Navigation :

Interaction (INAP)

Introduction

A SIP call-control Lua script using LhoSipIncallLuaService or LhoSipOutcallLuaAgent may request that the caller be connected to an external INAP-controlled SRF, with the LhoSipApp performing the INAP role of an SCP on behalf of the Lua service logic script.

The service must specify the name of an SRF that is configured on the LhoSipApp.

The LhoSipApp will initiate a temporary B-Leg connection to the SRF using an outbound SIP INVITE Request, then - acting as a SIP Back-to-Back User Agent (B2BUA) - relay the relevant messages between the Legs as necessary to establish and maintain a connection.

The A-Leg messaging will involve one of:

SIP INVITE Provisional Responses and Final Response
SIP re-INVITE Request

A re-INVITE Request is necessary if a Final Response has already been sent for the A-Leg INVITE Request.

Here is the overall flow for an interaction using the SIP INVITE Final Response mechanism to connect to an external INAP-controlled SRF. Note that Provisional Responses from the B-Leg to the A-Leg are possible but not shown, and the example given is for PlayAnnouncement only.

Message Flow (External INAP Interaction)

Service logic processing will suspend until:

The A-Party abandons the call, or
The external SRF returns with an INAP message, or
The external interaction timer reaches the maximum allowed duration, or
An internal processing error occurs.

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 the following arguments:

