An issue with the default IVR behaviour

When you dial into a phone system and are greeted by an IVR, if you choose an option on the IVR that you expect to be answered by a human you expect to hear the phone ringing as you wait for a human to pick it up.  However, due to the way the Local_Extension is defined in the default FreeSwitch dialplan, it will instead play music on hold to the caller and there is nothing you can do to override that setting without altering the FreeSwitch dialplan.

Typically when a human transfers a call you expect to get music on hold while they do that for you (sometimes people like to make an exception for calls transferred by the receptionist, but even then, music on hold would be appropriate), but when an IVR transfers a call you do not expect to be placed on hold as the IVR is a computer and should be giving you its full attention, not placing you on hold while it does something else - therefore you expect to hear a ringing sound if the IVR transfers you to a human.

Accordingly the following steps allow you to alter this behaviour and override the music on hold in order to provide a ringing sound to the caller when transferring a call from an IVR.

1. you need to go to the FusionPBX System-Variables screen 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-Dial Plan 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 .  A few lines below that you will find .  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 any time you prefer a ringing sound when you do a transfer from an IVR you can use one of two options:

1. set transfer_ringback=${us-ring} in a dialplan entry immediately prior to the IVR
2. 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}

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

Simple recording management in FusionPBX

I wanted to be able to play a message to callers and to make it easy for users of the phone system to update the message without needing to understand how to administer the phone system.  So I developed a javascript that can be used to do this.  If you want to use it, download the javascript from here: easyrecording.js  and save it in the scripts subdirectory of your freeswitch folder (on my system this is /usr/local/freeswitch/scripts).

This script is designed to allow you to setup a message that users can update directly from their phones without needing to do any administration of the phone system directly.  It uses four channel variables which must be set depending on the mode used, prior to calling the script:
    mode, filename, title, auth
Note that this script generally relies on speech synthesis to prompt the user as (a) the user is an administrator of the system and therefore prettiness is not important, (b) the script does not need to be supplied with any additional files.  Because speech synthesis is used, if you type a response while the speech is occurring the speech will not stop, however your response will be noted and processed at the end of the speech.  Accordingly the flite module will need to be enabled on your system in order to use this script.

It has six modes:
1. mode=play
    filename=the name of the file you want to play (without any extension as wav is assumed)
    In this mode, it will play the file from /usr/local/freeswitch/recordings/easyrecording/.  If the recording does not exist it will play an error message.  Moral of the story - record all your recordings before users get to hear them!
2. mode=record
    filename=the name of the file you want to record (without any extension as wav is assumed)
    title=an introductory heading for the recording menus that are used when the user is updating this recording
    optional: auth="permit" will result in authentication not being required to change recordings
    In this mode the user will first hear the current message and then be given the ability to re-record it and confirm that they are happy with it before replacing the original recording.  If auth is not set then the script will assume that the user is maintaining only the current recording and will prompt for the pin for that specific recording - in this case, no channel variable will be set when they authenticate.  Note that recordings that are no longer required can be manually deleted from /usr/local/freeswitch/recordings/easyrecordings.
3. mode=auth
    filename=the name of the menu structure that you are authenticating the user for.  This is not actually a filename but is simply used to represent the menu structure in the pin database.
    title=an introductory heading for the menu structure
    In this mode, the user will be authenticated and the auth channel variable will be set to "permit" if the user enters a valid pin.  This mode is intended to be used at the start of an IVR for maintaining multiple recordings.  Until they hangup, thus ending the authorised session, they will be able to update any recording listed in the IVR.
4. mode=pinreset
    In this mode the master pin can be used to change any other pin if someone forgets their pin.  It can also be used to remove obsolete pin registrations from the database as to change a pin it is simply deleted - which resets it to the default pin of 7777.
5. mode=setmasterpin
    This allows you to set the master pin.  It should only be known by the phone system administrator.  The dialplan entry you use to run this should be removed as soon as you have set the master pin.  Assuming you don't forget it you will never need to use this mode again.
