N2IVR (VXML) Lua Application

To override a hangup code, define the HANGUP_CODES global parameter. This parameter is optional, as is each scenario. If a scenario isn’t defined, the service will use the default.

A HANGUP_CODES global parameter defined with the defaults would be:

    <global name="HANGUP_CODES" type="hash">
        <no_service_error>603</no_service_error>
        <setup_error>500</setup_error>
        <engine_error>500</engine_error>
        <force_decline>603</force_decline>
        <vxml_error>500</vxml_error>
    </global>

Note that the VXML <disconnect> element does not use a hangup code defined by this global parameter. Instead, the VXML <disconnect> element will not hang up with a code as a disconnect would normally be a call end with a BYE.

However if a disconnect should send a code, one can be set by setting the VXML session variable connection.protocol.sip.disconnect_code which can be defined using the VXML_SESSION_VARIABLES global parameter, and/or overridden by individual VXML documents.

VXML_SESSION_VARIABLES

The VXML_SESSION_VARIABLES global parameter may be defined for the service. This table of session variables 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.

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>

The session variable connection.protocol.sip.disconnect_code is special. This session variable will determine the SIP hangup code used when the <disconnect> VXML element is encountered.

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.

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.

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>

AUDIO_SOURCE_INTERPRETATION

The AUDIO_SOURCE_INTERPRETATION global parameter may be defined for the service. This string defines the approach the VXML service will take to interpreting the <audio> element’s src attribute.

By default, the internal N2IVR method is used. This method can also be explicitly defined by setting AUDIO_SOURCE_INTERPRETATION to Internal. The internal method applies the following rules:

1. If src attribute is of the form builtin://messageid then the given messageid (a numeric value) is used as a message ID as configured in the N2IVR.
2. If src attribute is of the form file://.../v/filename then the given filename is used as a variable part name. The final directory path segment can also be set to variable_parts instead of just v.
3. If src attribute is otherwise a file:// URI, the filename is interpreted as a file uploaded and named in the N2IVR with the given name (without prefix).
4. Any other URI formats are treated as an error.

This configuration option can be set to FermaSynthesis in which case the audio source is decoded as per the following rules:

1. The file name without suffix is determined.
2. If the file name matches a numeric value as might be returned by the FermaSynthesis REST API provided by N2IVR then the audio file is played as the identified variable part.
3. If the file name does not match a known variable part, the file name is used as a lookup into the named annoucement files stored by the IVR.

This configuration option can be set to Hook in which case a hook file must also be given, with a method that implements this Lua signature:

--- @param src string The string which defines the source audio
--- @return boolean # On parse failure, return false. Otherwise returns true
--- @return string? # The error string, on failure, or on success the filename
--- @return integer? # On parse success, if a message ID, return the message ID as the third value, and true as the first.
---
function interpret_audio_source (src)
    return false, "Unknown source URI format."
end

Example:

    <global name="AUDIO_SOURCE_INTERPRETATION">FermaSynthesis</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