Argument	Type	Description
`srf_name`	String	[Required] The name of the SRF to use to perform the interaction, as configured on the `LhoSipApp`.
`announcement`	Table	[Required] A table specifying the parameters for the interaction which is to be performed.
`.message_id`	Integer	A single message ID to play. This ID will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageID` or `informationToSend.messageID.variableMessage.elementaryMessageID` IE within the INAP PA or PACUI message. The ID must be coordiated with the SRF. The definition of this ID may depend on the specified language, and may include a mixture of audio files and variable parts. Specify exactly one of `.message_id` or `.message_ids`.
`.message_ids`	Table of Integer	A table of one or more message IDs to play in sequence. These IDs will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageIDs` IE within the INAP PA or PACUI message. The IDs must be coordiated with the SRF. The definitions of these IDs may depend on the specified language, but are only expected to include audio files (no variable parts). Specify exactly one of `.message_id` or `.message_ids`.
`.language`	String	The name of a language to prefer instead of the language specified by the most recent invocation of `.set_language` or any default used by the SRF. If possible, the language preference will be conveyed to the SRF along with the interaction parameters. The LhoSipApp language map configuration may be used to map the language to an integer ID that the the SRF will understand. (Default = use the language specified by the most recent invocation of `.set_language` or any default used by the SRF).
`.repetition`	Positive Integer	The value for the `informationToSend.inbandInfo.numberOfRepetitions` IE within the INAP PA or PACUI message. (Default = do not send this value to the SRF).
`.duration`	Integer	The value for the `informationToSend.inbandInfo.duration` IE within the INAP PA or PACUI message. (Default = do not send this value to the SRF).
`.interval`	Integer	The value for the `informationToSend.inbandInfo.interval` IE within the INAP PA or PACUI message. (Default = do not send this value to the SRF).
`.variables`	Table of Tables	A table containing the values to substitute into pre-defined placeholders in the message structure. These values will be conveyed to the SRF in the `informationToSend.messageID.variableMessage.variableParts` IE within the INAP PA or PACUI message. Each entry in the table is a table which specifies exactly one of the attributes as follows. (Default = no variables).
`.integer`	Integer	An integer value to speak as a variable part. This will be conveyed to the SRF in the `VariablePart.integer` IE.
`.number_digits`	(+)Hex String	A hexadecimal numeric string to speak as a variable part. This will be conveyed to the SRF in the `VariablePart.number` IE.
`.time_hhmm`	<HHMM>	An integer hour and minute to speak as a variable part. This will be conveyed to the SRF in the `VariablePart.time` IE. Value must be in the range `0000` to `2400`.
`.date_yymmdd`	<YYMMDD>	A 6-digit integer year/month/day to speak as a variable part. This will be conveyed to the SRF in the `VariablePart.date` IE.
`.date_yyyymmdd`	<YYYYMMDD>	An 8-digit integer year/month/day to speak as a variable part. This will be conveyed to the SRF in the `VariablePart.date` IE.
`.price_digits`	Integer	An integer value of "cents" to speak as a variable part. This will be conveyed to the SRF in the `VariablePart.price` IE.
`.collect`	Table	A container for parameters related to digit collection. Digit collection will be performed if and only if this parameter is present. (Default = do not collect digits).
`.min_num_digits`	`1` - `32`	[Required] The minimum number of digits which the SRF must collect. This value will be conveyed to the SRF in the `collectedInfo.collectedDigits.minimumNbOfDigits` IE within the INAP PACUI message. This value must be less than or equal to `max_num_digits`.
`.max_num_digits`	`1` - `32`	[Required] The maximum number of digits which the SRF must collect. This value will be conveyed to the SRF in the `collectedInfo.collectedDigits.maximumNbOfDigits` IE within the INAP PACUI message. This value must be greater than or equal to `min_num_digits`.
`.end_digit`	`#*A-F0-9`	The value for the `collectedInfo.collectedDigits.endOfReplyDigit` IE within the PACUI message. If the digit is `` or `#`, the digit will be translated according to the `star_digit` and `hash_digit` configured on the `LhoSipApp` for the SRF. (Default = use the `end_digit` configured on the `LhoSipApp` for the SRF)*.
`.cancel_digit`	`#*A-F0-9`	The value for the `collectedInfo.collectedDigits.cancelDigit` IE within the PACUI message. If the digit is `` or `#`, the digit will be translated according to the `star_digit` and `hash_digit` configured on the `LhoSipApp` for the SRF. (Default = use the `cancel_digit` configured on the `LhoSipApp` for the SRF)*.
`.first_digit_timeout`	Positive Integer	The value for the `collectedInfo.collectedDigits.firstDigitTimeOut` IE within the PACUI message. (Default = do not send this value to the SRF).
`.inter_digit_timeout`	Positive Integer	The value for the `collectedInfo.collectedDigits.interDigitTimeOut` IE within the PACUI message. (Default = do not send this value to the SRF).
`.interruptable`	Boolean	The value for the `collectedInfo.collectedDigits.interruptableAnnInd` IE within the PACUI message. (Default = do not send this value to the SRF).
`.private_digits`	Boolean	When `true`, the collected digits are considered private, and will not be logged to `LhoSipApp` EDRs. Note that the SRF is a separate, independent element, and this flag does prevent the SRF from logging the collected digits. (Default = use the `default_private_digits` configured on the `LhoSipApp`).
`options`	Table	A table specifying additional parameters for the connection to the SRF. (Default = do not apply additional parameters to the SRF connection).
`.calling_party`	(+)Hex String	The `userinfo` part of the INVITE Request `From` header address. The protocol and domain parts of the address will be determined automatically. The applicable configured `calling_party` denormalisation on the `LhoSipApp` will be applied. Set to `UNDEF` to suppress the network-supplied presented calling party (if any). This parameter will have no effect if presentation of the calling party is restricted. (Default = for an A-Leg initiated by an outbound INVITE Request, the A-Leg presented called party; for an A-Leg initiated by an inbound INVITE Request, the A-Leg presented calling party).
`.is_calling_restricted`	Boolean	Specify whether presentation of the calling party should be restricted. This parameter will have no effect if: The A-Leg was initiated by an inbound INVITE Request that contained a `Privacy` header with value `none`. The A-Leg was initiated by an outbound INVITE Request with a Response that contained a `Privacy` header with value `none`. Otherwise, when restricted, the SRF INVITE Request `From` and `Contact` headers will be anonymous, and a `Privacy` header containing the `id` flag will be included. Other flags from any `Privacy` headers in the A-Leg INVITE Request or Response will be included in the SRF INVITE Request `Privacy` header. When not restricted, the SRF INVITE Request `From` and `Contact` headers will not be anonymous, and a `Privacy` header will not be included. (Default = for an A-Leg initiated by an inbound INVITE Request, the restriction requested by the calling party; for an A-Leg initiated by an outbound INVITE Request, the restriction requested by the called party).
`.original_called_party`	(+)Hex String	The `userinfo` part of the INVITE Request `To` header address. The protocol and domain parts of the address will be determined automatically. The applicable configured `called_party` denormalisation on the `LhoSipApp` will be applied. (Default = use the SRF INVITE Request called party).

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

Attribute	Type	Description
`.controlled`	Boolean	[Required] Is this call still controlled right now? This value being `true` indicates that (at least some) telephony API actions can be performed by service logic. Note that in some cases the available control actions may be limited.
`.proceed_ok`	Boolean	[Required] Can the service logic still use the `.proceeding` method? This value will be `true` when `.controlled` is `true`, we have not yet sent a Final Response, and an SDP Offer would not be required to proceed.
`.decline_ok`	Boolean	[Required] Can the service logic still use the `.decline` method? This value will be `true` when `.controlled` is `true` and we have not yet sent a Final Response.
`.reason`	`Abandoned`	The reason for loss of call control during interaction. This value is present only when `.controlled` is `false`. (Default = not present, `.controlled` is `true`).
`.error`	String	A description of the first error that occurred in connection with the interaction. This value is present only when `.controlled` is `true` and an error occurred. One of `.digits` or `.error` will be present when `.controlled` is `true` and `.collect` was specified. If this value is defined, the service logic should assume that the intended audio was not played in full to the caller, and/or that digit collection was not completed successfully. This value may be defined when e.g. the SRF could not be reached, some audio files were missing, some interaction parameters were invalid, etc. (Default = not present, `.controlled` is `false` or an error did not occur).
`.digits`	`#*A-F0-9`	Digits collected from the caller. This value is present only when `.controlled` is `true`, `.error` is not present, and `.collect` was specified. One of `.digits` or `.error` will be present when `.controlled` is `true` and `.collect` was specified. This value will be present but empty if insufficient digits were collected from the caller. The `star_digit` and `hash_digit` configured on the `LhoSipApp` for the SRF will be used to translate any digits to `` or `#` as appropriate. (Default = not present, `.controlled` is `false` or `.collect` was not specified or an error occurred)*.

