UAS API - Outbound Reminder Sample Application

• Python
• C#
• VB
• F#
• C++/CLI

• 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;
  	};
  }