Navigation :

N2IVR (VXML) Lua Application

N2IVR (VXML) 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 VXML-controlled interactions. In this mode:

SIP/RTP is used for audio stream control.
The VoiceXML interpreter controls the announcements played and interaction requests made to the caller.

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 (VXML) Deployment Guide page which defines all of the components which are required to implement the N2IVR (VXML) solution in a typical deployment model.

Here is a N2IVR (VXML) Lua Application config example showing the specific configuration within the LogicApp.

    <application name="VXML-IVR" module="LogicApp" admin_alloc="1m" user_alloc="64m">
        <include>
            <lib>../apps/logic/lib</lib>
            <lib>../../n2sip/lib</lib>
            <lib>../apps/rest_c/lib</lib>
        </include>
        <parameters>
            <parameter name="edr_enabled" value="1"/>
            <parameter name="default_edr_app_name" value="EDR"/>
            <parameter name="default_edr_stream_key" value="vxmlivr"/>
            <parameter name="trace_level" value="0"/>
            <parameter name="max_trace_level" value="3"/>
            <parameter name="trace_per_second" value="20"/>
            <parameter name="default_lua_lib_path" value="../lua/lib/?.lua;../lua/lib/3rdparty/?.lua;../../n2sip/lua/lib/?.lua"/>
            <parameter name="default_rest_app_name" value="VXML-REST-Client"/>
        </parameters>
        <config>
            <services>
                <service module="LhoSipApp::LhoSipIncallLuaService"
                    libs="../../n2sip/apps/lho_sip/lib"
                    script_dir="../../n2sip/lua/svc"
                    >

                    <globals>
                        <!-- section for custom configuration for the VXML IVR service -->
                    </globals>

                    <script_check_secs>5</script_check_secs>

                    <triggers>
                        <!-- section for explicitly defining the called party numbers which trigger the IVR VXML interpreter -->
                        <trigger called_prefix="64" script_key="n2ivr_vxml"/>
                    </triggers>
                </service>
            </services>
            <agents>
                <agent module="LhoSipApp::LhoSipOutcallLuaAgent" libs="../../n2sip/apps/lho_sip/lib"/>
                <agent module="VxmlLuaAgent" libs="../../n2sip/apps/vxml_lua_agent/"/>
            </agents>
        </config>
    </application>

Configuration Details

Parameters

The default_lua_lib_path must include the n2svcd and n2sip default lua/lib paths. The default_rest_app_name must point to a REST Client app which will be used to request VoiceXML documents from a VoiceXML server.

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 (VXML) 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_vxml.lua.

Agents

The VXML service requires the use of the VxmlLuaAgent for querying VoiceXML servers.

Triggers

At least one trigger must be defined which points to the script with script_key configured as n2ivr_vxml. Refer to the LhoSipIncallLuaService configuration page for possible trigger-matching parameters.

Globals

SERVICE_IDENTIFICATION

The SERVICE_IDENTIFICATION global parameter must be defined for the service. This array of mappings will define which VoiceXML document URI should be used to retrieve the initial VoiceXML document for each possible inbound called prefix

Refer to the Logic App Configuration page for a description of how to defined global constants as arrays. The SERVICE_IDENTIFICATION must be an array of hashes. The format is as follows:

    <global name="SERVICE_IDENTIFICATION" type="array">
        <mapping type="hash"> <called_prefix>64910010011</called_prefix> <uri>https://voicexml.nsquared.nz/info.jsp</uri> </mapping>
        <!-- more mappings as required can be defined -->
    </global>

Each <mapping> must have the following elements defined, which become key/value pairs of the mapping itself:

Property	Description
`called_prefix`	The prefix of the called party number (taken from the `To:` SIP header) to match against a mapping. More specific mappings must be defined before less specific mappings.
`uri`	The HTTP(S) URI to retrieve the first VoiceXML document from, for the call interaction. If the host & port are not defined, then the default host and port of the associated `RestClientApp` will be used. Note that any SSL/TLS connectivity required must be defined on the `RestClientApp` itself.

VXML_SESSION_VARIABLES

The VXML_SESSION_VARIABLES global parameter may be defined for the service. This table of session varaibles will be made available as session variables to the VoiceXML interpreter and can be accessed within VoiceXML documents using:

    <var name="myvar" expr="session.connection.aai"/>

All listed properties will become session variables.

Refer to the Logic App Configuration page for a description of how to defined global constants such as VXML_SESSION_VARIABLES. The VXML_SESSION_VARIABLES value if declared must be a hash, with the element names as the session variable name, and element values as the session variable values.

For example, VXML_SESSION_VARIABLES might be defined as:

    <global name="VXML_SESSION_VARIABLES" type="hash">
        <connection.aai>VXML Application (N2IVR)</connection.aai>
    </global>

VXML_PROPERTIES

The VXML_PROPERTIES global parameter may be defined for the service. This table of properties will define the initial value of VoiceXML properties, i.e. those document in Section 6.3 of the VoiceXML 2.0 specification. Properties not listed in this table are ignored by the N2IVR VXML interpreter and need not be defined. If defined, they will be ignored.

Refer to the Logic App Configuration page for a description of how to defined global constants such as VXML_PROPERTIES. The VXML_PROPERTIES value if declared must be an object. Any of the following properties may be defined. If a property is not defined, the default as described will be used.

