IVR Menu
Menu: (Apps-IVR Menu)
This is often used to setup 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." While it performs the Auto Attendant task well, it is not limited to that. 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.
Contents
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 SkyPBX 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 SkyPBX 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 Sky Dance (and SkyPBX) 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:
- Add an option in the menu (example: 5)
- Click the carat button next to the destination box
- Paste in menu-play-sound:../../../../recordings/sound_file_name.wav (replace with your file see above for more info)
- set the order to 0
- Enter in a description (example:play transfer message)
- Save
- Add a new option
- Enter in the same option number (example: 5)
- Select the destination to transfer to
- set the order to 1
- Enter in a good description (example: transferring to destination)
- Save
- go to System->Apply Settings
- 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. 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 |
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.