Introducing the Stealth AutoAttendant for Asterisk 1.4 and FreePBX

Last week we introduced the powerful, new Allison text-to-speech voice for Asterisk® using Cepstral. Now that Allison is an integral part of your free PBX in a Flash server, let's put her to good use. Today we're going to roll up our sleeves and show you how to build a typical Interactive Voice Response (IVR) system for your server. Once again we've chosen our Stealth AutoAttendant because it demonstrates the real power of the latest release of FreePBX.

Here's the way our Stealth Auto Attendant works. A call comes into your PBX, and we first decide whether it should be processed using business hour rules or nighttime settings. This works identically for home use except the times may be a little different. Once the call flow is chosen based upon the time of day, then we're going to play a generic greeting that goes something like this. For home use, it might say: "Hi. You've reached the Mundy's residence. Please hold a moment while we connect your call." For small office use, it might say: "Hi. You've reached Wonder Widgets International. Please hold a moment while we locate a sales agent to assist you." The point of these greetings is to welcome the caller without providing a clue that an IVR system is being used for the initial call processing, hence the name Stealth.

With the Stealth AutoAttendant, if the caller doesn't press any buttons on the phone, their call will be transferred to a default ring group after the greeting message completes. If the caller actually knows about the IVR, the caller can press a button while the greeting message is playing to transfer to a particular extension, listen to voicemail, get a weather or news update, check their email, or get dialtone to make a call to Europe using your company's favorite El Cheapo provider.

If no button is pressed during the greeting message, then the incoming call is passed to a ring group while music on hold plays to the caller. If no one is available to take the call, then the call is next routed to a second IVR that gives the caller the option of transferring to one or more cellphones or leaving a message on your voicemail system. Other hidden options can be embedded in this IVR as well.

In the old days, i.e. before last week, today's design was inhibited by the need to acquire customized voice messages for the various IVRs. For the design we've outlined above, you would actually have needed messages for three IVRs: the initial greeting for the Stealth AutoAttendant, the NoAnswer IVR, and the Applications IVR for access to weather, news, and email apps. If you sprung for the $24 Cepstral investment last week, then that's all a thing of the past. Now you can record your own messages and still use Allison as your voice talent. We would hasten to add that we sent Allison a note last week congratulating her on the new Cepstral voice. The note we got back went something like this: "I'm excited about the Cepstral technology. I just hope it doesn't run me out of business." Well, as fantastic as the Cepstral technology is, it's never going to quite measure up to using the real deal. But, as they say, it's close enough for government work and will certainly suffice for home or small office use, two markets that probably would not have hired professional voice talent to begin with. So let's get started.

Being Smart About Cepstral Utilization. There are a couple of things you need to know up front about using Cepstral. First, while the licenses are relatively inexpensive, they still are provided on a per connection basis. For example, if you're using Cepstral to read back a weather report, that ties up one license. If another caller is using Cepstral to play back email messages, that's another license. So, while $30 is cheap, on a 100-user PBX, the cost is a good bit more than $30. Unlike in the Flite days, where Egor could be handling multiple tasks at no cost, you need to be smarter about the way you deploy Cepstral on your server unless your PBX is basically a one-user system. For example, it doesn't make sense to use Cepstral interactively for playing back a 7-day weather forecast. That process would consume more than a full minute of a Cepstral license while Cepstral could just as easily have written the weather forecast out to a .wav file in less than one second. The same goes for IVR prompts. Don't even think about using Cepstral interactively for IVR applications. Instead, write out the IVR prompts to .wav files, and play those to callers which consumes no Cepstral licenses! Repeat after me: "Wave files free. Interactive Cepstral = $30 per simultaneous use." Design accordingly.

Building IVR Voice Prompts with Cepstral. Let's begin by building the voice prompts for our three IVRs. You obviously can customize these as we go along so that, when we're finished, you have a flawless system to deploy in your own home or office. If you didn't install Cepstral with the Allison voice last week, do that first. Here's the link. Our plan goes like this. We're going to record the voice prompts on your PBX in a Flash server, then copy them to your Windows or Mac desktop, and then we'll use FreePBX to assimilate them into your system for use with your IVRs. That's just the FreePBX way of doing things, but it's not really all that painful.

