UAS API - Pin Input Sample Application

  • Filename:

    samples/pin_input.py

    Description:

    An inbound application that prompts the caller to enter a 4 digit pin. After ringing and answering an inbound call, the application uses TTS to ask for a four digit PIN using channel.FilePlayer.say(). The channel.DTMFDectector.get_digits() function is used to collect the DTMF digits. The count argument indicates the number of digits to collect, and the seconds_predigits_timeout argument specifies how long to wait for the first key press before timing out.

    The DTMF detector return cause is checked by using the channel.DTMFDetector.cause() function. In this case, if the correct number of digits were entered, TTS is use to play back the digits that were collected; otherwise an error message is spoken.

    Code:

    """
        An inbound application that prompts the caller to enter a 4 digit pin. 
        It waits at most 30 seconds for the caller to begin entering digits, then replays 
        the digits to the caller before hanging up.
    """
    
    from prosody.uas import Hangup, Error
    
    __uas_identify__ = "application"
    __uas_version__  = "1.0b2"
    
    def main(channel, application_instance_id, file_man, my_log, application_parameters):
        return_code = 0
        try:
            if channel.state() == channel.State.CALL_INCOMING:
                channel.ring()   # this can raise a Hangup exception
                channel.answer() # this can raise a Hangup exception
            else:
                raise Hangup('No inbound call')
    
            channel.FilePlayer.say("Please enter a four digit pin.", barge_in = True)
    
            # wait at most 30 seconds for the caller to begin entering digits
            digits = channel.DTMFDetector.get_digits(count=4, seconds_predigits_timeout = 30)
    
            if channel.DTMFDetector.cause() == channel.DTMFDetector.Cause.COUNT:
                channel.FilePlayer.say("The digits you entered are, {0}".format(", ".join(digits)))
            else:
                channel.FilePlayer.say ("No digits received. Hanging up.")
                return_code = -103
    
        except Hangup as exc:
            my_log.info("Got Hangup: {0}".format(exc))
            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\UASApplications\PinInput\src\main\java\com\aculab\uas\app\PinInput.java

    Description:

    Once the call is answered with channel.answer(), we use TTS to prompt for a four digit PIN code. channel.getDtmfDetector() can obtain the digits entered by the caller for us, using the getDigits() method. The specific overload used requires the expected number of digits and a timeout value (here it is 30 seconds) and returns a string in which the detected digits are stored . The cause value indicates why the method returned. The DtmfDetectorCause.Count cause signifies that the expected count of digits were detected.

    The code then responds to the caller with the digits entered. Note that the text has some formatting to ensure that TTS reads it in a natural manner. The call is then disconnected using the channel.hangUp() method.

    Code:

    package com.aculab.uas.app;
    
    // An inbound application that answers a call, prompts for the caller to 
    // enter a 4 digit pin code. It waits for 30 seconds for 4 digits to be entered 
    // and then replays them to the caller before hanging up.
    import com.aculab.amsapi.*;
    import com.aculab.uasapi.*;
    
    // The application class.
    // This must extend either UASInboundApplication or UASOutboundApplication and
    // override the run method.
    // It must be packaged in a jar file of the same name together with a manifest file.
    public class PinInput extends UASInboundApplication
    {
        // Success Codes:
        final int Success = 0;
        // ... any positive integer
    
        // Fail Codes:
        // -1 to -99 reserved
        final int ExceptionThrown = -100;
    
    
        // This is the entry point for the application
        @Override 
        public int run(UASCallChannel channel,
                       String applicationParameters)
            throws Exception
        {
            this.getTrace().traceInfo("Start - appParms [%s]", applicationParameters);
            int returnCode = Success;
    
            try
            {
                // Answer the call
                CallState state = channel.answer();
                if (state == CallState.Answered)
                {
                    // Prompt to enter a pin allowing bargein
                    String prompt = "Please enter a four digit pin code.";
                    channel.getFilePlayer().say(prompt, true);
    
                    // Wait for 30 seconds for four digits
                    String digits = channel.getDtmfDetector().getDigits(4, 30);
                    DtmfDetectorCause cause = channel.getDtmfDetector().getCause();
                    if (cause == DtmfDetectorCause.Count)
                    {
                        channel.getFilePlayer().say(
                                "The pin code you entered was <say-as interpret-as='vxml:digits'>%s</say-as>",
                                digits);
                    }
    
                    channel.getFilePlayer().say("Goodbye.");
                }
            }
            catch (Exception e)
            {
                this.getTrace().traceError("Exception thrown %s", e.getMessage());
                returnCode = ExceptionThrown;
            }
            finally
            {
                // Ensure call is hung up
                channel.hangUp();
            }
    
            this.getTrace().traceInfo("Completed with return code %d", returnCode);
            return returnCode;
        }
    }
    
  • Filename:

    Samples\C#\PinInput\PinInput.cs

    Description:

    Once the call is answered with channel.Answer(), we use TTS to prompt for a four digit PIN code. The channel.DtmfDetector can obtain the digits entered by the caller for us, using the GetDigits() method. The specific overload used requires the expected number of digits, an output string in which the resultant digits are stored and a timeout value of 30 seconds. The method returns a cause value indicating why the method returned. The DtmfDetectorCause.Count cause signifies that the expected count of digits were detected.

    The code then responds to the caller with the digits entered. Note that the text has some formatting to ensure that TTS reads it in a natural manner. The call is then disconnected using the channel.HangUp() method.

    Code:

    using System;
    using System.Threading;
    using AMSClassLibrary;
    using UASAppAPI;
    
    // An inbound application that answers a call, prompts for the caller to 
    // enter a 4 digit pin code. It waits for 30 seconds for 4 digits to be entered 
    // and then replays them to the caller before hanging up.
    namespace PinInput
    {
        // 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 PinInput : UASInboundApplication
        {
            // Possible return codes
            enum ReturnCode
            {
                // Success Codes:
                Success = 0,
                // ... any positive integer
    
                // Fail Codes:
                // -1 to -99 reserved
                ExceptionThrown = -100
            }
    
            // This is the entry point for the application
            public override int Run(UASCallChannel channel,
                                    string applicationParameters)
            {
                this.Trace.TraceInfo("Started");
                ReturnCode reply = ReturnCode.Success;
    
                try
                {
                    // Answer the call
                    CallState state = channel.Answer();
                    if (state == CallState.Answered)
                    {
                        // Prompt to enter a pin, allowing bargein
                        channel.FilePlayer.Say("Please enter a four digit pin code.", true);
    
                        // Wait for 30 seconds for four digits
                        string digits;
                        DtmfDetectorCause cause = channel.DtmfDetector.GetDigits(4, out digits, 30);
                        if (cause == DtmfDetectorCause.Count)
                        {
                            channel.FilePlayer.Say(
                        		"The pin code you entered was <say-as interpret-as='vxml:digits'>{0}</say-as>",
                        		digits);
                        }
    
                        channel.FilePlayer.Say("Goodbye.");
                    }
                }
                catch (Exception e)
                {
                    this.Trace.TraceError("Exception thrown {0}", e.Message);
                    reply = ReturnCode.ExceptionThrown;
                }
                finally
                {
                    channel.HangUp();
                }
    
                this.Trace.TraceInfo("Completed");
                return (int)reply;
            }
        }
    }
  • Filename:

    Samples\VB\PinInput\PinInput.vb

    Description:

    Once the call is answered with channel.Answer(), we use TTS to prompt for a four digit PIN code. The channel.DtmfDetector can obtain the digits entered by the caller for us, using the GetDigits() method. The specific overload used requires the expected number of digits, an output string in which the resultant digits are stored and a timeout value of 30 seconds. The method returns a cause value indicating why the method returned. The DtmfDetectorCause.Count cause signifies that the expected count of digits were detected.

    The code then responds to the caller with the digits entered. Note that the text has some formatting to ensure that TTS reads it in a natural manner. The call is then disconnected using the channel.HangUp() method.

    Code:

    Imports AMSClassLibrary
    Imports UASAppAPI
    
    ' An inbound application that answers a call, prompts for the caller to 
    ' enter a 4 digit pin code. It waits for 30 seconds for 4 digits to be entered 
    ' and then replays them to the caller before hanging up.
    Namespace PinInput
    
        ' 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 PinInput
            Inherits UASInboundApplication
    
            ' Possible return codes
            Enum ReturnCode
                ' Success Codes:
                Success = 0
                ' ... any positive integer
    
                ' Fail Codes:
                ' -1 to -99 reserved
                ExceptionThrown = -100
            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("Started")
                Dim reply As ReturnCode = ReturnCode.Success
    
                Try
                    ' Answer the call
                    Dim state As CallState
                    state = channel.Answer()
    
                    If state = CallState.Answered Then
    
                        ' Prompt to enter a pin
                        channel.FilePlayer.Say("Please enter a four digit pin code.")
    
                        ' Wait for 30 seconds for four digits
                        Dim digits As String = ""
                        Dim cause = channel.DtmfDetector.GetDigits(4, digits, 30)
                        If cause = DtmfDetectorCause.Count Then
                            channel.FilePlayer.Say("The pin code you entered was {0}, {1}, {2}, {3}", _
                                digits(0), _
                                digits(1), _
                                digits(2), _
                                digits(3))
                        End If
    
                        channel.FilePlayer.Say("Goodbye.")
                    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#\PinInput\PinInput.fs

    Description:

    Once the call is answered with channel.Answer(), we use TTS to prompt for a four digit PIN code. The channel.DtmfDetector obtain the digits entered by the caller for us, using the GetDigits() method. The specific overload used requires the expected number of digits, an output string in which the resultant digits are stored and a timeout value of 30 seconds. The method returns a cause value indicating why the method returned. The DtmfDetectorCause.Count cause signifies that the expected count of digits were detected.

    The code then responds to the caller with the digits entered. Note that the text has some formatting to ensure that TTS reads it in a natural manner. The call is then disconnected using the channel.HangUp() method.

    Code:

    // An inbound application that answers a call, prompts for the caller to 
    // enter a 4 digit pin code. It waits for 30 seconds for 4 digits to be entered 
    // and then replays them to the caller before hanging up.
    namespace PinInput
    
        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
    
        // 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 PinInput() = 
            inherit UASInboundApplication()
    
            // This is the entry point for the application
            override obj.Run(channel:UASCallChannel, applicationParameters:string) : int = 
                
                obj.Trace.TraceInfo("Started")
                let mutable reply = ReturnCode.Success
    
                try
                    // Answer the call
                    if channel.Answer() = CallState.Answered then
    
                        // Prompt to enter a pin
                        channel.FilePlayer.Say("Please enter a four digit pin code.") |> ignore
    
                        // Wait for 30 seconds for four digits
                        let mutable digits = ""
                        let cause = channel.DtmfDetector.GetDigits(4, &digits, 30)
                        match cause with
                            | DtmfDetectorCause.Count -> 
                                match digits.Length with
                                    | 0 -> 
                                        channel.FilePlayer.Say("Pin empty.") |> ignore
                                    | _ ->
                                        channel.FilePlayer.Say("The pin code you entered was {0}, {1}, {2}, {3}", digits.Chars(0), digits.Chars(1), digits.Chars(2), digits.Chars(3)) |> ignore
                            | _ -> 
                                channel.FilePlayer.Say("Pin Not entered.") |> ignore
    
                        channel.FilePlayer.Say("Goodbye.") |> ignore
                with 
                    | _ as e -> 
                        obj.Trace.TraceError("Exception thrown {0}", e.Message)
                        reply <- ReturnCode.ExceptionThrown
                    
                obj.Trace.TraceInfo("Completed")
                (int)reply