Transfer Menu | Aculab

UAS API - Transfer Menu Sample Application

Filename:

samples/transfer_menu.py

Description:

An inbound application that prompts the user to select a target to be transfered to. The target names (to be read out using TTS) and addresses (to be transfered to using the channel API) are given in application_parameters which is configured on the Inbound Services page. The target addresses must be other inbound services that have been registered on the Inbound Services page.

This example requires that application_parameters is a semi-colon delimited list in the format: <target name>,<target address>;<target name>,<target address> for example: join a conference,sip:AddToConfService@sip-0-2-0.aculab.com;listen to music,sip:InBoundMusic@sip-0-2-0.aculab.com This application requires one extra channel.

The application rings and answers the call, it then tries to get the extra channel. It then splits up the information in application_arguments to generate the transfer menu list. The application then uses TTS to prompt the caller for a menu choice. Finally, it uses the channel.transfer_to_inbound_service() function to transfer the caller to another inbound service. This function requires a reference to an extra channel.

The get_menu_selection() function has a loop which says each item in the transfer menu list, and then waits for a valid DTMF digit (one which corresponds to a transfer option). The transfer name and destination are returned by the function.

Code:

__uas_identify__ = "application"
__uas_version__ = "1.0b1"

from prosody.uas import Hangup, Error, PlayableMedia
from prosody.uas.highlevel import HighLevelCallChannel, HighLevelGrammar, HighLevelDigitInputOptions

"""
    An inbound application that prompts the user to select a target to be transferred to. 
    
    The target names and addresses - or phone numbers - are provided in application_parameters.
    These are set, during service registration, on the inbound service registration page at cloud.aculab.com.    

    The application_parameters must be a delimited string in the format: <name>, <address>; <name>, <address>
    
    For example:
    "Fred,sip:fred@place.com;Jack,sip:jack@place.com"

    The target names are used to create an automatic speech recognition (ASR) grammar.
    ASR is used to get the caller's choice and the call is then connected to the target address.
    
    A digit is associated with each name, and this can be entered on the telephone keypad instead of speaking.

    At application start, the target names are read out along with the associated digit.

    This application requires 1 extra channel.
    
    Actions:
        - wait for an inbound call
        - generate the transfer options menu
        - speak the options using TTS
        - listen for the caller's selection using ASR and DTMF
        - transfer the call

"""

def transfer_menu(application_parameters, my_log):
    # Split the application_parameters up into transfer options
    # (split with semicolon), and then again with commas. Return the 
    # data as a dictionary

    try:
        return dict(tuple(a.split(',')) for a in application_parameters.split(';'))
    except Exceptionas exc:
         my_log.error("The application parameters could not be parsed correctly: {0}".format(exc))
    return {}


def get_menu_selection(channel, transfer_list, my_log):

    channel.DTMFDetector.clear_digits()
    my_log.info("transfer_list: {0}".format(transfer_list))
    
    # create a speech recognition grammar of the IVR options
    my_grammar = HighLevelGrammar()
    my_grammar.create_from_alternatives(*transfer_list.keys())
    
    valid_digits = range(len(transfer_list))
    my_digit_options = HighLevelDigitInputOptions(valid_digits=''.join(map(str, valid_digits)))

    prompt_text = 'Please say the name of the person you want to call. Or press '
    for digit in valid_digits:
        # associate digits with the names
        prompt_text = prompt_text + "{0} for {1}, ".format(digit, transfer_list.keys()[digit])

    prompt = PlayableMedia(text_to_say=prompt_text, channel=channel)
    response = channel.capture_input(prompt, speech_recognition_grammar=my_grammar, 
                                  digit_input_options=my_digit_options)
    # if response is None, no valid input was detected
    if response is not None:
        # check whether we got speech or digits
        if response.type == response.Type.SPEECH:
            # return the name
            return response.input
        else:
            # return the name associated with the digit
            return transfer_list.keys()[int(response.input)]
    return None