Before we begin, you need to figure out what you want your three prompts to say. For the Stealth AutoAttendant, we gave you some examples above, but you can tailor these to meet your own needs. Once you have the prompt the way you want it, step 1 is to test it. Log into your server as root, plug in some speakers, and issue the following Cepstral command:

swift "Hi. You've reached the Mundy's residence. Please hold a moment while I connect your call."

You may not be entirely happy with the way your prompt sounds. This is where your artistic creativity comes into play. First, you can adjust the spelling of certain words to try and smooth out the rough edges. You also can alter the playback using SSML commands to adjust pauses, playback speed, and many other settings. And finally you can phonetically spell problem-words to address specific issues. For example, to sound out Cepstral, here is the sample code:

Welcome to <phoneme ph="k eh1 p s t r ah0 l">Cepstral</phoneme>.

If this looks like Greek to you, not to worry. There is excellent documentation, but it still takes a bit of experimentation. Suffice it to say that every vowel has various sounds, and the 0 or 1 on the end of the vowel sound tell Cepstral whether to apply emhasis to the particular sound. Here's the list of sounds you have at your disposal. And here are the W3C SSML commands for Cepstral, all of which work under Linux.

Once you get your prompt the way you want it, our recommendation is to first save the text including the surrounding quotation marks to a text file. Then, if you want to change it later, you'll have your original text to work with. To save it to a text file, do this:

echo "Hi. You've reached the Mundy's residence. Please hold a moment while I connect your call." > welcome.txt

Then edit the file (nano -w welcome.txt) and put quotation marks at the beginning and end of the text. Also replace any embedded quotes and apostrophes with normal (i.e. not typographic) quotes and apostrophes.

To generate the .wav file from your .txt file using Cepstral, issue the following command:

swift -f welcome.txt -o welcome.wav

Now repeat the steps above to create the following prompts:

noanswer.txt: "I'm sorry. Noone is available to take your call at the moment. If you'd like to try their cellphones, press 1 for Joe or 2 for Betty. If you'd prefer to leave a message, press 3."

apps.txt: "For Mail Call, press 1. For News Clips, press 2. For weather forecasts by airport code, press 3. For weather forecasts by zip code, press 4. To schedule a telephone reminder, press 5."

FreePBX Preparations. Now that we have our voice prompts ready, copy them to your desktop. Then open FreePBX by pointing your web browser to the IP address of your PBX in a Flash system. We're going to be doing a good bit of editing even though it'll only take a few minutes. Firefox works much better with FreePBX than Internet Explorer so don't say we didn't warn you.

As with most applications, there's a certain order in doing things that makes life much simpler. So it is with FreePBX. First, be sure you have built all the pieces of the puzzle that you plan to use in your IVRs before you build your IVRs. This includes extensions, ring groups, system recordings aka voice prompts, DISA, miscellaneous destinations, etc. Second, we need to address a little Asterisk quirk. For whatever reason, Asterisk has a difficult time transferring calls to a cellphone when you get into nested IVRs. If you recall from our initial design, the plan is to provide a second IVR to catch unanswered calls after the first IVR transfers the inbound calls to a ring group. If you plan to have a cellphone transfer as one of the options in your second IVR, then here's a word to the wise. Don't use Misc Destinations to set up the numbers for your cellphones, or the calls will never be completed! What will work is to create additional extensions on your system specifically for your cellphones.

For today's exercise, we're going to assume that Joe and Betty's extensions are 201 and 202 on your PBX. So we'll also want to create extensions 301 and 302 for their cellphones. Just create SIP extensions in the usual way with no voicemail. If you want to force cellphone voicemail to kick in when a cellphone call goes unanswered, be sure to adjust the Ring Time for your cellphone extensions to 40-60 seconds when you set up these extensions. Now drop down to the Linux command prompt on your server and issue the following commands to set permanent forwarding of these extensions to Joe and Betty's cellphone numbers. Use the desired cellphone numbers in the appropriate format to match your dialplan. Be sure to test this by dialing each extension from a phone on your system to be sure the calls actually get transferred!

asterisk -rx "DATABASE PUT CF 301 6781234567"
asterisk -rx "DATABASE PUT CF 302 6787654321"

There's an alternate way to set the call forwarding which Philippe Lindheimer of FreePBX fame recommends... and he oughta know. When you create these "cellphone extensions," adjust the dial entry from SIP/301 and SIP/302 to look like the following example. Then you won't need the database manipulation step above.

dial... Local/6781234567@from-internal

