Navigation :

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: When received as a digit within a PA/PACUI Number variable part, this will be spoken as "Star" (if the language Codec supports it). When collected via DTMF or SIP RTP Telephony Event, `` is encoded as this hex digit to return in `digitsResponse` of the `PromptAndCollectUserInformationResult`. When received as a Cancel Digit, End of Input Digit, or Start Digit in `PromptAndCollectUserInformation`, this digit matches a `` via DTMF or SIP RTP Event. (Default = `B`).
`scp_hash_digit`	`[A-F]`	The hex digit used to represent "Hash" when communicating with the SCP, specifically: When received as a digit within a PA/PACUI Number variable part, this will be spoken as "Hash" (if the language Codec supports it). When collected via DTMF or SIP RTP Telephony Event, `#` is encoded as this hex digit to return in `digitsResponse` of the `PromptAndCollectUserInformationResult`. When received as a Cancel Digit, End of Input Digit, or Start Digit in `PromptAndCollectUserInformation`, this digit matches a `#` via DTMF or SIP RTP Event. (Default = `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.