UAS API - Outbound Reminder Sample Application

  • Filename:

    samples/outbound_reminder.py

    Description:

    An outbound application that makes a call to a destination address and says a text string and, optionally, plays a wav file. The destination address, text string and wav file name are supplied in outbound_parameters as a semi-colon delimited string. The wav file name is optional. This application requires that call_from is supplied in application_parameters, which is configured on the Outbound Services page.

    The channel.call() function is used to call the destination address. If the call is busy, the application waits for ten seconds and then tries again. The application will continue to try for a minute before raising an error exception.

    The application will check for a valid text to speak string and a valid wav file to play. It will use the TTS function channel.FilePlayer.say() to speak the string and channel.FilePlayer.play() to play the wav file.

    Code:

    """
        An outbound application that makes a call to a destination address and 
        says a text string and optionally plays a wav file. The destination 
        address, text string and wav file name are supplied in 
        outbound_parameters as a semi-colon separated list. The wav file name is 
        optional. 
        
        This application requires that call_from is supplied in 
        application_parameters, which is configured on the outbound service page of the CWP.
    
        For information on placing outbound calls please read the online 
        web services documentation.
    
        For additional information regarding outbound PSTN calls, please see the 
        online documentation.
    
        Also have a look at the invoke_outbound_service sample code in the 
        samples_ws directory.
        
        Actions:
            - place an outbound call
            - play tts
            - play a wav file
            - hang up
    
    """
    
    from prosody.uas import Hangup, Error
    import time
    
    __uas_version__  = "0.0.1"
    __uas_identify__ = "application"
    
    def main(channel, application_instance_id, file_man, my_log, application_parameters, outbound_parameters):
        return_code = 0
        try:
            # read outbound_parameters, we're expecting "destination_address;text_to_say;file_to_play"
            my_log.info("Outbound parameters: {0}".format(outbound_parameters))
            
            out_arg_splits = outbound_parameters.split(';')
            text_to_say = None
            file_to_play = None
            destination = out_arg_splits[0]
            # we expect call_from to be in application_parameters
            # call_from is used in CLI validation for PSTN calls
            call_from = application_parameters
            try:
                text_to_say = out_arg_splits[1]
                file_to_play = out_arg_splits[2]
            except:
                pass
            
            # Place an outbound call. If the destination is BUSY,
            # wait ten seconds and try again; try for one minute.
            endTime = time.time() + 60
    
            while channel.call(destination, call_from=call_from) != channel.State.ANSWERED:
                cause = channel.cause()
                if cause != channel.Cause.BUSY:
                    raise Error("Call destination returned cause {0}".format(cause))
                if time.time() > endTime:
                    raise Hangup("Call destination is busy.")
                time.sleep(10)
                continue
            
            my_log.info("Placed an outbound call") # log at info level
    
            # Play a wake-up call message
            if text_to_say is not None:
                cause = channel.FilePlayer.say(text_to_say)
                if cause != channel.FilePlayer.Cause.NORMAL:
                    raise Error("Say good morning failed: cause is {0}".format(cause)) # log at error level
                my_log.info("Played TTS") # log at info level
            else:
                my_log.info("No TTS to play") # log at info level
            
            # Play a recorded message
            if file_to_play is not None:
                cause = channel.FilePlayer.play(file_to_play, barge_in=True)
                if cause != channel.FilePlayer.Cause.NORMAL:
                    raise Error("Play message failed: cause is {0}".format(cause))            
                my_log.info("Played File") # log at info level
            else:
                my_log.info("No File to play") # log at info level
            
            channel.hang_up()
                
        except Hangup as exc:
            my_log.info("Hangup exception: {0}".format(exc))
             # in this app a hangup is not an error, return a positive value
            return_code = 100
            
        except Error as exc:
            # for error conditions return a negative value
            my_log.error("Error exception: {0}".format(exc))
            return_code = -101
            
        except Exception as exc:
            # an unexpected exception, return a negative value
            my_log.exception("Unexpected exception: {0}".format(exc))
            return_code = -102
            
        finally:
            if channel.state() != channel.State.IDLE:
                channel.hang_up()
        return return_code
    
  • Filename:

    Samples\C#\OutboundReminder\OutboundReminder.cs

    Description:

    Unlike the applicationParameters argument which is specified by the Outbound Service on the cloud associated with this application, the outboundParameters argument originates from the entity that invoked the Outbound Service.

    We use the String.Split() method to separate the outboundParameters text into arguments. The first three arguments are required. The first is the destination address to call, the second is the source address from which the call is to be made (also called the caller Id), the third is the text that is to be converted to audio using TTS and played to the call. The fourth parameter is optional and is the filename of the wav file to be played to the call.

    Note that the source address MUST be provided for PSTN destination addresses. In this case, the source address must have been validated and be listed on the Caller ID page (under the Manage menu option). For SIP destination addresses the source address MAY be provided.

    We use the channel.Call() method to make an outbound call to the destination address. If the call is answered we use channel.FilePlayer.Say() to perform TTS and subsequently channel.FilePlayer.Play() if required, to play the optional wav file to the call.

    Code:

    using System;
    using System.Threading;
    using AMSClassLibrary;
    using UASAppAPI;
    
    // An outbound application that makes a call to a destination address (passed in)
    // from a source address (passed in) and says a text string (also passed in) and 
    // optionally plays a wav file to that call.
    //
    // See the outbound calls documentation for your platform for information on setting 
    // the source address (it may need to be a validated caller Id).
    //
    // Requires:
    // [outboundParameters = destination address ; source address ; text to say ; filename(can be omitted)]
    //
    // e.g. 
    // outboundParameters = "sip:bob@bobscompany.com;;Time for your meeting"
    // or
    // outboundParameters = "441908081876;441908876543;Time for your meeting;alarm.wav"
    namespace OutboundReminder
    {
        // The application class.
        // 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 OutboundReminder : UASOutboundApplication
        {
            // Possible return codes
            enum ReturnCode
            {
                // Success Codes:
                Success = 0,
                // ... any positive integer
    
                // Fail Codes:
                // -1 to -99 reserved
                ExceptionThrown = -100,
                ArgumentError = -101
            }
    
            // This is the entry point for the application
            public override int Run(UASCallChannel channel,
                                    string applicationParameters, // not used 
                                    string outboundParameters)    // destination address ; source address ; text to say ; (filename)
            {
                this.Trace.TraceInfo("Start - appParms [{0}] outParms [{1}]",
                                   applicationParameters,
                                   outboundParameters);
                ReturnCode reply = ReturnCode.Success;
    
                // Check we have been given a destination address and some text to say
                string[] splits = outboundParameters.Split(';');
                if (splits.Length < 3)
                {
                    this.Trace.TraceError("This app requires a destination address, source address and some text to say, in the outboundParameters field");
                    return (int)ReturnCode.ArgumentError;
                }
                string destinationAddress = splits[0];
                string sourceAddress = splits[1];
                string textToSay = splits[2];
                string fileToPlay = (splits.Length >= 4) ? splits[3] : null;
    
                try
                {
                    // Make a call
                    CallState state = channel.Call(destinationAddress, sourceAddress);
                    if (state == CallState.Answered)
                    {
                        this.Trace.TraceInfo("Call answered");
    
                        this.Trace.TraceInfo("Saying text " + textToSay);
                        channel.FilePlayer.Say(textToSay);
    
                        if (!String.IsNullOrEmpty(fileToPlay))
                        {
                            this.Trace.TraceInfo("Playing file " + fileToPlay);
                            channel.FilePlayer.Play(fileToPlay);
                        }
                    }
                }
                catch (Exception except)
                {
                    this.Trace.TraceError("Exception thrown {0}", except.Message);
                    reply = ReturnCode.ExceptionThrown;
                }
                finally
                {
                    channel.HangUp();
                }
    
                this.Trace.TraceInfo("Completed");
                return (int)reply;
            }
        }
    }
  • Filename:

    Samples\VB\OutboundReminder\OutboundReminder.vb

    Description:

    Unlike the applicationParameters argument which is specified by the Outbound Service on the cloud associated with this application, the outboundParameters argument originates from the entity that invoked the Outbound Service.

    We use the String.Split() method to separate the outboundParameters text into arguments. The first three arguments are required. The first is the destination address to call, the second is the source address from which the call is to be made (also callled the caller Id), the third is the text that is to be converted to audio using TTS and played to the call. The fourth parameter is optional and is the filename of the wav file to be played to the call.

    Note that the source address MUST be provided for PSTN destination addresses. In this case, the source address must have been validated and be listed on the Caller ID page (under the Manage menu option). For SIP destination addresses the source address MAY be provided.

    We use the channel.Call() method to make an outbound call to the destination address. If the call is answered we use channel.FilePlayer.Say() to perform TTS and subsequently channel.FilePlayer.Play() if required, to play the optional wav file to the call.

    Code:

    Imports AMSClassLibrary
    Imports UASAppAPI
    
    ' An outbound application that makes a call to a destination address (passed in)
    ' from a source address (passed in) and says a text string (also passed in) and 
    ' optionally plays a wav file to that call.
    '
    ' See the outbound calls documentation for your platform for information on setting 
    ' the source address (it may need to be a validated caller Id).
    '
    ' Requires:
    ' [outboundParameters = destination address ; source address ; text to say ; filename(can be omitted)]
    '
    ' e.g. 
    ' outboundParameters = "sip:bob@bobscompany.com;;Time for your meeting"
    ' or
    ' outboundParameters = "441908081876;441908876543;Time for your meeting;alarm.wav"
    Namespace OutboundReminder
    
        ' The application class.
        ' 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 OutboundReminder
            Inherits UASOutboundApplication
    
            ' Possible return codes
            Enum ReturnCode
                ' Success Codes:
                Success = 0
                ' ... any positive integer
    
                ' Fail Codes:
                ' -1 to -99 reserved
                ExceptionThrown = -100
                ArgumentError = -101
            End Enum
    
            ' This is the entry point for the application
            ' applicationParameters - not used 
            ' outboundParameters -    destination address ; source address ; text to say ; (filename)
            Overrides Function Run(ByVal channel As UASCallChannel, _
                                   ByVal applicationParameters As String, _
                                   ByVal outboundParameters As String) _
                                   As Integer
    
                Me.Trace.TraceInfo("Start - appParms [{0}] outParms [{1}]", _
                                   applicationParameters, _
                                   outboundParameters)
                Dim reply As ReturnCode = ReturnCode.Success
    
                ' Check we have been given a destination address and some text to say
                Dim splits = outboundParameters.Split(";")
                If splits.Length < 3 Then
                    Me.Trace.TraceError("This app requires a destination address, source address and " + _
                                        "some text to say, in the outboundParameters field")
                    Return ReturnCode.ArgumentError
                End If
                Dim destinationAddress = splits(0)
                Dim sourceAddress = splits(1)
                Dim textToSay = splits(2)
                Dim fileToPlay = If((splits.Length >= 4), splits(3), "")
    
                Try
                    ' Make a call
                    Dim state = channel.Call(destinationAddress, sourceAddress)
                    If state = CallState.Answered Then
                        Me.Trace.TraceInfo("Call answered")
    
                        Me.Trace.TraceInfo("Saying text " + textToSay)
                        channel.FilePlayer.Say(textToSay)
    
                        If Not String.IsNullOrEmpty(fileToPlay) Then
                            Me.Trace.TraceInfo("Playing file " + fileToPlay)
                            channel.FilePlayer.Play(fileToPlay)
                        End If
                    End If
                Catch ex As Exception
                    Me.Trace.TraceError("Exception thrown {0}", ex.Message)
                    reply = ReturnCode.ExceptionThrown
                Finally
                    channel.HangUp()
                End Try
    
                Me.Trace.TraceInfo("Completed")
                Return reply
    
            End Function
    
        End Class
    
    End Namespace
  • Filename:

    Samples\F#\OutboundReminder\OutboundReminder.fs

    Description:

    Unlike the applicationParameters argument which is specified by the Outbound Service on the cloud associated with this application, the outboundParameters argument originates from the entity that invoked the Outbound Service.

    We use the String.Split() method to separate the outboundParameters text into arguments. The first three arguments are required. The first is the destination address to call, the second is the source address from which the call is to be made (also called the caller Id), the third is the text that is to be converted to audio using TTS and played to the call. The fourth parameter is optional and is the filename of the wav file to be played to the call.

    Note that the source address MUST be provided for PSTN destination addresses. In this case, the source address must have been validated and be listed on the Caller ID page (under the Manage menu option). For SIP destination addresses the source address MAY be provided.

    We use the channel.Call() method to make an outbound call to the destination address. If the call is answered we use channel.FilePlayer.Say() to perform TTS and subsequently channel.FilePlayer.Play() if required, to play the optional wav file to the call.

    Code:

    // An outbound application that makes a call to a destination address (passed in)
    // from a source address (passed in) and says a text string (also passed in) and 
    // optionally plays a wav file to that call.
    //
    // See the outbound calls documentation for your platform for information on setting 
    // the source address (it may need to be a validated caller Id).
    //
    // Requires:
    // [outboundParameters = destination address ; source address ; text to say ; filename(can be omitted)]
    namespace OutboundReminder
    
        open System
        open System.Threading
        open AMSClassLibrary
        open UASAppAPI
        open System.Threading
    
        // Possible return codes
        type ReturnCode =
            // Success Codes:
            | Success = 0
            // ... any positive integer
    
            // Fail Codes:
            // -1 to -99 reserved
            | ExceptionThrown = -100
            | ArgumentError = -101
    
        // The application class.
        // This must have the same name as the assembly and must inherit from either 
        // UASInboundApplication or UASOutboundApplication.
        // It must override the Run method.
        type OutboundReminder() = 
            inherit UASOutboundApplication()
    
            // This is the entry point for the application
            override obj.Run(channel:UASCallChannel, applicationParameters:string, outboundParameters:string) : int = 
                
                obj.Trace.TraceInfo("Started")
                let mutable reply = ReturnCode.Success
    
                // Check we have been given a destination address and some text to say
                let splits = outboundParameters.Split(';')
                if splits.Length < 3 then
                    obj.Trace.TraceError("This app requires a destination address, source address and " +
                                         "some text to say, in the outboundParameters field")
                    int ReturnCode.ArgumentError
                else
                    let destinationAddress = splits.[0]
                    let sourceAddress = splits.[1]
                    let textToSay = splits.[2]
                    let fileToPlay = if (splits.Length >= 4) then splits.[3] else ""
    
                    try
                        try
                            // Make a call
                            let state = channel.Call(destinationAddress, sourceAddress)
                            if state = CallState.Answered then
                                obj.Trace.TraceInfo("Call answered")
    
                                obj.Trace.TraceInfo("Saying text " + textToSay)
                                channel.FilePlayer.Say(textToSay) |> ignore
    
                                if not(String.IsNullOrEmpty(fileToPlay)) then
                                    obj.Trace.TraceInfo("Playing file " + fileToPlay)
                                    channel.FilePlayer.Play(fileToPlay) |> ignore
                        with
                            | _ as e->
                                obj.Trace.TraceError("Exception thrown {0}", e.Message)
                                reply <- ReturnCode.ExceptionThrown
                    finally
                        channel.HangUp() |> ignore
    
                    obj.Trace.TraceInfo("Completed")
                    int reply
    
    
  • Filename:

    Samples\C++\OutboundReminder\OutboundReminder.cpp

    Description:

    Unlike the applicationParameters argument which is specified by the Outbound Service on the cloud associated with this application, the outboundParameters argument originates from the entity that invoked the Outbound Service.

    We use the String->Split() method to separate the outboundParameters text into arguments. The first three arguments are required. The first is the destination address to call, the second is the source address from which the call is to be made (also called the caller Id), the third is the text that is to be converted to audio using TTS and played to the call. The fourth parameter is optional and is the filename of the wav file to be played to the call.

    Note that the source address MUST be provided for PSTN destination addresses. In this case, the source address must have been validated and be listed on the Caller ID page (under the Manage menu option). For SIP destination addresses the source address MAY be provided.

    We use the channel->Call() method to make an outbound call to the destination address. If the call is answered we use channel->FilePlayer->Say() to perform TTS and subsequently channel->FilePlayer->Play() if required, to play the optional wav file to the call.

    Code:

    // This is the main DLL file.
    
    #include "stdafx.h"
    #include "OutboundReminder.h"
    
    // An outbound application that makes a call to a destination address (passed in)
    // from a source address (passed in) and says a text string (also passed in) and 
    // optionally plays a wav file to that call.
    //
    // See the outbound calls documentation for your platform for information on setting 
    // the source address (it may need to be a validated caller Id).
    //
    // Requires:
    // [outboundParameters = destination address ; source address ; text to say ; filename(can be omitted)]
    //
    // e.g. 
    // outboundParameters = "sip:bob@bobscompany.com;;Time for your meeting"
    // or
    // outboundParameters = "441908081876;441908876543;Time for your meeting;alarm.wav"
    namespace OutboundReminder
    {
        // Possible return codes
        enum ReturnCode
        {
            // Success Codes:
            Success = 0,
            // ... any positive integer
    
            // Fail Codes:
            // -1 to -99 reserved
            ExceptionThrown = -100,
            ArgumentError = -101
        };
    
        // This is the entry point for the application
    	int OutboundReminder::Run(UASCallChannel^ channel, String^ applicationParameters, String^ outboundParameters)
    	{
    		this->Trace->TraceInfo("Started");
    		ReturnCode reply = Success;
    
            // Check we have been given a destination address and some text to say
    		array<String^>^ splits = outboundParameters->Split(';');
    		if (splits->Length < 3)
            {
                this->Trace->TraceError("This app requires a destination address, source address and some text to say, in the outboundParameters field");
    			return ArgumentError;
            }
            String^ destinationAddress = splits[0];
            String^ sourceAddress = splits[1];
            String^ textToSay = splits[2];
            String^ fileToPlay = (splits->Length >= 4) ? splits[3] : "";
    
    		array<String^>^ emptyCodecs = gcnew array<String^>(0);
    
    		try
    		{
                // Make a call
                CallState state = channel->Call(
    				destinationAddress, 
    				sourceAddress,
    				emptyCodecs,
    				60,
    				LiveSpeakerDetectionSettings::None,
    				0);
    			
    			if (state == CallState::Answered)
                {
                    this->Trace->TraceInfo("Call answered");
    
                    this->Trace->TraceInfo("Saying text " + textToSay);
                    channel->FilePlayer->Say(textToSay);
    
                    if (fileToPlay->Length != 0)
                    {
                        this->Trace->TraceInfo("Playing file " + fileToPlay);
                        channel->FilePlayer->Play(fileToPlay, false, nullptr);
                    }
                }
    
    		}
    		catch (Exception^ e)
    		{
    			this->Trace->TraceError("Exception thrown {0}", e->Message);
    			reply = ExceptionThrown;
    		}
    		finally
    		{
    			channel->HangUp();
    		}
    
    		this->Trace->TraceInfo("Completed");
    		return reply;
    	};
    }