def main(channel, application_instance_id, file_man, my_log, application_parameters):
    my_log.info("Transfer menu started")
    return_code = 0
    try:
        channel.ring(1)
        channel.answer()
        my_log.info("Call answered")

        # in this application, we will using the high level API wrapper
        # for the channel object
        high_level_channel = HighLevelCallChannel(channel, my_log)        
        try:
            # an extra channel is required, the number of extra channels
            # available is set on the service page
            out_channel = channel.ExtraChannel[0]
        except:
            raise Error("You need to register an extra channel for this application.")

        # Convert the application_parameters into a transfer menu list for later use
        transfer_list = transfer_menu(application_parameters)
        if not transfer_list:
            raise Error("Invalid transfer menu")
        
        # Prompt for digit
        channel.FilePlayer.say("Hello. ")
        target = get_menu_selection(high_level_channel, transfer_list, my_log)

        if not target:
            channel.FilePlayer.say("There is nobody to call.")
        else:
            # we will use the high level channel to place an outbound call and connect
            # the inbound and outbound calls together. If the target is a PSTN call
            # you will have to supply a call_from as well - please see the online documentation
            # on placing outbound PSTN calls.
            print("Calling {0}".format(target))
            if high_level_channel.call_and_connect(out_channel, call_to=transfer_list[target]) is False:
                channel.FilePlayer.say("I wasn't able to transfer you. Please try again later.")
                channel.hang_up()
            
        channel.wait_for_idle()

    except Hangup as exc:
        my_log.info("Got Hangup")
        return_code = 100

    except Error as exc:
        my_log.error("Got Error: {0}".format(exc))
        return_code = -101

    except Exception as exc:
        my_log.exception("Got unexpected exception: {0}".format(exc))
        return_code = -102

    finally:
        if channel.state() != channel.State.IDLE:
            channel.hang_up()
    return return_code

Filename:

Samples\C#\TransferMenu\TransferMenu.cs

Description:

This application first checks to ensure that the Inbound Service that invoked this application has allocated sufficient extra channels, by inspecting the channel.ExtraChannels array. Extra channels are required to make outbound calls in an inbound application and can be configured in the Inbound Service configuration. Once the check has been made, the application splits the applicationParameters into an array for further use.

The call is answered, a small TTS message is sent to the user and then the GetMenuSelection() method is called. This method will prompt the user for a DTMF tone after giving a list of the transfer options. We use the channel.DtmfDetector.GetDigits() method to grab a single keypad press and then make sure the returned item is in our list of transfer options. This loop will continue until either a valid keypress has been detected, or the user hangs up.

To transfer the call, we use the channel.TransferToInboundService() method. We specify the target address and the extra channel to use for the transfer. The function returns a boolean value indicating if the transfer attempt was successful. This transfer method uses the retrievable transfer mechanism and therefore we must maintain the state of the original channel to allow the transferred call to continue. So we wait for the transferred call to be hung up before terminating.

Code:

using System;
using System.Threading;
using System.Collections.Generic;
using AMSClassLibrary;
using UASAppAPI;

// An inbound application that prompts the user to select a target inbound service 
// to be transferred to. A prompt (to be read out) and service name (to be transferred to) 
// for each possible target need to be listed in the applicationParameters when
// this service is registered.
//
// Note: this sample will only run on platforms that support Transfer.
//
// Requires:
// [applicationParameters = semicolon delimited list of <action>,<service name<
//      e.g. "join a conference,AddToConference;
//            listen to media file,InboundPlayWav"]
// [1 extra channel]
namespace TransferMenu
{
    // The application class.join a 
    // This must have the same name as the assembly and must inherit from either 
    // UASInboundApplication or UASOutboundApplication.
    // It must override the Run method.
    public class TransferMenu : UASInboundApplication
    {
        // Possible return codes
        enum ReturnCode
        {
            // Success Codes:
            Success = 0,
            // ... any positive integer

            // Fail Codes:
            // -1 to -99 reserved
            ExceptionThrown = -100,
            NotSufficientExtraChannels = -101,
            NotSufficientDestinations = -102
        }

        // A class to represent each of the menu options
        class TransferTarget
        {
            public TransferTarget(string entry, int key)
            {
                string[] details = entry.Split(',');
                if (details.Length != 2)
                {
                    throw new ArgumentException("Invalid destination details", "applicationParameters");
                }
                Prompt = details[0].Trim();
                ServiceName = details[1].Trim();
                Key = key;
            }
            public string Prompt;
            public string ServiceName;
            public int Key;
        }

