IVR Nodes

An interactive voice response (IVR) node is a simple way to play an audio file to the caller. Using multiple IVR nodes, more complex dialogs can be built with the system.

In IVR node can operate autonomously or interact with an external application server. It collects input from the user or from within the system, and calculates what to do next based on extended regular expressions (ERE). An IVR node can be configured for complex tasks so that callers can for example enter account numbers and pay bills through an external application server.

When a caller reaches an IVR node, the system plays back the prompt that has been set for that IVR node. Once the caller answers the system by pressing the required digit(s), the system will continue processing the call. This first IVR node is typically used as an entry door into the system, and the nodes that follow are used to decide how to proceed next with the caller. For example, the IVR node can ask the customer for account information then ask an external application server where the customer should go from there. Based on the answer from the external application server, the customer is routed to the appropriate waiting queue.

An IVR node can also be used to define dialog that will be used to process calls. In this case, each node plays one prompt and asks a specific question to the caller. The first prompt may ask the caller what language is preferred and then dispatch the caller into two different node systems for two different languages. This IVR node mechanism is very flexible and allows you to either process the input internally in the system or use an external application server to decide where to go next. The IVR node collects the user input according to the list of ERE expressions that was entered in the node’s match list. In the simplest case, a static routing is sufficient without consulting the external server, but it depends on the user input.

IVR node versus auto attendant

The IVR node and auto attendant are two different account types. Auto attendants with basic functionality (routing callers from point A to B) do not need an IVR node and can use the built-in IVR that is available through the auto attendant account.

IVR node have a wide range of features.

List of IVR Nodes

When clicking on the IVR nodes navigation item, the system shows the nodes that are available in the tenant. The list contains the account number of the node and the name. Clicking on the number will edit the node.

Adding an IVR Node

• In the account number(s) field, enter an account number. If you wish to give the node multiple names, use a semiconon to seperate the numbers. You can also use phone numbers (DID) as number.
• In the display name field, enter a descriptive name for the node.
• The system will automatically generate a profile picture for the group. If you can, use a different picture for the node.
• If you want to use settings from another node, you can have those settings being cloned from that node in the clone settings from account field.

IVR Node Settings

Identity

Account Number(s): The number or numbers assigned to this account.

Name: A descriptive name for the account.

Short name: A short name for the account. This short name is used in places where there is not much space, for example on soft labels of certain VoIP phones.

Note field: A general purpose for taking notes on the account. This field is not used by the PBX and it is only visible to the administrator.

Outbound number (ANI): The IVR node uses an ANI (automatic number identification) when sending a caller to an external number. For more information, see Trunk ANI.

Profile picture: You can load a new profile picture for the account.

Account class name: The account class name for the account, which can be used for billing purposes.

Settings

WAV File: This setting is used to set up the audio file that will be played when the IVR node gets called. This can be either an audio file or a text that the system converts into an audio file.

Dial Plan for outbound calls: Choose the dial plan that you would like the system to use when routing calls to an outside number.

Send daily CDR report: The system can send daily, weekly, monthly and quarterly email reports about the activity of the group. For more information see Call Reports.

DTMF Match List: The IVR node keeps track of the DTMF that the user has entered since entering the node. The DTMF match list contains a list of patterns that the system will try to match. The patterns are seperated by spaces and have the following format:

• Each pattern must contain two fields separated by a character that does not occur anywhere else in the string, for example !.
• The first field contains the extended regular expression that is matched agains the input. For example a pattern 123 would match any input that contains the sequence 123 and ^8[0-9]{2}$ would match all 3-digit numbers starting with an 8.
• The second field contains the destination in case there was a match. Input matches can be referenced with the \ escape sequence. For example, if the input was 1234 and the pattern was 1([0-3]*)4 and the replacement was ivr\1, the destination would be ivr23.

If there is no list of actions set up, the system will call the destination. A destination of - will disconnect the call. If the number does not match an account number, the default dial plan of the domain will be used.

Special digits

