Interaction

Introduction

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

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

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

The processing will suspend until the SRF 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.
.srf_name String [Required] The SRF name as configured in the LhoScpApp.
This may be an on-switch resource, or an external SRF.
.message_id Integer A single message ID to play. This ID must be coordiated with the SRF 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 SRF 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 SRF language name as configured in the LhoScpApp.
This will be mapped to the associated numeric ID and sent to the SRF 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 SRF).
.repetition Integer Sets the `informationToSend.inbandInfo.numberOfRepetitions` sent to the SRF.
The SRF may or may not respect this value.
(Default = do not specify this value to the SRF).
.duration Integer Sets the `informationToSend.inbandInfo.duration` sent to the SRF.
This is the total expected duration of the interaction including repetitions and silence.
The SRF 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 SRF, and use the default service logic timeout value).
.interval Integer Sets the `informationToSend.inbandInfo.interval` sent to the SRF.
The external SRF may or may not respect this value.
(Default = do not specify this value to the SRF).
.variables Array of Object Each variable part Object must specify exactly one of the indicated options.
Some SRFS may place a limit in the number of variable parts.
(Default = do not supply variable parts to the SRF).
.integer Positive Integer Indicates that the variable part should be "spoken" as an natural language integer by the SRF.
The SRF 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 SRF.
The SRF 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 SRF.
The string is "YYMMDD" six-digits. The handling of century is SRF-dependent.
The natural algorithm will use the preferred, or the default language.
.date_yyyymmdd String Indicates that the variable part should be "spoken" as a natural language date string by the SRF.
The string is "YYYYMMDD" eight-digits.
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 SRF.
The string is "HHMM" four-digits. The handling of am/pm, noon, and midnight is SRF-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 SRF.
The string is "[DDDDDD]CC" from two to eight digits. The handling of zero cents is SRF-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 SRF 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 SRF 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 SRF).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
This field is relevant only when prompt is specified.
(Default = determined by the SRF).
.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 SRF).
.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 SRF).
.private_digits 0 / 1 Indicates that the collected digits are private (e.g. PIN entry) and the SCP should not log them to EDR.
This field is relevant only when prompt is specified.
Note that this disables only the logging of the digits by the SCP. The SRF is a separate, independent node element and this flag does not prevent the SRF from logging the collected digits.
(Default = the collected digits will be logged to EDR record).
.interruptable 0 / 1 Informs the SRF 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).
.fci String Specify the content of the FCIBillingChargingCharacteristics in the FurnishChargingInformation to send immediately prior to sending ConnectToResource or EstablishTemporaryConnection at the start of the interaction.
(Default = do not send FurnishChargingInformation).

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 SRF'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 SRF should return no digits at all in the case where insufficient digits are entered. However, that behavior can vary according to SRF 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 scp_call = ...

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

local.result = scp_api.interaction ({
    srf_name = 'DefaultSRF',
    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 SRF (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 

.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 SRF default language.

.play_announcement

The play_announcement method takes the following arguments:

Attribute Type Description
srf_name String [Required] The SRF name as configured in the LhoScpApp.
This may be an on-switch resource, or an external SRF.
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 SRF 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 SRFS 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 SRF).
options Object This is a container for selected additional SRF control options, all of which are optional. (Default = do not supply any other options to the SRF).
.fci String Specify the content of the FCIBillingChargingCharacteristics in the FurnishChargingInformation to send immediately prior to sending ConnectToResource or EstablishTemporaryConnection at the start of the interaction.
(Default = do not send FurnishChargingInformation).

The language will be the value in the most recent call to .set_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 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 

.prompt_and_collect

The prompt_and_collect method sets the prompt flag to request the SRF 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
srf_name String [Required] The SRF name as configured in the LhoScpApp.
This may be an on-switch resource, or an external SRF.
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 SRF 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 SRFS 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 SRF).
min_num_digits 1 - 32 [Required] The minimum number of digits which the SRF will be instructed to collect.
max_num_digits 1 - 32 [Required] The maximum number of digits which the SRF 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 SRF control options, all of which are optional. (Default = do not supply any other options to the SRF).
.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 SRF).
.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 SRF).
.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 SRF).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
This field is relevant only when prompt is specified.
(Default = determined by the SRF).
.interruptable 0 / 1 Informs the SRF 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).
.fci String Specify the content of the FCIBillingChargingCharacteristics in the FurnishChargingInformation to send immediately prior to sending ConnectToResource or EstablishTemporaryConnection at the start of the interaction.
(Default = do not send FurnishChargingInformation).

The language will be the value in the most recent call to .set_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 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