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