6. mode=maintenance
    In maintenance mode you are presented with a list of all the recordings and you can choose to re-record any of them. This script is designed such that you can create an IVR to do this for specific recordings where you want to give one person responsibility to maintain a subset of recordings, but if you only have a small system then it may be simplest for one person or group of people to maintain all recordings and this is where this mode can be used.  You may still want to have a different individual maintain some recordings, and that is fine, you can set up an IVR for them to use.
The first time a recording is made or authorisation is required, the user will be asked to enter the default pin.  The default pin is 7777.  It cannot be used at any other time except to set a pin the first time the pin is used.  When the phone system administrator sets up a menu using the easy recording system they will need to inform the user who will be maintaining it that they must use this pin when they set the recording the first time but that they will get to set their own pin at that time.

As an example.  I am setting up a simple phone system for a small business.  They will have one person who maintains all recordings and I'm going to get them to do it using the built in maintenance mode.  To make the initial recordings I have set up a dialplan entry called "temporary" with the following definition:

Tag	Type	Data	Order
condition	destination_number	^1$	1
action	set	title=Main menu choices I V R	0
action	set	mode=record	3
action	set	filename=../main_ivr	4
action	javascript	easyrecording.js	13

You will see here that I have separated "I V R" into separate words so that the speech synthesiser will spell them out rather than trying to pronounce the word "ivr".  In my case here, I am recording the choices used to introduce an IVR on the system.  This simplifies my setup of the IVR as now I can just select this recording from the menu once I've recorded it using this temporary dialplan (by dialing 1 from a phone).

You will also note the little trick I've done to make sure that the recording can be used in an IVR - in the filename I have included "../" at the start of it.  This is because, by default, recordings made using easyrecording.js are kept in freeswitch/recordings/easyrecordings - this is perfect for when the recordings are intended to be played back using the easyrecording.js playback method, but if they need to be used with an IVR they will not work if they are in a subdirectory below the recordings directory.  Accordingly, the "../" tells the script to record it directly into the recordings directory rather than the subdirectory.   You would only do this if you need to use your recording with an IVR or something else in freeswitch where it needs it to be in the recordings directory.  The rest of the time you can just enter the filename on its own in this variable.

Note that if you want to use a recording with an IVR, apart from ensuring it is placed directly into the recordings subdirectory you may also want to update the default configuration of the recording in the Apps-Recordings screen in FusionPBX to give it a more meaningful name.  This isn't a necessary step as it will automatically be listed there already, but is required if you want to give the recording a better human readable name than the filename you set for the recording.

Note that even if you are going to do all your recording maintenance using maintenance mode, it is necessary to set a pin on each recording - this is because if you do not set a pin then no record is kept of the recording in the table that is used to operate maintenance mode.  In such a case, the only record of your recording is the recording itself (this would happen if you set auth=permit prior to making your recording - this can be used for doing one off recordings if you desire rather than using the FusionPBX built in recording function accessed by dialing *732673).

After creating this dialplan, apply the settings and dial the number for your dialplan (in my case 1), make your recording, then you can change the title and filename and apply the settings and record another recording - do this until you have an initial recording for each of the messages you want.  Then you can delete this dialplan entry (or disable it if you think you might want it again in the future) and do all your administration of the recorded messages using maintenance mode.

This is the dialplan entry that I've set up to enable them to maintain the recorded messages:

Tag	Type	Data	Order
condition	destination_number	^999990$	1
action	set	mode=maintenance	3
action	javascript	easyrecording.js	4

As you can see, there is nothing to it.

If you are going to play a recording from an IVR entry, you can actually do it with a built in function in the IVR that can play a WAV file for you.  The IVR entry you would need is menu-play-sound:../../../../recordings/easyrecordings/the_name_of_your_recording.wav

I hope this example helps you to experiment with this tool.  If you find this useful I'd love to get feedback.