☰
Navigation :

Interaction (INAP)

Introduction

An SIP LUA script may request that the caller be directed to an external SRF 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 SRF Name as configured within the LhoSipApp list of configured SRF nodes.

The controlling LhoSipApp will establish a B-Leg temporary connection to the SRF 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:

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 SRF 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 LhoSipIncallLuaService Interaction API (External/INAP)

.inap_interaction [Asynchronous]

This method provides full access to the Interaction mechanism for external INAP SRFs, 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
srf_name String An external SRF 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 SRF.
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 SRF.
Specify exactly one of .message_id or .message_ids.
.language String Optional language name which may be conveyed to the external SRF (if it supports sending of language information).
For external INAP-controlled SRFs, 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 SRF.
This value is set in informationToSend.inbandInfo.numberOfRepetitions for the PA or PACUI.
(Default = do not specify this value to the SRF).
.duration Integer A requested duration value supplied to the SRF.
This value is set in informationToSend.inbandInfo.duration for the PA or PACUI.
(Default = do not specify this value to the SRF).
.interval Integer A requested interval value supplied to the SRF.
This value is set in informationToSend.inbandInfo.interval for the PA or PACUI.
(Default = do not specify this value to the SRF).
.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 SRF 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 SRF 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 SRF).
.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 SRF).
.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 SRF).
.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 SRF).
.interruptable 0 / 1 Informs the SRF 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 SRF).
.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 SRF is a separate, independent node element and this flag does not prevent the SRF 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 SRF name is not configured, the SRF 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 SRF'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_service"

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_service"

local scc = ...

NUM_DAYS_ID = 1020

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

incall_api.inap_interaction ("N2SRF", { 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_service"

local scc = ...

ENTER_PIN_ID = 1044

incall_api.inap_interaction ("N2SRF", { 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 SRF.

.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
.srf_name String An external SRF 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 SRF 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_service"

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_service"

local scc = ...

NUM_DAYS_ID = 1020

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

incall_api.play_announcement ("MainSRF", 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
srf_name String An external SRF 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 SRF 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 SRF or internal Media Server will be instructed to collect.
max_num_digits 1 - 32 [Required] The maximum number of digits which the SRF 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 SRF or internal Media Server defaults).
.end_digit #*A-F0-9 The digit which specifies End of Input.
(Default = determined by the SRF or internal Media Server).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
(Default = determined by the SRF 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 SRF 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 SRF 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 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 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_service"

PIN_PROMPT_ID = 713

local scc = ...

-- Use default Language, (default) internal SRF.
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
srf_name String An external SRF 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 SRF 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_service"

MAIN_MENU_ID = 733

local scc = ...

local result = incall_api.collect_digit ("SRF-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