An E (end of message) or T (timeout) can also be used in the string to indicate when the call should be sent to the specified extension. For example, !E!70! will send the call to account 70 at the end of the message, and !T!70! will send it to account 70 at the end of the timeout. The timeout relies on the IVR account's timeout setting.

From-based routing match list: This field uses a similar syntax like the DTMF field. Instead of waiting for user input, the system feeds the caller-ID into this field. If it matches, it redirects the call to the resulting number and does not play back the audio file.

To-based routing match list: Same like the from-based list, but for the callee.

List of actions: If no list of actions is specified in the account, the system will call the destination from the pattern matching process. Multiple actions are seperated by spaces. If the list of actions is available, it will take actions according to the following table (see below).

IVR language: The language that should be used for the node. This setting is only relevant when using text-to-speech.

Timeout: A timeout symbol T is triggered by the system after (1) the call enters the node and the user does not press any digit or (2) after the last digit.

Pause after playback: This setting inserts extra silence after the playback.

Remote application control: If this flag is enabled, the system will expect an external application server to control the flag. This is typically done through CSTA.

Mute when user presses a key: When this flag it set, the system will mute the audio playback.

Record calls: When this setting is enabled, the system will record calls in the node. The recordings can later be retrieved and reviewed.

Recording Messages

In addition to uploading audio content by the administrator through the web front end, messages can be recorded using the Record Message (*98) star code. The code takes the form *98xxx, where xxx is the account number of the IVR node.

tip

In order to record audio, an extension needs to have permission to record audio for groups. See groups for more information.

Input processing

The following input is available:

• When the caller enters a digit, the PBX appends that digit to the input for that IVR node. The input string is cleared when the IVR node is being called (also when coming from another IVR node).
• When the IVR node audio announcement ends, the PBX acts as if the user entered a E digit.
• When the timeout kicks in, the PBX acts as if the user entered a T digit.

The "DTMF Match List" contains a list of match patterns that are checked. The list elements are separated by space. Each pattern contains of two fields. The fields are separated by any character that does not occur anywhere else in the string, for example !. The first field contains the extended regular expression and the second field the replacement. The field has the same meaning as the fields in the dial plan. The second field contains the destination.

The destination may be any dialable number. If the number requires a dial plan, the default dial plan of the domain will be used. If the destination field contains a single dash (-) and the pattern matches, the PBX will disconnect the call.

A simple replacement where the caller enters 0 and is sent to extension 500 would be !0!500!. An example pattern that waits until a user has entered three digits and then returns the three digits would look like this: !^([0-9]{3})$!\1!.

The other two fields, "From-based routing match list" and "To-based routing match list" are used when the PBX opens the IVR node. The format is the same like in the "DTMF Match List". If there is a match with the "From" or the "To"-header of the call, then the IVR node immediately switches the destination without playing the WAV file. This way, you can implement flexible routing schemes.

The timeout specified in the "Timeout" field starts either when the PBX sends the call to the IVR node or then the user enters a digit.

If no "List of actions" is specified in the account, the PBX will take the output of the pattern matching as the name of the account to switch to. If the "List of actions" is available, it will pass the destination to the application for further decision what to do with it. See Linking External Application Server to an IVR Node for more information about the SOAP processing.

The following table summarizes possible actions:

Scheme	Meaning	Example
action:lang	Set the language for the call. The value parameter contains the language code (2 digits).	action:lang?value=fr
action:goto	Call the number. The dest parameter contains the number to be called.	action:goto?value=88{input}
action:refer	Transfer the call. The dest parameter contains the number to be called.	action:refer?value=88{input}
action:bye	Disconnect the call	action:bye
action:cmc	Set the client matter code (cmc) for the call. The value parameter contains the code.	action:cmc?value={input}
action:set	Change setting. The name parameter contains the name of the setting to be changed, the value parameter the value. If available, the account parameter indicates which account should be affected (default is the IVR node of the call).	action:set?name=dnd&value=false&account={input}
action:dialpan	Change the dial plan. The plan parameter contains the name of the dial plan. If available, the account parameter indicates which account should change the dial plan (default is the IVR node of the call).	action:dialplan?plan=Standard+Dial+Plan
action:url	Trigger a webhook.	action:url
http, https	Use an external application server (deprecated).	https://app-srv.example.com/do