Example (simple announcement):

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

local scc = ...

local WELCOME_ID = 4022

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

local NUM_DAYS_ID = 1020

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 = ...

local 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 default language for all subsequent interactions.

Note: this method affects interactions with both the Internal RTP resource and External INAP-controlled SRFs.

This method takes a single argument:

Argument	Type	Description
`language`	String	The new default language for all subsequent interactions. Specify `nil` to use the SRF's default language, if any. (Default = `nil`, use the SRF's default language, if any).

The set_language method returns true.

.inap_play_announcement [Asynchronous]

This helper method provides a flattened-argument version of the inap_interaction method for playing an announcement without digit collection.

It has the following arguments:

Attribute	Type	Description
`.srf_name`	String	[Required] The name of the SRF to use to play the announcement, as configured on the `LhoSipApp`.
`message_id/s`	Number/Table	[Required] The message ID or IDs to play. If there is one ID, it will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageID` or `informationToSend.messageID.variableMessage.elementaryMessageID` IE within the INAP PA message. If there is more than one ID, it will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageIDs` IE within the INAP PA message. The ID(s) must be coordiated with the SRF. The definitions of these IDs may depend on the specified language. If there is one ID, the definition may include a mixture of audio files and variable parts. If there is more than one ID, the definition may only include audio files (no variable parts).
`variables`	Table of Tables	As for `.inap_interaction` `announcement.variables`.
`options`	Table	As for `.inap_interaction` `options`.

The language used will be the language specified by the most recent invocation of .set_language or any default used by the SRF.

All other interaction parameters will have their default values.

The inap_play_announcement method returns the same table structure as inap_interaction.

Example (simple announcement):

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

local WELCOME_ID = 4022

local scc = ...

incall_api.inap_play_announcement ("MainSRF", WELCOME_ID)

return

Example (one integer variable part):

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

local scc = ...

local NUM_DAYS_ID = 1020

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

incall_api.inap_play_announcement ("MainSRF", NUM_DAYS_ID, { integer = 356 })

return

.inap_prompt_and_collect [Asynchronous]

This helper method provides a flattened-argument version of the inap_interaction method for playing an announcement with digit collection.

It has the following arguments:

Attribute	Type	Description
`srf_name`	String	[Required] The name of the SRF to use to perform the interaction, as configured on the `LhoSipApp`.
`message_id/s`	Number/Table	[Required] The message ID or IDs to play. If there is one ID, it will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageID` or `informationToSend.messageID.variableMessage.elementaryMessageID` IE within the INAP PACUI message. If there is more than one ID, it will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageIDs` IE within the INAP PACUI message. The ID(s) must be coordiated with the SRF. The definitions of these IDs may depend on the specified language. If there is one ID, the definition may include a mixture of audio files and variable parts. If there is more than one ID, the definition may only include audio files (no variable parts).
`variables`	Table of Tables	As for `.inap_interaction` `announcement.variables`.
`min_num_digits`	`1` - `32`	[Required] The minimum number of digits which the SRF must collect. This value will be conveyed to the SRF in the `collectedInfo.collectedDigits.minimumNbOfDigits` IE within the INAP PACUI message. This value must be less than or equal to `max_num_digits`.
`max_num_digits`	`1` - `32`	[Required] The maximum number of digits which the SRF must collect. This value will be conveyed to the SRF in the `collectedInfo.collectedDigits.maximumNbOfDigits` IE within the INAP PACUI message. This value must be greater than or equal to `min_num_digits`.
`options`	Table	A table specifying additional parameters for digit collection and the connection to the SRF. (Default = do not apply additional parameters for digit collection or the connection to the SRF).
`.end_digit`	`#*A-F0-9`	The value for the `collectedInfo.collectedDigits.endOfReplyDigit` IE within the PACUI message. If the digit is `` or `#`, the digit will be translated according to the `star_digit` and `hash_digit` configured on the `LhoSipApp` for the SRF. (Default = use the `end_digit` configured on the `LhoSipApp` for the SRF)*.
`.cancel_digit`	`#*A-F0-9`	The value for the `collectedInfo.collectedDigits.cancelDigit` IE within the PACUI message. If the digit is `` or `#`, the digit will be translated according to the `star_digit` and `hash_digit` configured on the `LhoSipApp` for the SRF. (Default = use the `cancel_digit` configured on the `LhoSipApp` for the SRF)*.
`.first_digit_timeout`	Positive Integer	The value for the `collectedInfo.collectedDigits.firstDigitTimeOut` IE within the PACUI message. (Default = do not send this value to the SRF).
`.inter_digit_timeout`	Positive Integer	The value for the `collectedInfo.collectedDigits.interDigitTimeOut` IE within the PACUI message. (Default = do not send this value to the SRF).
`.interruptable`	Boolean	The value for the `collectedInfo.collectedDigits.interruptableAnnInd` IE within the PACUI message. (Default = do not send this value to the SRF).
`.private_digits`	Boolean	When `true`, the collected digits are considered private, and will not be logged to `LhoSipApp` EDRs. Note that the SRF is a separate, independent element, and this flag does prevent the SRF from logging the collected digits. (Default = use the `default_private_digits` configured on the `LhoSipApp`).
`.calling_party`	(+)Hex String	The `userinfo` part of the INVITE Request `From` header address. The protocol and domain parts of the address will be determined automatically. The applicable configured `calling_party` denormalisation on the `LhoSipApp` will be applied. Set to `UNDEF` to suppress the network-supplied presented calling party (if any). This parameter will have no effect if presentation of the calling party is restricted. (Default = for an A-Leg initiated by an outbound INVITE Request, the A-Leg presented called party; for an A-Leg initiated by an inbound INVITE Request, the A-Leg presented calling party).
`.is_calling_restricted`	Boolean	Specify whether presentation of the calling party should be restricted. This parameter will have no effect if: The A-Leg was initiated by an inbound INVITE Request that contained a `Privacy` header with value `none`. The A-Leg was initiated by an outbound INVITE Request with a Response that contained a `Privacy` header with value `none`. Otherwise, when restricted, the SRF INVITE Request `From` and `Contact` headers will be anonymous, and a `Privacy` header containing the `id` flag will be included. Other flags from any `Privacy` headers in the A-Leg INVITE Request or Response will be included in the SRF INVITE Request `Privacy` header. When not restricted, the SRF INVITE Request `From` and `Contact` headers will not be anonymous, and a `Privacy` header will not be included. (Default = for an A-Leg initiated by an inbound INVITE Request, the restriction requested by the calling party; for an A-Leg initiated by an outbound INVITE Request, the restriction requested by the called party).
`.original_called_party`	(+)Hex String	The `userinfo` part of the INVITE Request `To` header address. The protocol and domain parts of the address will be determined automatically. The applicable configured `called_party` denormalisation on the `LhoSipApp` will be applied. (Default = use the SRF INVITE Request called party).

The language used will be the language specified by the most recent invocation of .set_language or any default used by the SRF.

All other interaction parameters will have their default values.

The inap_prompt_and_collect method returns the same table structure as inap_interaction.

Example (PIN entry):

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

local scc = ...

local PIN_PROMPT_ID = 713

local result = incall_api.inap_prompt_and_collect ("MainSRF", PIN_PROMPT_ID, 4, 4, { private_digits = true })

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

return

.inap_collect_digit [Asynchronous]

This helper method provides a simplified version of the inap_prompt_and_collect method for playing an announcement with single digit collection.

It has the following arguments:

Attribute	Type	Description
`srf_name`	String	[Required] The name of the SRF to use to perform the interaction, as configured on the `LhoSipApp`.
`message_id/s`	Number/Table	[Required] The message ID or IDs to play. If there is one ID, it will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageID` or `informationToSend.messageID.variableMessage.elementaryMessageID` IE within the INAP PACUI message. If there is more than one ID, it will be conveyed to the SRF in the `informationToSend.messageID.elementaryMessageIDs` IE within the INAP PACUI message. The ID(s) must be coordiated with the SRF. The definitions of these IDs may depend on the specified language. If there is one ID, the definition may include a mixture of audio files and variable parts. If there is more than one ID, the definition may only include audio files (no variable parts).
`variables`	Table of Tables	As for `.inap_interaction` `announcement.variables`.

The language used will be the language specified by the most recent invocation of .set_language or any default used by the SRF.

The minimum number of digits will be 1.

The maximum number of digits will be 1.

All other interaction and SRF connection parameters will have their default values.

The inap_collect_digit method returns the same table structure as inap_interaction.

Example (simple menu):

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

local scc = ...

local MAIN_MENU_ID = 733

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

return