Interaction

Introduction

An SCP LUA script may request that the caller be directed to an on-switch or external SRP using ConnectToResource or EstablishTemporaryConnection as appopriate.

For external SRPs, the service must specify a known SRP Name as configured within the LhoScpApp list of configured SRP nodes.

If a different SRP is currently open from a previous interaction, then a prior DisconnectForwardConnection will be sent on the SSP transaction, and any external SRP transaction will be ended according to the applicable SRP configuration.

The processing will suspend until the SRP indicates completion of the interaction, or a guard timer expires. In the “normal” case where the caller waits for the announcement to end, the call will continue to be “controlled”, and the service logic may carry on and attempt other telephony actions.

The LhoScpLuaService Interaction API

.interaction

This method provides full access to the Interaction mechanism and is provided for use by custom service developers. In the majority of scenarios, one of the subsequently-described convenience methods should be sufficient and preferable. However, this full-featured alternative is provided for use by complex or non-standard services.

This method takes a single details parameter which is a LUA table with the following structure:

Field Type Description
details Object [Required] The detailed control parameters for the interaction.
.srp_name String [Required] The SRP name as configured in the LhoScpApp.
This may be an on-switch resource, or an external SRP.
.message_id Integer A single message ID to play. This ID must be coordiated with the SRP node that is playing the announcement.
Specify exactly one of .message_id or .message_ids.
.message_ids Array of Integer An array of message IDs to play. These IDs must be coordiated with the SRP node that is playing the announcement.
Specify exactly one of .message_id or .message_ids.
Playing of multiple message IDs is not compatible with `.variables`.
.language String Specifies an SRP language name as configured in the LhoScpApp.
This will be mapped to the associated numeric ID and sent to the SRP using the associated mechanism.
The language is used to select the preferred audio file, and to encode variable parts such as numbers and dates.
(Default = do not pass language to the SRP).
.repetition Integer Sets the `informationToSend.inbandInfo.numberOfRepetitions` sent to the SRP.
The SRP may or may not respect this value.
(Default = do not specify this value to the SRP).
.duration Integer Sets the `informationToSend.inbandInfo.duration` sent to the SRP.
This is the total expected duration of the interaction including repetitions and silence.
The SRP may or may not respect this value.
The service logic will apply a timer and will abandon the interaction if it does not respond within this time.
(Default = do not specify this value to the SRP, and use the default service logic timeout value).
.interval Integer Sets the `informationToSend.inbandInfo.interval` sent to the SRP.
The external SRP may or may not respect this value.
(Default = do not specify this value to the SRP).
.variables Array of Object Each variable part Object must specify exactly one of the indicated options.
Some SRPS may place a limit in the number of variable parts.
(Default = do not supply variable parts to the SRP).
.integer Positive Integer Indicates that the variable part should be "spoken" as an natural language integer by the SRP.
The SRP may place an upper bound on the supported integer range. Negative numbers are not supported.
The natural algorithm will use the preferred, or the default language.
.number_digits Digit String Indicates that the variable part should be "spoken" as a natural language digit string by the SRP.
The SRP may limit the characters supported in this string. Typically [0-9][A-F] and "*" and "#" are supported.
The natural algorithm will use the preferred, or the default language.
.date_yymmdd String Indicates that the variable part should be "spoken" as a natural language date string by the SRP.
The string is "YYMMDD" six-digits. The handling of century is SRP-dependent.
The natural algorithm will use the preferred, or the default language.
.time_hhmm String Indicates that the variable part should be "spoken" as a natural language time string by the SRP.
The string is "HHMM" four-digits. The handling of am/pm, noon, and midnight is SRP-dependent.
The natural algorithm will use the preferred, or the default language.
.price_digits String Indicates that the variable part should be "spoken" as a natural language decimal price string by the SRP.
The string is "[DDDDDD]CC" from two to eight digits. The handling of zero cents is SRP-dependent.
The natural algorithm will use the preferred, or the default language.
.prompt 1 Set this field to 1 if you wish the interaction to collect user input digits.
(Default = do not collect user input digits).
.min_num_digits 1 - 32 The minimum number of digits which the SRP will be instructed to collect.
This field is relevant only when prompt is specified.
[Required] This required when prompt is specified.
.max_num_digits 1 - 32 The maximum number of digits which the SRP will be instructed to collect.
This value must be greater than or equal to min_num_digits.
This field is relevant only when prompt is specified.
[Required] This required when prompt is specified.
.end_digit #*A-F0-9 The digit which specifies End of Input.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.first_digit_timeout Positive Integer The number of seconds allowed between completing the announcement and entering the first digit.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.inter_digit_timeout Positive Integer The number of seconds allowed between entering one digit and entering the subsequent digit.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.interruptable 0 / 1 Informs the SRP that the prompt should be interrupted by user input.
This field is relevant only when prompt is specified.
(Default = the prompt may be interrupted by the user).

The interaction method returns a structure indicating the result of the interaction.

Attribute Type Description
.controlled Boolean [Required] Is this call still controlled, i.e. can subsequent telephony actions be performed?
.error String An optional interaction soft error related to a problem in playing the announcement or collecting input.
.digits #*A-F0-9 Input digits collected from user.
May include * or # characters according to the SRP's interpretation.
The .digits and .error are mutually exclusive.
Note that .digits may be present even when .reason is present.
One of .digits or .error will be present when .reason is not present and digit collection was requested.
In theory, the SRP should return no digits at all in the case where insufficient digits are entered. However, that behavior can vary according to SRP manufacturer, and the service logic should always validate the number of digits returned.
.reason String Reason for loss of A-Leg control.
This field is present is present if and only if .controlled is false.

