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.
The service must known the SRP Name as configured within the LhoScpApp list of support SRP Functions.
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 SCP control parameters for the message.
.srp_name
String
[Required] The SRP name as configured in the LhoScpApp.
.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.
Interpretation of this value is specific to the SRP.
(Default = do not specifiy this value to the SRP).
.duration
Integer
Sets the
informationToSend.inbandInfo.duration sent to the SRP.
Interpretation of this value is specific to the SRP.
(Default = do not specifiy this value to the SRP).
.interval
Integer
Sets the
informationToSend.inbandInfo.interval sent to the SRP.
Interpretation of this value is specific to the SRP.
(Default = do not specifiy 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.
.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).
Example (connect to called party with a prefix, no FCI, redirection):
local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"
local handler = function (scp_call)
local result = scp_api.prompt_and_collect (srp_name, message_id, 'German', 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).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.
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.
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).
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 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)
local result = scp_api.play_announcement ("SWITCH", { 1070, 1073 }, "German", { { integer = 5000 }})
if (result.error and result.controlled) then
result = scp_api.play_announcement ("SWITCH", { 1080, 1073 }, "German", { { 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.
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.
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).
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 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, 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)