Ring Groups. The other trick you need to appreciate is that FreePBX provides much enhanced call routing flexibility with ring groups. With an extension, your only option is to send unanswered calls to voicemail. With a ring group, calls can be routed to more than a dozen different destinations including IVRs, other ring groups, voicemail in 3 flavors, miscellaneous destinations, DISA, conferences, or even custom applications. So we typically recommend setting up ring groups for each individual extension on your system, e.g. 401 and 402 for Joe and Betty in our example. And, then set up an additional ring group (499) which includes every extension on your system. If you have work groups or departments, you can use the rest of the 490's for those ring group collections. For now, build these ring groups with a No Answer Destination of the VoiceMail extension matching each extension number. For home use, we recommend setting all of the extensions to the same voicemail box although this isn't required.

Importing Voice Prompts. Once you have all of your extensions, cellphone extensions, and ring groups set up, let's spend a minute importing your three new voice prompts that will be used in the IVRs: welcome.wav, noanswer.wav, and apps.wav. Because of the FreePBX design, all three of these .wav files need to be on the same desktop that you're using to access FreePBX. Then choose System Recordings from the FreePBX Setup tab. Click on the Browse button to select each .wav file. Then click the Upload button to import it into FreePBX. Name each recording and click the Save button. Let's use welcome, noanswer, and apps for the names. Reload FreePBX once you have imported all three .wav files.

Adding DISA. DISA is an extremely powerful function in Asterisk and even more so in FreePBX. Create a DISA option using the link on the Setup tab. Let's name it Standard, enter a PIN of sufficient length that you don't have to worry about compromising your PBX, set response timeout to 7 and digit timeout to 5, and leave Require Confirmation unchecked. If you're going to be placing calls from your cellphone to your PBX in order to take advantage of better outbound call rates using DISA, then you may also want to enter your cellphone number in the CallerID field. This will assure that calls placed through your PBX still have your cellphone's CallerID when they arrive at their destination.

Creating Misc Destinations. If you haven't already installed the Nerd Vittles goodies, now's the time to do it. We recommend you install at least two of the weather applications, the NewsClips application, the MailCall application, and the Telephone Reminders app. You can find all of the installation scripts here. Each install takes less than 15 seconds.

Once you've installed the five applications, create a Misc Destination with the Phone Number of each application plus a Misc Destination to retrieve your voicemail. We recommend:

MailCall... 555
Weather-Airport... 611
Weather-ZipCode...947
NewsClips... 511
Reminders... 123
VoiceMail... *98

Building the Apps IVR. We need to build the IVRs in reverse order so that the Apps IVR will be available for use in the NoAnswer and Welcome IVRs, and the NoAnswer IVR will be available for use in the Welcome IVR. So let's build the Apps IVR first. Click on the IVR link in FreePBX and then click Add IVR. Make the following entries on the form. When you run out of IVR options, click the Increase Options button to add another one. Click the Save button when you're finished and then reload FreePBX.

Name... AppsIVR
Timeout...10
Enable Directory...unchecked
Enable DirectDial...unchecked
Announcement...apps
1...Misc Destination: MailCall
2...Misc Destination: NewsClips
3...Misc Destination: Weather-Airport
4...Misc Destination: Weather-ZipCode
5...Misc Destination: Reminders

Building the NoAnswer IVR. Next we build the NoAnswer IVR. It will not only be used during the day when noone can answer a call, but it will also function as your night service. Design accordingly! Click on the IVR link in FreePBX and then click Add IVR. Make the following entries on the form. When you run out of IVR options, click the Increase Options button to add another one. Click the Save button when you're finished and then reload FreePBX. NOTE: We don't like people waking us up in the middle of the night, but if you do, you can add the 0 option shown in the Welcome IVR below.

Name... NoAnswerIVR
Timeout...10
Enable Directory...unchecked
Enable DirectDial...unchecked
Announcement...noanswer
1...Extensions: Joe Cell <301>
2...Extensions: Betty Cell <302>
3...Voicemail: <201> Joe (no message)
4...Voicemail: <202> Betty (no message)
5...Extensions: Joe <201>
6...Extensions: Betty <202>
7...Misc Destination: Voicemail
8...DISA: Standard
9...IVR: AppsIVR

