IVR Menu

Menu: (Apps-IVR Menu)

This is often used as an Auto Attendant. For example a company may have a recording that says for "Sales press 1 Support press 2 for Billing press 3 otherwise stay hold and someone will answer your call." Can perform the Auto Attendant task well. However it is not limited to that alone. It is also a powerful tool for Interactive Voice Response and can be used to do the more advanced work that is often expected of IVRs.

IVR Menu supports the use of stacked actions - this is where you have multiple actions that you want carried out in order when a person makes a single selection from the menu, for instance if you want to play a message and then transfer the call to an extension (see example: IVR Menu#Playing a message and then transferring). See the note in the IVR Menu#Troubleshooting if your stacked actions do not execute in the expected order.

Music on hold when you transfer a call from IVR

By default, if you transfer a call to an extension from an IVR the caller will hear music on hold while waiting for the call to be answered. If you would prefer a ring sound then you can do one of two options:

• set transfer_ringback=${us-ring} in a dialplan entry immediately prior to the IVR
• add an extra entry to each option in your IVR, before the transfer but with the same option number and have it execute the line below

menu-exec-app:set transfer_ringback=${us-ring}

However, to make this work you need to do two other things first:

1. you need to go to the FusionPBX System-Variables page and create a new variable in the Music on Hold section (with an order higher than the hold_music variable - you could use 500 for example). The new variable will be transfer_ringback and you should set it to $${hold_music} and enable it.

2. you need to go to the FusionPBX Dialplan-Dialplan Manager and click on the advanced button. Then once the XML edit window is displayed scroll down in the XML until you find "Local_Extension". Note that if you press CTRL-F a search window will appear and you can search on that - include the " characters when you search or you will get another entry that isn't relevant. The entry you should find is <extension name="Local_Extension">. A few lines below that you will find <action application="set" data="transfer_ringback=$${hold_music}"/>. You can either remove this line or comment it out - to comment it add !-- after the < at the start of the line and add -- before the > at the end of the line.

The reason that you need to make these changes is that the default config provided in freeswitch (and FusionPBX) is a demonstration config and is intended to be customised by people when it is implemented in a live system. The problem with having the transfer_ringback entry in this section is that it prevents you overriding the default setting, as every time a call is transferred to an extension the transfer_ringback is set to music on hold. Therefore step 1 here sets a default setting in vars.xml and step 2 removes the line that sets the variable every time a transfer happens. Now the change above is able to allow you to override the default setting whenever you want to.

This will replace the music on hold with ringing sounds when you are transferring from an IVR.

Playing a recording from an IVR choice

Use

menu-play-sound:sound_file_name.wav

Note that this will expect to find the recording in sounds/en/us/callie. If you want to play it from recordings you will need to use

menu-play-sound:../../../../recordings/sound_file_name.wav

Version 3.7.1 Dev commit 7565 changed the default playback of recording, although the instructions above should still work, using the dropdown will instead use lua streamfile.lua "filename". With the new method several DTMF options are available during playback.

• end playback

0 start over 1 volume down 3 volume up 4 back 5 seconds 5 pause toggle 6 forward 5 seconds 7 increase playback speed 9 decrease playback speed

Playing a message and then transferring

To play a message and then transfer it to its destination do the following:

1. Add an option in the menu (example: 5)
2. Click the carat button next to the destination box
3. Paste in menu-play-sound:../../../../recordings/sound_file_name.wav (replace with your file see above for more info)
4. set the order to 0
5. Enter in a description (example:play transfer message)
6. Save
7. Add a new option
8. Enter in the same option number (example: 5)
9. Select the destination to transfer to
10. set the order to 1
11. Enter in a good description (example: transferring to destination)
12. Save
13. go to System->Apply Settings
14. Call ivr menu to test and it should play the sound file and transfer you to the destination.

Timing out of the IVR and doing something else

By default, an IVR is configured to repeat 3 times if there is no response and then hangup. If you need to change this behaviour click on the advanced button in the IVR screen and change 'max timeouts' to 1 (or whatever you require). With 1 it will play the IVR once and if no selection is made it will hangup. Next, rather than dialing the IVR directly, create a dial plan entry with: action: set hangup_after_bridge=true, action: ivr the_name_of_your_ivr, action: bridge where_you_want_the_call_to_go_when_no_ivr_response_is_given This will now cause the unselected IVR to fail over to the destination you specified instead.

Prefix the Caller ID

To prefix the caller id to know where a customer/client has come from add the following line to your ivr options. Its is a good idea to keep things short. In the following example we will be prefixing a c: to the caller's name to denote a customer. replace c: with what ever you would like the prefix to be.

menu-exec-app:set caller_id_name=c:${caller_id_name}

Valid Caller ID Characters

A-Za-Z0-9
.-#$%&*()_+!|^'[];?,~{}=+`

Invalid Characters

\:@/"

caller_id_name doesn't work. FreeSWITCH docs say this cannot be set. The variable gets set; however the changes don't get passed. The solution is to use effective_caller_id_name. It also appears that a ':' doesn't work. So don't use it.

menu-exec-app:set effective_caller_id_name=YOUR_PREFIX-${caller_id_name}

IVR Menu Option List

The recording presents options to the caller. Options match key presses (DTMF digits) from the caller which directs the call to the destinations.

Option	Destination	Order	Description
/^(10[01][0-9])$/	Transfer $1 default	0	Transfer to extension
1	Ivr IVR-Submenu	10	Option 1 Submenu
2	Set effective_caller_id_name=bill-${caller_id_name}	19	Billing Set CallerID
2	Transfer Some_hunt_group default	20	Billing XFR Hunt Group

Beginner Sample Setup

These instructions are current for version 7.4.1 . Getting a basic IVR working is supposed to be trivial, but I wasted hours going down wrong paths.

Assume you have some phone extensions and a trunk working already.

Start by creating a new IVR menu entry. Specify the following:

• Name
• Extension (make this a new extension different from any existing ones)
• Greet Long (just choose one of the .wav files)
• Set Direct Dial to True
• Set an option if you want. I chose Option 1 to transfer to an extension (destination: "123 xml default" for extension 123)

Now create a new Inbound Route.

• Give it a name
• Do NOT click the "Add" button. Instead, click "Advanced" in the top right corner. This will reveal "Condition 1" and "Condition 2". Set "Condition 1" to "Destination Number" and "Expression" to the incoming DID.
• For "Action 1" find your IVR menu entry and choose it.

Now if you dial the DID you should get your basic IVR menu. You can then customize the menu with recordings and better options and so on.

It is important to create the IVR menu entry before creating the incoming route, unless you know your way around the system already.

Trouble Shooting

• IVR menu doesn't respond to key presses:
  • Your incoming provider may be sending the dtmf in a different form Edit your inbound route (DialPlan->Inbound Routes) and add in an option:

Tag: Action
Type: start_dtmf
Data: 
Order: 2 (depends on your configuration usually it should follow the destination number and happen before transfering)

• Using stacked actions for a selection in an IVR doesn't work as expected
  • Freeswitch versions earlier than September 2010 (not sure of the exact date for the change) were affected by a bug that caused stacked options to be executed in REVERSE ORDER. If you are using an old version you therefore have two options:

1. upgrade Freeswitch to a newer version
2. reverse the order of your action stack so that the action you want executed first is last and the last is first.