N2IVR (INAP) Lua Application
N2IVR (INAP) Lua Application Configuration
The N-Squared IVR (Interactive Voice Response) solution supports various distinct control mechanisms.
This page contains information specifically related to the N2IVR when configured to offer INAP-controlled interactions, effectively acting as an INAP SRF. In this mode:
- SIP/RTP is used for audio stream control.
- INAP is used to allow to receive interaction instructions.
Note that the N2IVR (INAP) Lua Application is only an end-point for RTP streams. It does not proxy/transcode RTP packets and does not support the establishment of any B-Legs.
The logic for the N2IVR operating in this mode is defined by a purpose-specific run-time script written in the Lua scripting language, and this page describes the configuration parameters specifically for the Lua Logic script. There is also a general N2IVR (INAP) Deployment Guide page which defines all of the components which are required to implement the N2IVR (INAP) solution in a typical deployment model.
Here is a N2IVR (INAP) Lua Application config example showing the specific configuration within the LogicApp
.
<application name="Logic" module="LogicApp">
<include>
<lib>../apps/logic/lib</lib>
</include>
<parameters>
<parameter name="default_lua_lib_path" value="../lua/lib/?.lua;../../n2sip/lua/lib/?.lua"/>
<parameter name="default_tcap_app_name" value="SIGTRAN"/>
</parameters>
<services>
<service module="LhoSipApp::LhoSipIncallLuaService" libs="../../n2sip/apps/lho_sip/lib"
script_dir="../../n2sip/lua/svc" edr_stream_key="n2ivr">
<globals>
<global name="INAP_CONFIG">
<scps type="array">
<scp id="1" dpc="4114" dssn="106"/>
</scps>
<correlation_id_len type="integer" value="3"/>
<scp_id_location value="before"/>
<scp_id_len type="integer" value="1"/>
<nap_language_extension_id type="integer" value="400"/>
<default_language_name value="English"/>
<languages type="array">
<language id="1" name="English"/>
<language id="2" name="German"/>
</languages>
</global>
</globals>
<triggers >
<trigger to_dtg="IVR" script_key="n2ivr_inap"/>
</triggers>
</service>
...
Configuration Details
Parameters
The default_lua_lib_path
must include the n2svcd and n2sip default lua/lib
paths.
The default_tcap_app_name
must point to the SigtranApp instance which will be used to send AssistRequestInstruction
.
The address of the receiving SCP will be determined from the other configuration.
Service
The LhoSipIncallLuaService
service must be configured as per the LhoSipIncallLuaService Configuration page.
It should have a service-level edr_stream_key
attribute present which defines the default stream key to which the N2IVR (INAP) EDRs will be written.
The service-level script_dir
should be configured as “../../n2sip/lua/svc” which is typically the relative path from the n2svcd/bin
directory to the n2sip/lua/svc
directory which contains the required service script n2ivr_inap.lua
.
Triggers
At least one trigger must be defined which points to the script with script_key
configured as “n2ivr_inap”.
Refer to the LhoSipIncallLuaService
configuration page for possible trigger-matching parameters.
Global
The INAP_CONFIG
global parameter must be defined for the service.
Refer to the Logic App Configuration page for the full description
of how to defined global constants, specifically global structures like INAP_CONFIG
.
The INAP_CONFIG
value must be an object with the following structure:
instruction_timer_ms
|
Integer |
How long the IVR will wait to receive PlayAnnouncement or PromptAndCollectUserInformation
instructions from the controlling application before we consider that control is lost. This applies both to the first
play instruction after the AssistRequestInstructions is sent and for subsequent play instructions.If no instruction is received within the indicated period, the SrpSipApp will
tear down the SIP call and RTP stream and send a TCAP_ABORT message.(Default = 2500 ).
|
provisional_code
|
101 - 199
|
An SIP INVITE provisional response code to send back to the A-Leg at the start of the interaction to
cover the interval during which the IVR sends AssistRequestInstructions to the SCP and waiting for the
first interaction operation to be returned. If no value is configured here, then instead the IVR will send SIP INVITE final 200 OK response on the A-Leg to fully establish the voice channel, prior to sending AssistRequestInstructions to the SCP. (Default = send final 200 OK before sending ARI). |
correlation_id_len
|
Integer |
The number of digits for the CorrelationID parsed from inbound Called Party. (Default = 4). |
scp_id_len
|
Integer |
The number of digits for the SCP ID parsed from inbound Called Party. (Default = 1). |
scp_id_location
|
before / after / Integer
|
Where the SCP ID is located in the incoming Called Party Address. [N > 0] = As a prefix starting N characters from the start of the string.before = As a suffix near the end of the string, before the Correlation ID.after = As a suffix at the end of the string, after the Correlation ID.(Default = after ).
|
tcap_ari_ac
|
cs1_ip / camel2_srf / camel3_srf / camel4_srf
|
The TCAP Application Context to use when sending AssistRequestOperation to the SCP.(Default = cs1_ip ).
|
inap_variant
|
cs1 / camel2 / camel3 / camel4
|
Which INAP protocol variant to use when encoding and decoding INAP messages exchanged with the SCP. (Default = cs1 ).
|
scp_star_digit
|
[A-F]
|
The hex digit used to represent "Star" when communicating with the SCP, specifically:
B ).
|
scp_hash_digit
|
[A-F]
|
The hex digit used to represent "Hash" when communicating with the SCP, specifically:
C ).
|
default_language_name
|
String |
The Default Language Name to use. This must be a known language name for which a Variable Parts Codec is installed into the RtpApp which is responsible for mapping and synthesizing announcements.(Default = "English"). |
nap_language_extension_id
|
Integer |
For all received INAP/CAP PlayAnnouncement and PromptAndCollectUserInformation operations,
the IVR will look for an INAP extension with this numeric Type ID. The extension payload contains an integer language ID value
which is mapped to determine the preferred language name for announcement message ID mapping and for variable parts.The binary encoding of this extension is the "NAP" encoding as defined in the "N2IVR INAP Conformance" document. (Default = 400). |
languages
|
Array |
The Language Name applicable to this integer language identifier (see language_extension_id ).This must be a known language name for which a Variable Parts Codec is installed. (Default = None). |
.languages
|
Object |
Provisions a language whose ID may be provided to us in PlayAnnouncement or PromptAndCollectUserInformation .See below for the attributes of this object. |
.scps
|
Array |
Array of scp elements defining known SCP nodes to receive AssistRequestInstructions .
|
.scp
|
Object |
Provisions an SCP node to which we may send AssistRequestInstructions .See below for the attributes of this object. |
SCP Addresses
Each <scp>
definition in the <scps>
array within INAP_CONFIG
defines the address for a known SCP which is
ready to accept an INAP AssistRequestInstructions
operation.
Each scp
Object in the config
.scps
Array is configured as follows.
Parameter Name | Type | Description |
---|---|---|
id
|
Hex Digits |
[Required] SCP Identifier, as will be given to us in the called party (the To address digits of the SIP INVITE).
|
dri
|
Integer |
Destination SCCP Routing Indicator for this SCP with this <id>.0 = Global Title, 1 = PC+SSN(Default = 0 ).
|
dssn
|
Integer |
Destination SCCP SSN for the SCP with this <id>. [Required when dri = 1 ]
|
dpc
|
Integer |
Destination SCCP Point Code for the SCP with this <id>. [Required when dri = 1 ]
|
dgt_digits
|
Hex Digits |
Destination SCCP Global Title Digits for the SCP with this <id>. [Required when dri = 0 ]
|
dgt_tt
|
Integer | Destination SCCP Global Title Translation Type for the SCP with this <id>. |
dgt_np
|
Integer | Destination SCCP Global Title Numbering Plan for the SCP with this <id>. |
dgt_noa
|
Integer | Destination SCCP Global Title Nature of Address for the SCP with this <id>. |
Languages
Each <language>
definition in the <languages>
array within INAP_CONFIG
defines a numeric language ID
which may be received, and which maps into a local language name string for the purpose of language selection
when generating and/or processing audio using the RtpApp
.
Each language
Object in the config
.scps
Array is configured as follows.
Parameter Name | Type | Description |
---|---|---|
id
|
Integer |
[Required] Language ID, as will be given to us in the PlayAnnouncement or PromptAndCollectUserInformation .
|
name
|
String |
[Required] The Language Name to use when the instructing SCP provides the associated Language ID. This must be a known language name for which a Variable Parts Codec is installed into the RtpApp which is responsible for mapping and synthesizing announcements.
|
Message Handling
The N2IVR (INAP) Lua Application uses the following messages:
- TCAP Messages (TCAP-BEGIN outbound).
- SCC Messages (RTP-ESTABLISH outbound).
This is in addition to the HEARTBEAT and MANAGEMENT messages used by the underlying LogicApp
.