Building the Stealth AutoAttendant. Finally we build the Welcome IVR. Click on the IVR link in FreePBX and then click Add IVR. Make the following entries on the form. When you run out of IVR options, click the Increase Options button to add another one. Click the Save button when you're finished and then reload FreePBX.

Name... WelcomeIVR
Timeout...10
Enable Directory...unchecked
Enable DirectDial...unchecked
Announcement...welcome
1...Extensions: Joe Cell <301>
2...Extensions: Betty Cell <302>
3...Voicemail: <201> Joe (no message)
4...Voicemail: <202> Betty (no message)
5...Extensions: Joe <201>
6...Extensions: Betty <202>
7...Misc Destination: Voicemail
8...DISA: Standard
9...IVR: AppsIVR
0...Ring Group: 499
t...Ring Group: 499
i...Ring Group: 499

Passing Through CallerID on Cellphone Transfers. If you really want to get fancy and your trunk provider supports adjusting of CallerID on outbound calls (normally accomplished by setting sendrpid=yes in your outbound trunk setup), here's an easy way to customize FreePBX to assure that calls delivered to your cellphone from your Asterisk system still retain the original caller's number rather than the CallerID number of your Asterisk system. Keep in mind that virtually no cellphone provider will let you forward the CallerID name of the original caller, but you can send their number. Log into your Asterisk server as root and edit extensions_custom.conf: nano -w /etc/asterisk/extensions_custom.conf. Then insert code at the bottom of the file that looks something like the following. Note that vitel-outbound is the name of the outbound trunk you wish to use to place the call from your Asterisk system to your cellphone. It is followed by the actual number of your cellphone in a format that matches what your carrier expects to receive. Save your changes: Ctrl-X, Y, then Enter. Now edit your IVR setup and, instead of using 301 as the Option 1 destination for Joe's cellphone, choose Custom App: custom-cellphone,301,1. Then do the same thing for Option 2, extension 302: Custom App: custom-cellphone,302,1. Then save your changes and reload the Asterisk dialplan when prompted.

[custom-cellphone]
exten => 301,1,Background(pls-hold-while-try)
exten => 301,2,Set(CALLERID(num)=${CALLERIDNUM})
exten => 301,3,Dial(SIP/vitel-outbound/6781234567,60,m)
exten => 301,4,VoiceMail(204@default)
exten => 301,5,Hangup
exten => 302,1,Background(pls-hold-while-try)
exten => 302,2,Set(CALLERID(num)=${CALLERIDNUM})
exten => 302,3,Dial(SIP/vitel-outbound/6787654321,60,m)
exten => 302,4,VoiceMail(204@default)
exten => 302,5,Hangup

Revising the IVRs to Cross-Link Back To Welcome IVR. Finally, edit the NoAnswer and Apps IVRs and add a zero option that links back to the Welcome IVR:

0...IVR: WelcomeIVR

Revising the Ring Groups to Support the IVR. Now edit the 499 Ring Group (at least) and modify the Destination on No Answer to point to the NoAnswerIVR. Save your changes and reload FreePBX. The reason we couldn't do this previously should be obvious. But, in case your head is spinning, the reason is because the IVRs didn't yet exist when we initially created the Ring Groups so we couldn't select an IVR as a destination.

Setting Up Time Conditions. While this is the entry point for incoming calls, it's also the last piece that you configure when setting up an AutoAttendant because we want to route calls to different IVRs depending upon the time of day. As with all things FreePBX, you need to have the IVRs built before you can use them to route calls with Time Conditions. Basically, what we want to do is route incoming calls to the Welcome IVR during the day and to the NoAnswer IVR at night. Click on the Time Conditions link and choose Add New Time Condition. Fill in the form as suggested below:

Time Condition Name...Daily
Time to Start...07:00
Time to Finish...21:00
Weekday Start...Monday
Weekday Finish...Sunday
Month Day Start...1
Month Day Finish...31
Destination Match...IVR: WelcomeIVR
Destination Not Match...IVR: NoAnswerIVR

Routing Incoming Calls to Time Conditions. The final step is to route your incoming calls. Simply adjust your Inbound Routes to point to Time Condition: Daily. Save your changes and reload FreePBX.

For an exhaustive look at Building IVRs with Asterisk and FreePBX, read our more recent article here.