Property	Default	Description
`interdigittimeout`	4s	The inter-digit timeout value to use when recognizing DTMF input. Defined as a Time Designation value.
`termtimeout`	0s	The terminating timeout to use when recognizing DTMF input. Defined as a Time Designation value.
`termchar`	#	This is the termination digit to use to determine input termination by the user during an IVR interaction. This must be defined as one of: 0,1,2,3,4,5,6,7,8,9,*,#. The termination digit may be undefined. When undefined, the default termination digit for the IVR RTP application will be used.
`bargein`	true	Whether to allow users to interrupt announcements being played with DTMF digits. Default is true. May be set to "true" or "false".
`bargeintype`	speech	Type of announcement interrupt analysis to use. The N2IVR only supports "speech" interrupts (i.e. DTMF detection). When "hotword" is defined, the IVR will raise an error during call processing.
`timeout`	8s	The timeout waiting for the user to input a DTMF tone before a noinput event is generated by the VXML interpreter. Defined as a Time Designation value.
`documentmaxstale`		The maximum 'staleness' to allow for cached documents. Set to an empty value by default, which causes the VXML HTTP request engine to not define the `Cache-Control` `max-stale` header value. When specified, must be specified as a number indicating the number of seconds to allow stale cache value to be used. Note that the VXML IVR does not cache documents. This value is only relevant if a downstream HTTP proxy is caching VXML documents.
`documentmaxage`		The maximum age a downstream HTTP cache should allow when providing cached documents in response to a HTTP request by the VXML IVR. When set to an empty value (the default), the HTTP request engine will not set the the `Cache-Control` `max-age` header value. When specified, must be specified as a number indicating the maximum age (in seconds) a reqested document may be before a fresh document must be retrieved. Note that the VXML IVR does not cache documents. This value is only relevant if a downstream HTTP proxy is caching VXML documents.
`documentfetchhint`	safe	When set to `safe` all requests for documents by the VXML IVR will be made at the time the document is required. A value of `prefech` is ignored (all HTTP requests for documents are performed in safe mode)
`audiomaxstale`		Ignored. All audio is read at the moment it is required from the IVR's local audio storage - whether from disk, or local database.
`audiomaxage`		Ignored. All audio is read at the moment it is required from the IVR's local audio storage - whether from disk, or local database.
`audiofetchhint`	prefech	Ignored. All audio is read at the moment it is required from the IVR's local audio storage - whether from disk, or local database.
`fetchaudio`		When audio should be played to the caller during the retrieval of documents from a VoiceXML server, the audio file to play must be defined by this property. The value of this property must be a valid audio file name as stored by the IVR.
`fetchaudiodelay`	2s	The delay before initiating playback to the caller of the audio defined by the fetchaudio parameter. Defined as a Time Designation value.
`fetchaudiominimum`	5s	The minimum time to play the audio defined by fetchaudio once started. If the VXML IVR receives the VXML document prior to this minimum timeframe completing, then execution of the document is delayed until the minimum timeframe is complete.
`fetchtimeout`	0s	Ignored. All audio is read at the moment it is required from the IVR's local audio storage - whether from disk, or local database. Defined as a Time Designation value.
`maxnbest`	1	Ignored. In this N2IVR VXML service release, `maxnbest` is always limited to 1.

MERGE_EDRS

The MERGE_EDRS global parameter may be defined for the service. This boolean defines whether the VXML IVR will generate a single EDR per call handled, or an EDR per document processed.

The default approach is for the service to generate an EDR for each document processed. Set this variable to true to generate a single EDR for each handled SIP call.

    <global name="MERGE_EDRS" type="boolean">true</global>

MAX_REENTRIES

The MAX_REENTRIES global parameter may be defined for the service. This variable defines the maximum number of times a transition from one code block in a VXML document can be made to another code block within thes same VXML document. This occurs with <goto> commands using hash references to blocks in the same VXML document. It also occurs when formitems are iterated through.

This variable ensures infinite loops do not occur. The default is set to 1000.

    <global name="MAX_REENTRIES" type="integer">800</global>

MAX_TRANSITIONS

The MAX_TRANSITIONS global parameter may be defined for the service. This variable defines the maximum number of transitions allowed between VoiceXML documents (whether triggered via <goto> requires or <submit>).

This variable ensures infinite loops do not occur. The default is set to 10.

    <global name="MAX_TRANSITIONS" type="integer">20</global>

DEFAULT_LANGUAGE

The DEFAULT_LANGUAGE global parameter may be defined for the service. This variable defines the name, as known in N2IVR’s UI configuration and in the N2IVR database, of the language to treat as the default to use for audio announcements.

    <global name="DEFAULT_LANGUAGE">English</global>

LANGUAGE_MAPPING

The LANGUAGE_MAPPING global parameter may be defined for the service. This hash defines the mapping of xml:lang attributes that may be present in VoiceXML documents to named languages in the N2IVR configuration. Where a VoiceXML document language is defined without a mapping, or where a VoiceXML document does not have a xml:lang attribute, the default langauge will be used.

    <global name="LANGUAGE_MAPPING" type="hash">
        <en-EN>English</en-EN>
    </global>

Time Designation Values

VoiceXML time designation values are supported as configuration values for variables and properties where appropriate. A time designation value is a number, such as 250 or 1.1 or +0.5 followed by either ms (indicating milliseconds) or s (seconds).

Example values:

1s
250ms
+3.0s