Pin Input | Aculab

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\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