FreePBX Training - Only 2 Seats Left! We're excited about the upcoming FreePBX Training Seminar, and today we want to remind the foot-draggers that you've almost missed the boat. This Friday is the registration deadline, and there are only two remaining seats available. And, yes, in addition to some fantastic training and the fine cuisine of Charleston, you're going to be treated to some once-in-a-lifetime hardware deals on the very finest Asterisk compatible hardware cards and servers for your business. So sign up today and join the fun. This will be the hands-down very best Asterisk and FreePBX training course that money can buy.

This is a DON'T MISS opportunity to learn everything you ever wanted to know about FreePBX, Asterisk, and Linux. The course will cover IVRs, ACDs, IRQs, E911, and the rest of the alphabet as well as routing, trunking, dialplan integration, remote office configuration, echo cancellation, TDM hardware, gateways, IP phones. It's a very full, three-day course with a half day devoted to branding and selling Asterisk systems. The seminar is being held at one of Charleston's premier hotels, the Embassy Suites Historic Charleston, with gorgeous suites, swimming pool and exercise room, free WiFi, free breakfasts, and free cocktails every evening. There also will be evening sessions to sit down one-on-one with the FreePBX and PBX in a Flash developers. So come join us while space is still available!


Some Recent Nerd Vittles Articles of Interest...

Be Sociable, Share!

6 Responses to “Introducing the Stealth AutoAttendant for Asterisk 1.4 and FreePBX”

  1. Troy Carpenter says:

    There’s a few things I don’t understand. First, when creating the cellphone extensions, shouldn’t you use the “Other(Custom)device”, which will not set up a sip extension for a device that will never register. Instead, it presents the “Dial” field where the cell phone number goes there like this “Local/xxxxxxxxxx@outbound-allroutes”

    Secondly, I use cell phone numbers in my ring groups all the time. I use the cell number directly in the extension list, putting a # sign after the number. My cell phones always show the original caller’s number without any extension context modifications. This has been the case back when I first installed Trixbox and is still the case on my newly installed PiaF system.

    Finally, have the weather/new/email etc apps been ported to use the swift tts engine yet?

    Thanks for all you do!

    [WM: Troy, as you’ve discovered, there are literally dozens of ways to do the same thing in FreePBX. If your way works, great! If not, try our way. This was actually Philippe’s suggestion. Your way instead of SIP device makes more sense, but it may not matter. As for forwarding calls to cellphone numbers, it only became problematic (at least for us) when you were using nested IVRs as was the case with the hypothetical situation in this article. As for porting our apps to Cepstral, you’ll have to wait ’til Valentine’s Day which also happens to be the 3d (month) anniversary for PBX in a Flash.]

  2. Ed Lally says:

    Hey Ward,

    I don’t know if others have run into this problem, but after installing the other Nerd Vittles goodies (Mail Call, Weather by ZIP, etc.) with this article, my PBX In A Flash wouldn’t restart correctly. I tracked the problem down to the /tmp directory not having correct permissions. Running the command chmod 1777 /tmp at the Linux command line fixed it. For those unfamiliar with Linux, the command grants all users permission to write temp files and sets the “sticky bit” to prevent users from deleting each others’ files.

    Thanks again for all your telephony work — I love my FreePBX!

    [WM: Thanks, Ed. That’s how mine was actually set. Not sure what happened, but we’ll add it to the patch list.]

  3. Shane says:

    Does anyone else have a problem when dialing out and trying to press numbers, extensions, commands, etc… using PBX in Flash? I am using vitelity & polycom ip430s, do I need to enable a setting in PBX in a Flash in order for the other phone systems to recognize the numbers that I have pressed?

    [It’s the DTMFmode setting. Post the issue on the forums if you can’t figure it out.]

  4. mahya says:

    Hi,
    When I use Voicemail function, there is a default system greeting
    before voicemail recording. Is it possible to change that greeting?
    How? Actually I want to change the sequence of sound file that played for greeting.Please send the solution to my E-mail.
    Thanks

  5. Giorgio says:

    just one thing: THANKS ! i’m new to asterisk&freepbx, but i’m really enjoing the setting-up of my new phone system ! thanks, this tutorial helped me a lot in the discovering of new asterisk features.

  6. Charles says:

    It does take a bit of set-up to get it running just right. But, once you’re done, it is really a time saver. Anything that keeps me focused on whatever I happen to be doing at any given moment is a good thing. And most phone calls can wait… or be ignored. Thanks for this detailed setup guide. It helped a lot.

Ringbinder theme by Themocracy