Example (prompt and collect 4 digits):

    local n2svcd = require "n2.n2svcd"
    local scp_api = require "n2.n2svcd.scp"

    local handler = function (scp_call)

        scp_api.set_language ('German')
        local result = scp_api.prompt_and_collect (srp_name, message_id, nil, 4, 4, options)

        local.result = scp_api.interaction ({
            srp_name = 'DefaultSRP',
            message_id = 1010,
            language = 'English',
            prompt = 1,
            min_num_digits = 4,
            max_num_digits = 4
        })

        -- Note that it is possible to get digits even if the A-Leg control was lost.
        if (result.digits) then
            n2svcd.notice ("DIGITS = %s")

        -- In the case of non-collection, we might have been abandoned, or we might 
        -- have encountered a problem on the SRP (e.g. bad announcement, collection timeout).
        -- At least one explaination will apply.
        --
        else 
            n2svcd.notice ("NON-COLLECT = %s", result.error or result.reason)
        end

        -- If the call control w
        if (result.controlled) then
            scp_api.release_call (5)

        else
            n2svcd.notice ('Interaction Abandoned = %s', result.reason)
        end

        return 
    end

    return n2svcd.handler (handler)

.set_language

The set_language method sets the language name that will be passed in future calls to the following interaction helper methods. It takes a single argument:

Attribute Type Description
default_language String The new default Language for all subsequent calls to the interaction helper methods.
Specify `nil` to default to the on-switch or SRP default language.

.play_announcement

The play_announcement method takes the following arguments:

Attribute Type Description
srp_name String [Required] The SRP name as configured in the LhoScpApp.
This may be an on-switch resource, or an external SRP.
message_id/s Number/List [Required] Either a single message ID number to play, or a number List. If a single number is provided then this will be passed to the SRP as message_id. If a list of numbers is provided then this will be passed as message_ids.
variables Array of Object Each variable part Object must specify exactly one of the indicated options.
Some SRPS may place a limit in the number of variable parts.
See the above documentation for the interaction method. (Default = do not supply variable parts to the SRP).

The language will be the value in the most recent call to .set_srp_language (or nil).

The play_announcement method returns the same result structure as interaction.

Example (two message IDs, with retry on failure):

    local n2svcd = require "n2.n2svcd"
    local scp_api = require "n2.n2svcd.scp"

    local handler = function (scp_call)

        scp_api.set_language ('English')
        local result = scp_api.play_announcement ("SWITCH", { 1070, 1073 }, { { integer = 5000 }})

        if (result.error and result.controlled) then
            scp_api.set_language (nil)
            result = scp_api.play_announcement ("SWITCH", { 1080, 1073 }, { { integer = 5000 }})
        end

        -- Call will release automatically on exit.
        return 
    end

    return n2svcd.handler (handler)

.prompt_and_collect

The prompt_and__collect method sets the prompt flag to request the SRP to collect digits input by the caller. It has additional parameters, including the minimum and maximum number of digits to collect.
It also allows some additional refined control options.

The prompt_and_collect method takes the following arguments:

Attribute Type Description
srp_name String [Required] The SRP name as configured in the LhoScpApp.
This may be an on-switch resource, or an external SRP.
message_id/s Number/List [Required] Either a single message ID number to play, or a number List. If a single number is provided then this will be passed to the SRP as message_id. If a list of numbers is provided then this will be passed as message_ids.
variables Array of Object Each variable part Object must specify exactly one of the indicated options.
Some SRPS may place a limit in the number of variable parts.
See the above documentation for the interaction method. (Default = do not supply variable parts to the SRP).
min_num_digits 1 - 32 [Required] The minimum number of digits which the SRP will be instructed to collect.
max_num_digits 1 - 32 [Required] The maximum number of digits which the SRP will be instructed to collect.
This value must be greater than or equal to min_num_digits.
options Object This is a container for selected additional SRP control options, all of which are optional. (Default = do not supply any other options to the SRP).
.first_digit_timeout Positive Integer The number of seconds allowed between completing the announcement and entering the first digit.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.inter_digit_timeout Positive Integer The number of seconds allowed between entering one digit and entering the subsequent digit.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.end_digit #*A-F0-9 The digit which specifies End of Input.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
This field is relevant only when prompt is specified.
(Default = determined by the SRP).
.interruptable 0 / 1 Informs the SRP that the prompt should be interrupted by user input.
This field is relevant only when prompt is specified.
(Default = the prompt may be interrupted by the user).

The language will be the value in the most recent call to .set_srp_language (or nil).

The prompt_and_collect method returns the same result structure as interaction.

Example (prompt for exactly 4 digits and play them back):

    local n2svcd = require "n2.n2svcd"
    local scp_api = require "n2.n2svcd.scp"

    local handler = function (scp_call)

        local SWITCH = "SWITCH"

        -- Override some options for no good reason at all.
        local options = {
            end_digit = '*',
            cancel_digit = 'e',
            first_digit_timeout = 6,
            inter_digit_timeout = 4,
            interruptable = false
        }

        -- Collect exactly 4 digits, or none at all.
        local result = scp_api.prompt_and_collect (SWITCH, 3007, nil, 4, 4, options)

        -- If the caller is gone, we don't bother going on.
        if (not result.controlled) then
            return
        end

        -- Our scenario REQUIRES digits.
        if (not result.digits or not string.len (result.digits)) then
            error "No digits entered, cannot continue."
        end

        -- Play back the collected digits (as "number digits" type).
        result = scp_api.play_announcement (SWITCH, 4040 nil, { { number_digits = result.digits } })

        -- This will automatically release the call (if needed) with default release cause.
        return 
    end

    return n2svcd.handler (handler)