        // This is the entry point for the application
        public override int Run(UASCallChannel channel,
                                string applicationParameters)
        {
            this.Trace.TraceInfo("Started");
            ReturnCode reply = ReturnCode.Success;
            bool primaryCallHungUp = false;

            // Check we've got an extra Channel
            if (channel.ExtraChannels.Length < 1)
            {
                this.Trace.TraceWarning("Needs 1 extra channel to be configured");
                return (int)ReturnCode.NotSufficientExtraChannels;
            }
            UASCallChannel targetChannel = channel.ExtraChannels[0];

            try
            {
                // Decipher the applicationParameters
                string[] entries = applicationParameters.Split(';');
                if (entries.Length < 1)
                {
                    this.Trace.TraceWarning("Needs at least 1 transfer target to be configured");
                    return (int)ReturnCode.NotSufficientDestinations;
                }
                List<TransferTarget> targets = new List<TransferTarget>(entries.Length);
                int key = 0;
                foreach (string entry in entries)
                {
                    targets.Add(new TransferTarget(entry, key++));
                }

                // The selected target
                TransferTarget target = null;

                // Answer the call
                CallState state = channel.Answer();
                if (state != CallState.Answered)
                {
                    primaryCallHungUp = true;
                }

                if (!primaryCallHungUp)
                {
                    this.Trace.TraceInfo("Call answered");

                    // Prompt for a digit
                    channel.FilePlayer.Say("Hello.");
                    target = getMenuSelection(channel, targets);
                    if (target == null)
                    {
                        primaryCallHungUp = true;
                    }
                }

                if (!primaryCallHungUp)
                {
                    // Transfer to that target
                    channel.FilePlayer.Say("Transferring to {0}", target.Prompt);
                    state = channel.TransferToInboundService(
                                                target.ServiceName,
                                                targetChannel);

                    if (state != CallState.Transferred)
                    {
                        channel.FilePlayer.Say("I wasn't able to transfer you.");
                        channel.FilePlayer.Say("Please try again later.");
                    }
                    else
                    {
                        // Wait for transferree or far end to hangup 
                        channel.WaitForTransferredCallRetrieved(Timeout.Infinite);
                    }
                }
            }
            catch (Exception e)
            {
                this.Trace.TraceError("Exception thrown {0}", e.Message);
                reply = ReturnCode.ExceptionThrown;
            }
            finally
            {
                channel.HangUp();
            }

            this.Trace.TraceInfo("Completed");
            return (int)reply;
        }

        TransferTarget getMenuSelection(UASCallChannel channel, List<TransferTarget> targets)
        {
            // Prepare to receive digits
            channel.DtmfDetector.ClearDigits();

            // Get the target selected
            do
            {
                // Play the transfer options to the caller with bargein
                foreach (TransferTarget target in targets)
                {
                    string msg = string.Format("Press {0} to {1}", target.Key, target.Prompt);
                    FilePlayerCause cause = channel.FilePlayer.Say(msg, true);
                    if (cause == FilePlayerCause.HangUp)
                    {
                        return null;
                    }
                    if (cause == FilePlayerCause.BargeIn)
                    {
                        break;
                    }
                }

                string digits;
                channel.DtmfDetector.GetDigits(1, out digits, 10);
                if (channel.DtmfDetector.Cause == DtmfDetectorCause.Count)
                {
                    // Get the transfer target
                    int keyPressed = Convert.ToInt32(digits);
                    this.Trace.TraceInfo("Got keypress {0}", keyPressed);
                    if (keyPressed < targets.Count)
                    {
                        return targets[keyPressed];
                    }
                    channel.FilePlayer.Say("Selection not valid.");
                }
            } while (channel.DtmfDetector.Cause != DtmfDetectorCause.HangUp);

            // returning null on hangup
            return null;
        }
    }
}

Filename:

Samples\VB\TransferMenu\TransferMenu.vb

Description:

This application first checks to ensure that the Inbound Service that invoked this application has allocated sufficient extra channels, by inspecting the channel.ExtraChannels array. Extra channels are required to make outbound calls in an inbound application and can be configured in the Inbound Service configuration. Once the check has been made, the application splits the applicationParameters into an array for further use.

The call is answered, a small TTS message is sent to the user and then the GetMenuSelection() method is called. This method will prompt the user for a DTMF tone after giving a list of the transfer options. We use the channel.DtmfDetector.GetDigits() method to grab a single keypad press and then make sure the returned item is in our list of transfer options. This loop will continue until either a valid keypress has been detected, or the user hangs up.

To transfer the call, we use the channel.TransferToInboundService() method. We specify the target address and the extra channel to use for the transfer. The function returns a boolean value indicating if the transfer attempt was successful. This transfer method uses the retrievable transfer mechanism and therefore we must maintain the state of the original channel to allow the transferred call to continue. So we wait for the transferred call to be hung up before terminating.

Code:

Imports System.Collections.Generic
Imports AMSClassLibrary
Imports UASAppAPI

