Navigation :

Interaction (INAP)

Introduction

An SIP LUA script may request that the caller be directed to an external SRP which will be controlled via INAP, with the LhoSipApp performing the INAP role of an SCP on behalf of the Lua service logic script.,

The service must specify a known SRP Name as configured within the LhoSipApp list of configured SRP nodes.

The controlling LhoSipApp will establish a B-Leg temporary connection to the SRP using an outbound SIP INVITE.

The LhoSipApp acting as a back-to-back user agent will also perform the necessary A-Leg messaging to relay SDP information back from the B-Leg, using one of:

SIP INVITE Response (200 OK)
SIP INVITE Response (183 Early Media)
SIP re-INVITE

The SIP re-INVITE is necessary if the SIP call has previously been connected to a different RTP endpoint via SIP INVITE Response (200 OK) and hence needs to be re-directed.

Here is the overall flow for the interaction case using the SIP INVITE Response (200 OK) mechanism to establish a temporary B-Leg to an external INAP-controlled SRP for the purpose of performing interaction.

Possible additional provisional responses are not shown. The example given is for PlayAnnouncement only.

Message Flow (External INAP Interaction)

Service logic processing will suspend until the requested interaction has been completed, or abandoned.

The LhoSipIncallLuaService Interaction API (External/INAP)

.inap_interaction [Asynchronous]

This method provides full access to the Interaction mechanism for external INAP SRPs, 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 two arguments:

Argument	Type	Description
`srp_name`	String	An external SRP name as configured in the LhoSipApp. (Default = Use the internal Media Server).
`announcement`	Object	[Required] A structure defining the announcement interaction which is to be performed.
`.message_id`	Integer	A single message ID to play. This ID must be coordiated with the external SRP. 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 external SRP. Specify exactly one of `.message_id` or `.message_ids`.
`.language`	String	Optional language name which may be conveyed to the external SRP (if it supports sending of language information). For external INAP-controlled SRPs, this name is mapped to an on-the-wire integer value according to the configured language map. Refer to the LhoSipApp configuration documentation. (Default = Platform-Configured Value)
`.repetition`	Integer	A requested repetition count supplied to the SRP. This value is set in `informationToSend.inbandInfo.numberOfRepetitions` for the PA or PACUI. (Default = do not specify this value to the SRP).
`.duration`	Integer	A requested duration value supplied to the SRP. This value is set in `informationToSend.inbandInfo.duration` for the PA or PACUI. (Default = do not specify this value to the SRP).
`.interval`	Integer	A requested interval value supplied to the SRP. This value is set in `informationToSend.inbandInfo.interval` for the PA or PACUI. (Default = do not specify this value to the SRP).
`.variables`	Array of Object	An array of variable values to substitute into pre-defined placeholders in the message structure. Each variable part is an object which specifies exactly one of the attributes as follows.
`.integer`	Integer	An integer value to speak as a variable part.
`.number_digits`	Integer	An integer value to speak as a variable part.
`.time_hhmm`	<HHMM>	An integer hour and minute to speak as a variable part. Value is in the range `0000`-`2400`.
`.date_yymmdd`	<YYMMDD>	A 6-digit integer year/month/day to speak as a variable part.
`.date_yyyymmdd`	<YYYYMMDD>	An 8-digit integer year/month/day to speak as a variable part.
`.price_digits`	Integer	An integer value of "cents" to speak as a variable part.
`.collect`	Object	Container for information related to digit collection. Digit collection will be performed if and only if this container element is present. (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 value is set in `collectedInfo.collectedDigits.minimumNbOfDigits` for the PACUI. [Required] This required when `collect` 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 value is set in `collectedInfo.collectedDigits.maximumNbOfDigits` for the PACUI. [Required] This required when `collect` is specified.
`.end_digit`	`#*A-F0-9`	The digit which specifies End of Input. This value is set in `collectedInfo.collectedDigits.endOfReplyDigit` for the PACUI. (Default = determined by the SRP).
`.cancel_digit`	`#*A-F0-9`	The digit which specifies Cancel Input. This value is set in `collectedInfo.collectedDigits.cancelDigit` for the PACUI. (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 value is set in `collectedInfo.collectedDigits.firstDigitTimeOut` for the PACUI. (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 value is set in `collectedInfo.collectedDigits.interDigitTimeOut` for the PACUI. (Default = determined by the SRP).
`.interruptable`	`0` / `1`	Informs the SRP that DTMF input from the user should interrupt the playing of the prompt. This value is set in `collectedInfo.collectedDigits.interruptableAnnInd` for the PACUI. (Default = do not specify this value to the SRP).
`.private_digits`	`0` / `1`	Indicates that the collected digits are private, e.g. PIN entry, and the framework should not log them to any EDR. Note that this disables only the logging of the digits by the service logic and framework. The SRP is a separate, independent node element and this flag does not prevent the SRP from logging the collected digits. (Default = the default behavior configured for the application).

The inap_interaction method returns a LUA table with the following attributes.

Attribute	Type	Description
`.controlled`	Boolean	[Required] Is this call still controlled, i.e. can subsequent SIP actions be performed?
`.error`	String	An optional interaction error related to a problem in playing the announcement or collecting input. If this parameter is defined, then the service logic should assume that the announcement audio was not successfully communicated to the user, e.g. the SRP name is not configured, the SRP could not be reached, some audio files were missing, some interaction parameters were invalid, etc.
`.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. One of `.digits` or `.error` will be present when `.reason` is not present and digit collection was requested.
`.reason`	`Abandoned`	Reason for loss of call control during interaction. This field is present is present if and only if `.controlled` is `false`.
`.decline_ok`	Boolean	Can the service logic still use the `.proceeding` and `.decline` methods? This field is present is present if and only if `.controlled` is `true`. This field will be `true` if we have not yet sent a 2XX or 300-699 Response code.

Example (simple announcement):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

WELCOME_ID = 4022

local scc = ...

incall_api.inap_interaction ("INTERNAL", { message_id = WELCOME_ID })

return

Example (one integer variable part):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

local scc = ...

NUM_DAYS_ID = 1020

if (not result.controlled) then
    error ("Caller Abandoned during Answer.")
end

incall_api.inap_interaction ("N2SRP", { message_id = NUM_DAYS_ID, variables = { integer = 356 } })

return

Example (collect 4 digit PIN):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

local scc = ...

ENTER_PIN_ID = 1044

incall_api.inap_interaction ("N2SRP", { message_id = ENTER_PIN_ID, collect = { min_num_digits = 4, max_num_digits = 4 }})

return

.set_language [Pure Lua]

The set_language method sets the Language Name that will be passed in future calls to the following interaction helper methods.

Note: This default language name setting is not applied when calling the interaction method directly.

This method takes a single argument:

Argument	Type	Description
`default_language`	String	The new default Language for all subsequent calls to the interaction helper methods. Specify `nil` to default to the default language for the SRP.

.play_announcement [Asynchronous]

The play_announcement method is an interaction helper method for playing an external INAP-controlled announcement which does not prompt for digit collection.

It has the following arguments:

Attribute	Type	Description
`.srp_name`	String	An external SRP name as configured in the LhoSipApp. (Default = Use the internal Media Server).
`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 or internal Media Server as `message_id`. If a list of numbers is provided then this will be passed as `message_ids`.
`variables`	Array of Objects	Variable Parts list as per the Variable Part structure defined below. The number of variable parts should match the number of variable parts placeholders in the requested announcement ID. (Default = No variable parts).

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

All other interaction parameters will have their default values.

The play_announcement method returns the same result structure as inap_interaction.

Example (simple announcement):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

WELCOME_ID = 4022

local scc = ...

-- Play using internal Media Server.
incall_api.play_announcement (nil, WELCOME_ID)

return

Example (one integer variable part):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

local scc = ...

NUM_DAYS_ID = 1020

-- Explicitly choose non-default Language.
incall_api.set_language ("German")

incall_api.play_announcement ("MainSRP", NUM_DAYS_ID, { integer = 356 })

return

.prompt_and_collect [Asynchronous]

The prompt_and_collect method is an interaction helper method for playing an external INAP-controlled announcement which does prompt for digit collection.

It has the following arguments:

Attribute	Type	Description
`srp_name`	String	An external SRP name as configured in the LhoSipApp. (Default = Use the internal Media Server).
`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 or internal Media Server as `message_id`. If a list of numbers is provided then this will be passed as `message_ids`.
`variables`	Array of Objects	Variable Parts list as per the Variable Part structure defined below. The number of variable parts should match the number of variable parts placeholders in the requested announcement ID. (Default = No variable parts).
`min_num_digits`	`1` - `32`	[Required] The minimum number of digits which the SRP or internal Media Server will be instructed to collect.
`max_num_digits`	`1` - `32`	[Required] The maximum number of digits which the SRP or internal Media Server will be instructed to collect. This value must be greater than or equal to `min_num_digits`.
`options`	Object	A structure defining additional options for digit collection. (Default = Use SRP or internal Media Server defaults).
`.end_digit`	`#*A-F0-9`	The digit which specifies End of Input. (Default = determined by the SRP or internal Media Server).
`.cancel_digit`	`#*A-F0-9`	The digit which specifies Cancel Input. (Default = determined by the SRP or internal Media Server).
`.first_digit_timeout`	Positive Integer	The number of seconds allowed between completing the announcement and entering the first digit. (Default = determined by the SRP or internal Media Server).
`.inter_digit_timeout`	Positive Integer	The number of seconds allowed between entering one digit and entering the subsequent digit. (Default = determined by the SRP or internal Media Server).
`.private_digits`	`0` / `1`	Indicates that the collected digits are private (e.g. PIN entry) and the SCP should not log them to EDR. Note that this disables only the logging of the digits by the SCP. The SRP is a separate, independent node element and this flag does not prevent the SRP from logging the collected digits. (Default = the collected digits will be logged to EDR record).
`.interruptable`	`0` / `1`	Informs the SRP or internal Media Server that the prompt should be interrupted by user input. (Default = the prompt may be interrupted by the user).

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

All other interaction parameters will have their default values.

The prompt_and_collect method returns the same result structure as inap_interaction.

Example (PIN entry):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

PIN_PROMPT_ID = 713

local scc = ...

-- Use default Language, (default) internal SRP.
local result = incall_api.prompt_and_collect (nil, PIN_PROMPT_ID, nil, 4, 4)

if (not result.controlled) then
    n2svcd.debug_var ("Caller abandon during PIN entry.")
    return
end
if (result.digits) then
    n2svcd.debug_var ("PIN DIGITS = " .. result.digits)
end

return

.collect_digit [Asynchronous]

The collect_digit method is an interaction helper method for playing an external INAP-controlled announcement which prompts to collect a single digit.

It has the following arguments:

Attribute	Type	Description
`srp_name`	String	An external SRP name as configured in the LhoSipApp. (Default = Use the internal Media Server).
`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 or internal Media Server as `message_id`. If a list of numbers is provided then this will be passed as `message_ids`.
`variables`	Array of Objects	Variable Parts list as per the Variable Part structure defined below. The number of variable parts should match the number of variable parts placeholders in the requested announcement ID. (Default = No variable parts).

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

The minimum number of digits will be 1.

The maximum number of digits will be 1.

All other interaction parameters will have their default values.

The collect_digit method returns the same result structure as inap_interaction.

Example (simple menu):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

MAIN_MENU_ID = 733

local scc = ...

local result = incall_api.collect_digit ("SRP-1", MAIN_MENU_ID)
if (not result.controlled) then
    n2svcd.debug_var ("Caller abandon during main menu.")
    return
end
if (result.digits) then
    n2svcd.debug_var ("COLLECTED DIGIT = " .. result.digits)
end

return