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:

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:

This is in addition to the HEARTBEAT and MANAGEMENT messages used by the underlying LogicApp.