Webhooks vs. SOAP

The action:url action and using a HTTP request are different. The first one triggers a webhook while the second triggers a SOAP request. SOAP is an outdated technology but has not been removed from the PBX.

Action URL

When using a webhook action, the system will provide the following parameters:

Parameter	Value
cnam	The name of the caller
from	The number of the caller
to	The number of the callee
account	The account ID of IVR account
domain	The DNS address of the tenant
input	The input that was entered by the caller

The response from the webhook will be parsed using the Destination RegEx. This is a simple text match of the server response, even if the server responds with XML or JSON. For example, to find a response in a XML that would contain a <result>123</result>, a RegEx like !<result>([0-9]+)</result>!\1 could do the job of locating the result.

Using IVR Node to change extension parameters

One of the features about the IVR nodes is that you can use it to change extension parameters. The name of the setting is in the "name" parameter, the value in the "value" parameter. You can use parameter substitution (for example, "{input}") to set a value that was entered by the user. The account that will be changed can be in the parameter "account" (starting with version 64.1); if it is not present it will set the account that was returned by the regular expression matching.

Let's consider an example on how to reset the message waiting indicator of an extension using an IVR node. Following has to be setup on the PBX before we can use this feature

• On the IVR node 555, The DTMF match list is set to !([0-9]*)#!\1! (extension number followed by a #)
• Set action:set?name=vm_indicator&value=0/0 (0/0) under "List of actions"
• Enter something like "Please enter the extension number to reset the MWI, followed by the # sign" into the audio field (text mode)

Once this is setup, if the operator wants to reset the voice mail for extension 200, the following steps need to be taken:

• Dial 555 (this is the reset-voicemail IVR node)
• Listens to the above set prompt, "Please enter the extension number to reset the MWI, followed by the # sign"
• Presses the "extension number + #" (say, 200#)
• Hangs up

At this point, the voicemail indicator for extension 200 is reset. Now you have to reboot the phone and the vm indicator on the phone will go away.

Transfer

The PBX can also generate a REFER request on the leg that has called. For that use the action referwith the parameter dest. For example, action:refer?dest={input} will send a REFER to the calling leg and asks it to dial the number that was the result of the extended regular expression matching, typically the user input.

Outbound Calling

You can initiate a IVR node call from the REST API. This will call the number that you provide instead of having that number call the PBX. The dial plan of the IVR node will be used to make that call.

This feature makes it possible to call numbers up, for example to notify them about upcoming events and collect the feedback via the Action URL feature of the IVR node.

The REST call uses the GET method and has the following format: /rest/ivrnode/node@domain/dial/number. You may include a parameter timeout that shows how long the PBX should wait before disconnecting the call before the call connects. For example https://pbx/rest/ivrnode/77@pbx.com/dial/2121234567?timeout=30 would dial 2121234567 from IVR node 77 in tenant pbx.com with a timeout of 30 seconds.

All URL components must be properly URL-encoded. The request must have at least domain authentication, either by a session or by Basic authentication header.

Uploading Audio Content

When uploading audio content from the web interface, the browser will convert the audio file automatically into the right format (starting with version 69.3.1). Otherwise the file must be WAV mono, 8kHz and 16 bit/sample.

When using a script to upload content, that format conversion does not take place. Uploading content can be done using the REST API with the following format: /rest/ivrnode/node@domain/wave. The attachment of the POSTis the WAV file. The file must be 8 kHz, mono, 128 kbit/s linear audio. If there is no attachment, the WAV file will be deleted.

This feature can be useful to make the annoucement dynamic, for example include a time and a date in a upcoming appointment reminder. Because there is only one WAV file upload per IVR node, you must ensure that there are no overlapping uploads when you perform batch annoucements.