Inbound With TTS

UAS API - Inbound With Tts Sample Application

Filename:

samples/inbound_with_tts.py

Description:

An application that answers an inbound call and speaks some TTS. After ringing and answering the channel, the channel.FilePlayer.say() function is used to speak the text by converting the given text string into voice data. The process is known as Text-To-Speech (TTS).

The text to be spoken is passed to the application via the application_parameters variable which is configured on the Inbound Services page (Manage -> Inbound Services). The say function will block until the text has been spoken, and then the call will hang up.

Code:

# -*- coding: utf-8 -*-
"""
A simple application that answers an inbound call and speaks some TTS.
The TTS to say is passed in through application_parameters, which is
configured on the inbound services page of the CWP. In addition, this
sample will speak the current date and time.

    Actions:
        - check the channel state
        - ring and answer
        - play some tts - provided in application_parameters
        - say the date and time
        - 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):
    return_code = 0
    try:
        # check the incoming channel state
        state = channel.state()
        if state == channel.State.CALL_INCOMING:
            state = channel.ring()   # this can raise a Hangup exception
            if state == channel.State.RING_INCOMING:
                state = channel.answer() # this can raise a Hangup exception
        else:
            raise Hangup('No inbound call, state is {0}'.format(state))
        if state != channel.State.ANSWERED:
            raise Hangup('Failed to answer inbound call, state is {0}'.format(state))
        
        my_log.info("Answered an inbound call") # log at info level

        # Say a TTS prompt, the text is provided in application_parameters.
        # This will use the default TTS engine and voice.
        # Note that if your application_parameters contains Unicode characters, 
        # you may need to call an appropriate encode function here
        cause = channel.FilePlayer.say(application_parameters)
        if cause != channel.FilePlayer.Cause.NORMAL:
            raise Error("Say hello failed: cause is {0}".format(cause))

        # Now say the date and the time.
        # You can use SSML tags to select a different TTS engine and voice. 
        # The engines and voices available may depend on your account settings.
        # SSML is also used to change the way the text is spoken. 
        # See the online documentation for more information on SSML.
        # Here we use SSML tags to specify some text as a date and time.
        
        # Create a date string in the format year-month-day.
        date = time.strftime("%Y/%m/%d", time.localtime(time.time()))
        
        # Inform the TTS engine that the string should be spoken as a date.
        cause = channel.FilePlayer.say("The date is <say-as interpret-as='date' format='ymd'>{0}</say-as>".format(date))

        # Create a time string in the format hours-minutes-seconds
        timestr = time.strftime("%H:%M:%S", time.localtime(time.time()))

        # Inform the TTS engine that the string should be spoken as a time.
        cause = channel.FilePlayer.say("The time is <say-as interpret-as='time' format='hms24'>{0}</say-as>".format(timestr))

        if cause != channel.FilePlayer.Cause.NORMAL:
            raise Error("TTS player returned {0}: expected {1}".format(cause, channel.FilePlayer.Cause.NORMAL))
        
        # Bye bye, using the default settings.
        cause = channel.FilePlayer.say("Bye bye.")
        if cause != channel.FilePlayer.Cause.NORMAL:
            raise Error("Say bye bye failed: cause is {0}".format(cause))
        
    except Hangup as exc:
        my_log.info("Hangup exception reports: {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 reports: {0}".format(exc))
        return_code = -101
        
    except Exception as exc:
        # an unexpected exception, return a negative value
        my_log.exception("Unexpected exception reports: {0}".format(exc))
        return_code = -102
        
    finally:
        if channel.state() != channel.State.IDLE:
            channel.hang_up()

    return return_code

Filename:

Samples\C#\InboundWithTTS\InboundWithTTS.cs

Description:

First we ring and answer the call. Then we check the applicationParameters for some text with which to generate audio on the call. The applicationParameters argument is passed to our application by the UAS which receives it from the cloud. This argument is set in the Modify Existing Inbound Service page for the service that invoked our application.

After text manipulation, we say the text using channel.FilePlayer.Say(), which converts the given text into audio using Text-To-Speech (TTS). Finally, we hang up the call using channel.HangUp().

Code:

using System;
using AMSClassLibrary;
using UASAppAPI;

// An inbound application that says some text (passed in) to the
// caller followed by the current date and time then hangs up.
//
// Requires:
// [applicationParameters = the text to say]
namespace InboundWithTTS
{
    // 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 InboundWithTTS : UASInboundApplication
    {
        enum ReturnCode
        {
            // Success Codes:
            Success = 0,
            // ... any positive integer

            // Fail Codes:
            // -1 to -99 reserved
            ExceptionThrown = -100,
            PlayInterrupted = -101
        }

        // This is the entry point for the application
        public override int Run(UASCallChannel channel, string applicationParameters)
        {
            this.Trace.TraceInfo("Start - appParms [{0}]", applicationParameters);
            ReturnCode reply = ReturnCode.Success;

            try
            {
                // Ring for 2 seconds
                channel.Ring(2);

                // Answer the call
                CallState state = channel.Answer();
                if (state == CallState.Answered)
                {
                    this.Trace.TraceInfo("Answered");

                    if (applicationParameters.Length == 0)
                    {
                        applicationParameters = "no text was provided to say.";
                    }
                    
                    // Say the current date and the time 
                    // in the default TTS engine and voice.

                    // This uses SSML tags to determine the way the text is spoken. 
                    // See /documents/tts on your platform for more information on SSML.
                    DateTime now = DateTime.Now.ToLocalTime();

                    // Create TTS date text with SSML tags that specify how the date should be spoken.
                    string ttsDate = String.Format(
                        "<say-as interpret-as='date' format='dmy'>{0:dd/MM/yyyy}</say-as>",
                        now);

                    // Create TTS time text with SSML tags that specify how the time should be spoken.
                    string ttsTime = String.Format(
                        "<say-as interpret-as='time' format='hms24'>{0:HH:mm:ss}</say-as>",
                        now);

                    // Say the date 
                    FilePlayerCause playCause = channel.FilePlayer.Say(
                        "The current date is {0} and the time is {1}",
                            ttsDate,
                            ttsTime);
                    if (FilePlayerCause.Normal != playCause)
                    {
                        this.Trace.TraceError("Say failed or was interrupted");
                        reply = ReturnCode.PlayInterrupted;
                    }
                    else
                    {
                        // Now say the text provided in the application Parameters 
                        // field of the calling service using TTS.
                        playCause = channel.FilePlayer.Say(applicationParameters);
                        if (FilePlayerCause.Normal != playCause)
                        {
                            this.Trace.TraceError("Say failed or was interrupted");
                            reply = ReturnCode.PlayInterrupted;
                        }
                        else
                        {
                            // Say Goodbye using the default voice
                            channel.FilePlayer.Say("Goodbye.");
                        }
                    }

                    // Ensure the call is hung up.
                    channel.HangUp();
                }
            }
            catch (Exception e)
            {
                this.Trace.TraceError("Exception caught: {0}", e.Message);
                reply = ReturnCode.ExceptionThrown;
            }

            this.Trace.TraceInfo("Completed with return code {0}", reply);
            return (int)reply;
        }
    }
}

Filename:

Samples\VB\InboundWithTTS\InboundWithTTS.vb

Description:

First we ring and answer the call. Then we check the applicationParameters for some text with which to generate audio on the call. The applicationParameters argument is passed to our application by the UAS which receives it from the cloud. This argument is set in the Modify Existing Inbound Service page for the service that invoked our application.

After text manipulation, we say the text using channel.FilePlayer.Say(), which converts the given text into audio using Text-To-Speech (TTS). Finally, we hang up the call using channel.HangUp().

Code:

Imports AMSClassLibrary
Imports UASAppAPI

' An inbound application that says some text (passed in) to the
' caller followed by the current date and time then hangs up.
'
' Requires:
' [applicationParameters = the text to say]
Namespace InboundWithTTS

    ' 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 InboundWithTTS
        Inherits UASInboundApplication

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

            ' Fail Codes:
            ' -1 to -99 reserved
            ExceptionThrown = -100
            PlayInterrupted = -101
        End Enum

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

            Me.Trace.TraceInfo("Start - appParms [{0}]", applicationParameters)
            Dim reply As ReturnCode = ReturnCode.Success

            Try
                ' Ring for 2 seconds
                channel.Ring(2)

                ' Answer the call
                Dim state As CallState
                state = channel.Answer()

                If state = CallState.Answered Then

                    Me.Trace.TraceInfo("Call answered")

                    If String.IsNullOrEmpty(applicationParameters) Then
                        applicationParameters = "No text was provided to play"
                    End If

                    ' Say the current date and the time 
                    ' in the default TTS engine and voice.

                    ' This uses SSML tags to determine the way the text is spoken. 
                    ' See /documents/tts on your platform for more information on SSML.

                    ' Create TTS date text with SSML tags that specify how the date should be spoken.
                    Dim now = DateTime.Now.ToLocalTime()
                    Dim ttsDate = String.Format( _
                        "<say-as interpret-as='date' format='dmy'>{0:dd/MM/yyyy}</say-as>", _
                        now)

                    ' Create TTS time text with SSML tags that specify how the time should be spoken.
                    Dim ttsTime = String.Format( _
                        "<say-as interpret-as='time' format='hms24'>{0:HH:mm:ss}</say-as>", _
                        now)

                    ' Say the date 
                    Dim playCause = channel.FilePlayer.Say( _
                        "The current date is {0} and the time is {1}", _
                            ttsDate, _
                            ttsTime)
                    If FilePlayerCause.Normal <> playCause Then
                        Me.Trace.TraceError("Say failed or was interrupted")
                        reply = ReturnCode.PlayInterrupted
                    Else
                        ' Now say the text provided in the application Parameters 
                        ' field of the calling service using TTS.
                        playCause = channel.FilePlayer.Say(applicationParameters)
                        If FilePlayerCause.Normal <> playCause Then
                            Me.Trace.TraceError("Say failed or was interrupted")
                            reply = ReturnCode.PlayInterrupted
                        Else
                            ' Say Goodbye using the default voice
                            channel.FilePlayer.Say("Goodbye.")
                        End If
                    End If

                    ' Ensure the call is hung up.
                    channel.HangUp()
                End If

            Catch ex As Exception
                Me.Trace.TraceError("Exception thrown {0}", ex.Message)
                reply = ReturnCode.ExceptionThrown
            End Try

            Me.Trace.TraceInfo("Completed with return code {0}", reply)
            Return reply

        End Function

    End Class

End Namespace

Filename:

Samples\F#\InboundWithTTS\InboundWithTTS.fs

Description:

First we ring and answer the call. Then we check the applicationParameters for some text with which to generate audio on the call. The applicationParameters argument is passed to our application by the UAS which receives it from the cloud. This argument is set in the Modify Existing Inbound Service page for the service that invoked our application.

After text manipulation, we say the text using channel.FilePlayer.Say(), which converts the given text into audio using Text-To-Speech (TTS). Finally, we hang up the call using channel.HangUp().

Code:

// An inbound application that says some text (passed in) to the
// caller then hangs up.
//
// Requires:
// [applicationParameters = the text to say]
namespace InboundWithTTS

    open System
    open System.Threading
    open AMSClassLibrary
    open UASAppAPI

    // Possible return codes
    type ReturnCode =
        // Success Codes:
        | Success = 0
        // ... any positive integer

        // Fail Codes:
        // -1 to -99 reserved
        | ExceptionThrown = -100
        | PlayInterrupted = -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 InboundWithTTS() = 
        inherit UASInboundApplication()

        // This is the entry point for the application
        override obj.Run(channel:UASCallChannel, applicationParameters:string) : int = 
            
            obj.Trace.TraceInfo("In - appParms [{0}]", applicationParameters)
            let mutable reply = ReturnCode.Success

            try
                // Ring for 2 seconds
                channel.Ring(2) |> ignore

                // Answer the call
                if channel.Answer() = CallState.Answered then

                    obj.Trace.TraceInfo("Call answered")

                    if applicationParameters.Length = 0 then
                        channel.FilePlayer.Say("no text was provided to say.") |> ignore
                    elif channel.FilePlayer.Say(applicationParameters) <> FilePlayerCause.Normal then
                        obj.Trace.TraceError("Play failed or was interrupted")
                        reply <- ReturnCode.PlayInterrupted

                    channel.HangUp() |> ignore
            with 
                | _ as e -> 
                    obj.Trace.TraceError("Exception caught {0}", e.Message)
                    reply <- ReturnCode.ExceptionThrown

                
            obj.Trace.TraceInfo("Completed")
            (int)reply