' An inbound application that prompts the user to select a target inbound service 
' to be transferred to. A prompt (to be read out) and service name (to be transferred to) 
' for each possible target need to be listed in the applicationParameters when
' this service is registered.
'
' Note: this sample will only run on platforms that support Transfer.
'
' Requires:
' [applicationParameters = semicolon delimited list of <action>,<service name>
'      e.g. "join a conference,AddToConference;listen to media file,InboundPlayWav"]
' [1 extra channel]
Namespace TransferMenu

    Public Class TransferMenu
        Inherits UASInboundApplication

        ' Possible return codes
        Enum ReturnCode
            ' Success Codes:
            Success = 0
            ' ... any positive integer

            ' Fail Codes:
            ' -1 to -99 reserved
            ExceptionThrown = -100
            NotSufficientExtraChannels = -101
            NotSufficientDestinations = -102
        End Enum

        ' A class to represent each of the menu options
        Class TransferTarget
            Public Sub New(ByVal entry As String, _
                           ByVal keyin As Integer)
                Dim details = entry.Split(",")
                If details.Length <> 2 Then
                    Throw New ArgumentException("Invalid destination details", "applicationParameters")
                End If
                Prompt = details(0).Trim()
                ServiceName = details(1).Trim()
                Key = keyin
            End Sub

            Public Prompt As String
            Public ServiceName As String
            Public Key As Integer
        End Class

        ' This is the entry point for the application
        Overrides Function Run(ByVal channel As UASCallChannel, _
                               ByVal applicationParameters As String) _
                               As Integer

            Me.Trace.TraceInfo("Started")

            Dim reply = ReturnCode.Success
            Dim primaryCallHungUp = False

            ' Check we've got an extra Channel
            If channel.ExtraChannels.Length < 1 Then
                Me.Trace.TraceWarning("Needs 1 extra channel to be configured")
                Return ReturnCode.NotSufficientExtraChannels
            End If

            Dim targetChannel = channel.ExtraChannels(0)

            Try
                ' Decipher the applicationParameters
                Dim entries = applicationParameters.Split(";")
                If entries.Length < 1 Then
                    Me.Trace.TraceWarning("Needs at least 1 transfer target to be configured")
                    Return ReturnCode.NotSufficientDestinations
                End If

                Dim targets = New List(Of TransferTarget)
                Dim key = 0
                For Each entry In entries
                    targets.Add(New TransferTarget(entry, key))
                    key += 1
                Next

                ' The selected target
                Dim target As TransferTarget = Nothing

                ' Answer the call
                Dim state = channel.Answer()
                If state <> CallState.Answered Then
                    primaryCallHungUp = True
                End If

                If Not primaryCallHungUp Then
                    Me.Trace.TraceInfo("Call answered")

                    ' Prompt for a digit
                    channel.FilePlayer.Say("Hello.")
                    target = getMenuSelection(channel, targets)
                    If target Is Nothing Then
                        primaryCallHungUp = True
                    End If
                End If

                If Not primaryCallHungUp Then
                    ' Transfer to that target
                    channel.FilePlayer.Say("Transferring to {0}", target.Prompt)
                    state = channel.TransferToInboundService(target.ServiceName, targetChannel)

                    If state <> CallState.Transferred Then
                        channel.FilePlayer.Say("I wasn't able to transfer you.")
                        channel.FilePlayer.Say("Please try again later.")
                    Else
                        ' Wait for transferree or far end to hangup 
                        channel.WaitForTransferredCallRetrieved(Timeout.Infinite)
                    End If
                End If
            Catch e As Exception
                Me.Trace.TraceError("Exception thrown {0}", e.Message)
                reply = ReturnCode.ExceptionThrown
            Finally
                channel.HangUp()
            End Try

            Me.Trace.TraceInfo("Completed")
            Return reply

        End Function

        Function getMenuSelection(ByVal channel As UASCallChannel, ByVal targets As List(Of TransferTarget)) As TransferTarget
            ' Prepare to receive digits
            channel.DtmfDetector.ClearDigits()

            ' Get the target selected
            Do
                ' Play the transfer options to the caller with bargein
                For Each target In targets
                    Dim msg = String.Format("Press {0} to {1}", target.Key, target.Prompt)
                    Dim cause = channel.FilePlayer.Say(msg, True)
                    If cause = FilePlayerCause.HangUp Then
                        Return Nothing
                    End If
                    If cause = FilePlayerCause.BargeIn Then
                        Exit Do
                    End If
                Next

                Dim digits As String = ""
                channel.DtmfDetector.GetDigits(1, digits, 10)
                If channel.DtmfDetector.Cause = DtmfDetectorCause.Count Then
                    ' Get the transfer target
                    Dim keyPressed = Convert.ToInt32(digits)
                    Me.Trace.TraceInfo("Got keypress {0}", keyPressed)
                    If keyPressed < targets.Count Then
                        Return targets(keyPressed)
                    End If
                    channel.FilePlayer.Say("Invalid selection.")
                End If
            Loop While channel.DtmfDetector.Cause <> DtmfDetectorCause.HangUp

            ' returning null on hangup
            Return Nothing
        End Function

    End Class

End Namespace