IVR Nodes

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 .

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).

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.

info

Note: The IVR node and auto attendant are two distinct accounts. 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 and can be linked to an external application server .

Creating an IVR Node

• Go to your selected domain in the Vodia PBX web interface.
• Go to auto attendants by clicking on IVR Nodes under Accounts as shown above.
• A pop up window would give you a chance to enter the details in the new GUI.
• On top, click the tab Create to create a new IVR Node.
• In the Account Name field, enter an extension number and/or alias, i.e., a DID number. When entering an alias in addition to an extension number, use the following syntax: 667/9781234567.

info

Note: If you use a space instead of a slash (667 9781234567), you will create two separate accounts that will be unrelated to each other.

• To create multiple accounts at the same time, use a space between the numbers: 667 668 669
• Press Create.
• The IVR Node(s) will be created which you can see in the "IVR Node list" or in "all accounts list", where you can enter each IVR Node just by clicking it, in order to modify it if you want, as explained below.

Setting up an IVR Node

Once you've created an IVR account, use the following information to configure your settings.

Identity

• Account Number(s): This field takes extension number(s) and/or DID number(s). The number of DIDs that can be entered into this field is unlimited.
• Name: This field allows you to create an alias so that you can quickly identify the Account among other Accounts. For example, when creating aliases for an auto attendant, you might use the names Day Auto Attendant and Night Auto Attendant to distinguish the auto attendants from one another.

When choosing a name for a hunt group, use a short name if you plan to use the Group name (calling party) option in the From header to ensure that it will fit into the display of the phone.

Settings

• WAV File: An external recorded announcement can be uploaded in wave format (8-kHz Mono, 16-bit files). Announcements can also be recorded by dialing *98888, where 888 is the IVR node account.
• Dial Plan for outbound calls: Choose the dial plan that you would like the system to use when routing calls to an outside provider.
• ANI: The IVR node uses an ANI (automatic number identification) when sending calls to an external number. For more information, see Trunk ANI .
• Send daily CDR report to: The call data record (CDR) lists all calls that come into the IVR node. The report is sent at midnight each night to the email address specified here.
• DTMF Match List: This field allows you to enter a list of match patterns that will be used by the system to direct a call once a user has pressed a number from the telephone keypad. You can also use pre-coded IVR nodes.
• When entering DTMF match patterns, keep the following criteria in mind:
  • A space is required between list elements.
  • Each pattern must contain two fields separated by a character that does not occur anywhere else in the string, for example !".
  • The first field must contain the extended regular expression, and the second field must contain 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.

warning

Example: To specify that the caller should be directed to extension 500 after pressing 0, enter !0!500!into the DTMF field. To specify that the system should wait until a user has entered three digits before attempting to redirect the call, enter !^([0-9]{3})$!\1!.

info

Note: 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. (Note: The timeout relies on the IVR account's Timeout setting.)

• From-based routing match list: This field requires syntax similar to the DTMF field.
• To-based routing match list: This field is used when the Vodia PBX opens the IVR node. Use the same format as in DTMF Match List above. 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 allows you to implement flexible routing schemes.
• List of actions: If no "List of actions" is specified in the account, the system will assume that the matching pattern is the name of the account to switch to. If the "List of actions" is available, it will take appropriate action, e.g. if it is only a url (like http://appaddress.com), it will pass the destination to the application server (using the URL set in the setting) as a SOAP request to further determine what to do with it, see external application server for details. If the setting is set to action:url (see IVR Node External Application Server ), then it will trigger the action url, found on the action URL tab above. Multiple actions can be specified, separated by a space.
• Accounts that may record a message: Enter the extensions that are allowed to record welcome messages. Use a star (*) to indicate all users.
• Timeout (secs): The timeout specified in this field starts either when the system sends the call to the IVR node or when the user enters a digit.
• Permissions to monitor this account: This setting defines which extensions may monitor the status of this account, for example with a BLF button. By default, all extensions are allowed to see the status of an account. The setting is a list of extensions and wildcard patterns, seperated by space characters. If the list element contains a "np" (no pickup) flag after a colon seperator, then the monitoring will show only if the account is idle or busy. An example for this settings would be "41 42 5* 61:np 70*:np". The "np" flag was introduced in version 61.

Recording Messages

Messages can be recorded using the Record Message (*98) star code, or they can be uploaded through the web interface. Both methods are detailed in the following sections. Users must have permission to record greetings before they can record greetings for an IVR node using *98. The permission is given in the IVR account itself.

Record the Message Directly

To record the message:

1. From the telephone keypad, enter *98.
2. Enter the IVR Node account number.
3. Enter *1 ("1" is the greeting number).
4. Press the Confirm button.

In the example shown above, the IVR node account is "126," and the greeting that is being recorded is greeting 1. The standard greeting is recognized by the system as greeting 0 and can be recorded by entering *98. Use the standard greeting if you want to use the same greeting for all hours of the day and night.

Upload a WAV File

WAV files allow you to record and edit your message before loading it into the system. They also allow you to use professional IVR dialogs. From the IVR Node settings:

1. Click the Choose File button and upload the file (WAV files should be 8 kHz Mono, 16 bit).
2. Click Save.

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 Edigit.
• When the timeout kicks in, the PBX acts as if the user entered a Tdigit.

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 dial able 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.

Using IVR Node to change extension parameters

One of the nice 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

• Create an IVR node, say 555
• On the IVR node 555, set DTMF match list to !([0-9]*)#!\1!(extension number followed by a #)
• Set action:set?name=vm_indicator&value=0/0 (0/0)under "List of actions"
• Upload the proper WAV files (something like "Please enter the extension number to reset the MWI, followed by the # sign")
• Click Save

Once this is setup, if the operator wants to reset the voice mail for extension 200, she

• Picks up any phone and dials 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.

You can use similar setup to modify other extension parameters.

Transfer a call

The PBX can also generate a REFER request on the leg that has called (since version 56.6). 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.

REST API call

Outbound dialing

You can initiate a IVR node call from the REST API (starting at version 5.5). 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 GETmethod and has the following components:

ElementFunction /restGeneral REST API indicator /ivrnodeGeneral indicator for the IVR node /accountID of the IVR node, including the domain name (e.g. 77@localhost) /dialGeneral indicator for the dial function. /destinationDestination to call after one of the hunt group destination picks up.

You may include a parameter timeoutthat 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.

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 WAV files

You may upload a WAV file for an IVR node. 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.

The REST call uses the POSTmethod and has the following components:

ElementFunction /restGeneral REST API indicator /ivrnodeGeneral indicator for the IVR node /accountID of the IVR node, including the domain name (e.g. 77@localhost) /waveGeneral indicator for the WAV upload function.

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.