Asterisk Call Queues: The Smarter Way to Manage Incoming Calls

Ever wished you could screen incoming calls and route them to another person, or to an autoattendant, or to voicemail without the caller knowing what you're up to? Need a free Automatic Call Distribution (ACD) System for your business (with Elevator Music no less) that will balance incoming call workload among your employees? Ever wanted to prioritize incoming calls from different groups of callers? How about a simple way to access hidden features on your Asterisk® system when you're away from your home or office? Well, the latest Asterisk (1.2.4) now can do all of this without breaking a sweat... with Call Queues. And, with Asterisk@Home 2.5 and its included Asterisk Management Portal, you can build a complete Call Queue System in about half an hour.

Prerequisites: For today's project, you'll need at least Asterisk@Home 2.5. It can even be installed on your Windows desktop if you just want to experiment. We haven't yet tested this with Asterisk@Home 2.6, but we can always use a good guinea pig to report back. Just about any kind of incoming trunk should work: SIP, IAX2, or ZAP/PSTN. Then you'll need at least one Asterisk extension and a few external phone numbers we can play with to demonstrate how everything works. Depending upon what features you decide to use in your own system, you may also need a few customized voice prompts from Allison Smith although we'll provide some samples to get you started. The main voice prompt to explain to callees how to manage incoming calls from the call queue was funded previously by readers just like you. For the freeloaders, that's what the donate button is for ... to keep the goodies coming. To order your own voice prompts, you first sign up for an account at thevoice.digium. com. Then you go to digium.com and order 1 voice prompt (20 words) for $12 or 5 voice prompts with up to 20 words each ($50). When you sign up for your Digium account to actually pay for the prompts, make sure you use the same email address that was used when you signed up for your account on thevoice.digium.com (where you'll request creation of the prompts from Allison). After your check clears, Digium will deposit voice prompt credits in your thevoice.digium.com account. You then can log in there, type out what you want your prompts to say, and a few days later the prompts will be sitting there for you to review and download. It doesn't get much easier than that.

Overview. We're going to build a new flavor of our original Stealth AutoAttendant except today we're going to take advantage of a Call Queue to enhance the functionality of the original system. Along the way, we'll also show you how to expand this into a full-blown Automatic Call Distribution System for your business, large or small. The way today's system will work goes something like this. A caller calls your home. Asterisk answers the call and plays a message that says something like the following: "Hi. You've reached the Rockefeller's residence. Someone will be with you in a moment." Asterisk will then crank up Music on Hold and will direct the call to your Home Call Queue. This call queue will simultaneously ring all of your house phones and, if desired, your cell phone, Aunt Betty's phone at the nursing home, and your office extension. The CallerID displayed on all the ringing phones will be that of the incoming call. As with all Asterisk calls, whoever answers the call first gets the call. And there's no limit to the number of call queues on your system. It's just another "extension" to Asterisk. So it's easy to set up individual call queues for you and your spouse as well as each of the kids. Each can have its own incoming DID and a separate list of numbers to call when incoming calls arrive. Same goes for business use except you can add the ACD functionality of spreading out the incoming call workload to various employees.

When an incoming call arrives, if you don't answer the call, Asterisk optionally can play an AutoAttendant menu after a time limit that you specify giving the user choices of calling you or your spouse on your cellphone, calling your vacation home, or simply leaving a message on your voicemail system. Whatever you want it to say and do is pretty much up to you. If the incoming caller doesn't take tha bait and press a button, the phone extensions and outside numbers you've designated will all start ringing again. If the second attempt fails, the caller will get the IVR menu again after which the caller will be dumped into voicemail if the caller fails to choose an option. Again, you can set this scenario up in any way you like. That's just the way we've set it up for the example.

If the caller chooses an option, the call will be transferred to the appropriate number inside or outside your Asterisk PBX system. If you happen to be calling in to your own system, you can press single-digit numbers for other options that weren't identified in the IVR voice prompt to activate other Asterisk features such as DISA or reading your voicemail. If you'd prefer to dump calls you don't answer directly into your voicemail system, that can be done as well although you would lose the IVR features including the hidden functionality we've outlined. There are lots of options. Experiment!

If someone does answer the incoming call from the Call Queue, Asterisk will play instructions about available choices. We've sprung for that voice prompt, and the choices go something like this:

  • Press the star key (*) to immediately answer the incoming call.
  • Press the pound or hash key (#) and enter a phone number to transfer the incoming call elsewhere. The caller won't have a clue!
  • Press the pound or hash key (#) followed by 86 (that's VM for Voice Mail in case you're wondering) to transfer the incoming call to your voicemail.
  • Continue to wait for the tone and the call will automatically be connected.
  • You can add other obnoxious options here if you'd like. Basically, you can transfer any incoming call to any extension number for which you've created a custom context. These give you the full flexibility of the Asterisk programming language. For our purposes today, they can be used to irritate or annoy people who are irritating or annoying. Here's an example. Adding the following code to the [from-internal-custom] context of extensions_custom.conf and then transferring a call by pressing #-3-8-3 (D-U-D) will play a message that everyone in your household is busy taking other calls from telemarketers and to please try the call again later. Works great for calls with no CallerID if you want to personally review these. Click!

    exten=>383,1,Answer
    exten=>383,2,Wait(1)
    exten=>383,3,Background(tt-allbusy)
    exten=>383,4,SetMusicOnHold,default
    exten=>383,5,WaitMusicOnHold,30
    exten=>383,6,Background(thank-you-for-calling)
    exten=>383,7,Background(goodbye)
    exten=>383,8,Congestion
    exten=>383,9,Hangup

    Gotcha Alerts. We discovered one anomaly in building this on our Asterisk system. By the way, we've loved that word "anomaly" ever since it was first used by Ashton-Tate, the folks that marketed dBASE. They just never could bring themselves around to calling anything a bug. Anyway, here's the Call Queue problem which didn't appear for us until about the third day of testing.

    Sometimes, when transferring a call either to another number or to voicemail, the transfer occurs on your end before the transfer is executed on the caller's line. This means the person receiving the transfer from you (or your voicemail system) may actually answer the call and start yacking well before the transfer kicks in on the caller's end so that they can hear what's being said. The delay on our system was about 10 seconds so it shouldn't pose a problem for calls transferred to another person. It'll usually take them that long to get to a phone anyway. For voicemail transfers, our solution was to add an 11 second delay in the script which connects the queued call to voicemail. We'll show you in the code below how to adjust that should you need to.

    Keep in mind that Asterisk is managing two separate voice channels: the caller's incoming call and your outbound call either to voicemail or another number. There doesn't appear to be a good synchronization mechanism to assure that both transfers happen at or near the same time. We used a clunker PC for testing so this may just be a result of our system's slow processor and 128MB of available memory. Or it may be a bug in the code that will get improved down the road. We'd be interested in hearing from others so that we can report it as a bug if, in fact, it is.

    Call Queues also work in Asterisk@Home 1.5 ... sort of. What doesn't work is breaking out of the connection by pressing * or #. In short, a message will play to the callee announcing the call, and then the caller is connected. You'll need a different Allison recording than what we're providing today to do this, since the standard options don't function. But it will work with this one limitation. And you can accomplish almost the same thing by hitting the # key immediately after the announcement prompt completes and the calling party is connected to you.

    Today's Game Plan. We're going to begin by downloading some sample voice prompts, then create some Ring Groups to handle cellphones or external phone numbers (we covered Ring Groups last week if you need a refresher course), then build an IVR menu, then create a sample Call Queue, and finally take it for a spin. Once it's working, we'll show you how to further customize it for business use or to meet your own special requirements. Some of the voice prompts are ones we use on our home system so they're not going to be much help except to give you an idea what's possible. Just follow along and, once you've built the sample system, it's easy to order your own voice prompts and swap them with our samples. We'll also point you to some generic prompts that come with Asterisk. These may suffice especially for home use without spending a dime.

    Call Queue Voice Prompts. Every Call Queue has at least two voice prompts: one that answers the incoming call to your Asterisk system and a second one that announces the call to you or whoever the recipient of the call happens to be. A third voice prompt is required if you want to provide the caller with an IVR menu of choices if or when no one answers the incoming call.

    The first two voice prompts are in .gsm format and need to be copied to the /var/lib/asterisk/sounds/custom directory on your Asterisk system. To create an IVR menu using the Asterisk Management Portal, you'll need a third voice prompt in .wav format which can be stored anywhere on your Asterisk server. We've provided ours just so you can see how it works in the example, and we'll save it to the custom directory also just to keep things simple. There's another advantage to storing stuff in this custom directory. They get backed up as part of the AMP backup system script. To download the prompts, log in to your Asterisk server as root and then switch to user asterisk: su asterisk. Now issue the following commands:

    cd /var/lib/asterisk/sounds/custom
    wget http://nerdvittles.com/aah2/callqueue.zip
    unzip callqueue.zip
    rm -f callqueue.zip
    ls -all

    Now look in the list of files displayed and check to see if you have any existing files that begin with aa_. These are existing sound files for autoattendants you've already created. If there aren't any, then do the following:

    mv nothome.wav aa_1.wav
    exit

    If you have existing autoattendant sound files in the directory, just add one to the number of the highest one shown and then issue the move and exit commands above. For example, if you have an aa_1.wav and aa_2.wav files already, then mv nothome.wav aa_3.wav. We'll need this in a bit.

    VoiceMail Redirector. For today's project, we've built a generic voicemail redirector. When you transfer a call to extension 86 (that's VM for VoiceMail), it will send the caller to the voicemail account matching the extension number of the phone on which you picked up the call. The code below assumes all of your extensions are 3 digits. If not, change the number 3 in lines 20, 30, and 40 to the actual number of digits in your extensions. If the number of digits varies, you'll need to seek "professional help" at Voxilla or SourceForge. If you need something different or if you want to reroute all incoming calls to one particular voicemail box, you can adjust the code accordingly. Using a web browser, go to the IP address of your Asterisk system and log in to the Asterisk Management Portal (AMP) as maint using your password. Then go to Maintenance->Config Edit->extensions_custom.conf. In the [from-internal-custom] context, add the following code:

    exten => 86,1,Answer ; V-M
    exten => 86,2,Wait(1)
    exten => 86,3,GotoIf($["${CHANNEL:0:3}" = "SIP"]?20)
    exten => 86,4,GotoIf($["${CHANNEL:0:3}" = "ZAP"]?20)
    exten => 86,5,GotoIf($["${CHANNEL:0:4}" = "IAX2"]?30)
    exten => 86,6,GotoIf($["${CHANNEL:0:5}" = "Local"]?40)
    exten => 86,7,Playback(hangup-try-again)
    exten => 86,8,Playback(goodbye)
    exten => 86,9,Wait(1)
    exten => 86,10,Hangup
    exten => 86,20,VoiceMail(${CHANNEL:4:3}@default)
    exten => 86,21,Goto(99)
    exten => 86,30,VoiceMail(${CHANNEL:5:3}@default)
    exten => 86,31,Goto(99)
    exten => 86,40,VoiceMail(${CHANNEL:6:3}@default)
    exten => 86,41,Goto(99)
    exten => 86,99,Hangup

    If you want to force a specific extension to a different voicemailbox, add two lines to the top of this code that look like this using your extension instead of 400 (in both lines) and the voicemail box number instead of 444 before @default in the first line:

    exten => 86/400,1,VoiceMail(444@default)
    exten => 86/400,2,Hangup

    And finally, as noted above, if you find that calls are not immediately transferring the caller to VoiceMail when you transfer the calls with #86, adjust exten=>86,2, Wait(1) to a longer delay. exten=>86,2, Wait(11) does the trick on our old clunker PC. Hopefully, someone with a better performing PC and more RAM will report back in a Comment indicating whether such a fix is necessary on more robust systems.

    Once you add the above code to your extensions_custom.conf file, save your changes and then reload Asterisk by clicking: AMP->Setup->Incoming Calls->Submit Changes->Red Bar.

    Creating Ring Groups for External Phone Numbers. AMP isn't the sharpest tool in the shed and only knows about local extensions. So, if you want to use external phone numbers (such as cellphones) in your Dialplan, then you need to set them up as Ring Groups so AMP can handle them just like a local extension. Let's create three just so we'll have some to use in our example. You can go back and change these later to meet your own needs. Using a web browser, go to the IP address of your Asterisk system and log in to the Asterisk Management Portal (AMP) as maint using your password. Then go to Setup->Ring Groups->Add Ring Group. Add a Ring Group for each cellphone or external phone number you want to integrate into your Dialplan. Use extension numbers (for the Group Numbers) that aren't already in use on your system. Each entry should look something like this (be sure to use a dial string that matches your outbound trunk):

  • Group Number: 411
  • Ring Strategy: ringall
  • Extension List: 16781234567#
  • Ring Time: 40
  • Destination if No Answer: some voicemail account on your system
  • Click the Submit Changes button after you complete each Ring Group and then click the Red Bar to reload the new Ring Group into Asterisk. Repeat for at least 3 external numbers.

    Creating an IVR Menu with AMP. To keep things simple today, we're going to build a quick Interactive Voice Response (IVR) menu using AMP. Using a web browser, go to the IP address of your Asterisk system and log in to the Asterisk Management Portal (AMP) as maint using your password. Then go to Setup->Digital Receptionist->Create New Voice Menu. Enter an extension number that can be used for you to interact with AMP while you're building this. On the Record Menu page, you can record your own voice prompt. For the example, let's use the one we've provided from Allison Smith. Just pick up the extension you chose to use in building this and dial *99. You should hear the Mundy's nothome IVR message. If not, go back to the Call Queue Voice Prompts section above and complete the steps. Otherwise, name the menu: Unavailable Menu and enter the following in the description: 1-MaryCell 2-WardCell 3-BeachHouse 4-Voicemail. Then click the Continue button.

    In the Options for Menu form, leave the Directory Context the way it is. For the number of menu options, enter 4 and click Continue. You can go back and increase this number later to support stealth options. The only trick to stealth options is adding the stealth contexts to the bottom of your extensions_custom.conf with context names beginning with custom. For example, to add a DISA option with a password, you could include something like the following and add a fifth option to your autoattendant:

    [custom-disa]
    exten => s,1,Wait(1)
    exten => s,2,Authenticate(1234)
    exten => s,3,DISA(no-password|from-internal)
    exten => s,4,Hangup()

    In the next screen, you actually associate tasks on your system with the choices given in your voice prompt. For options 1, 2, and 3, pick Ring Groups corresponding to the first three choices in your voice prompt. For option 4, choose a voicemail account for callers to leave voicemail messages. Click the Continue button and then the Red Bar to update your configuration.

    Creating a Call Queue. Now we're ready to actually create a call queue to process incoming calls. Using a web browser, go to the IP address of your Asterisk system and log in to the Asterisk Management Portal (AMP) as maint using your password. Then go to Setup->Queues->Add Queue. Fill out the form with the following entries substituting a Queue Number (extension number) which doesn't conflict with existing numbers on your system, a Static Agents entry which includes at least one local extension number on your system, and a Failover to Voicemail number which matches an existing voicemailbox on your system. Do NOT use external numbers in the Static Agents field although you can use Ring Group numbers which point to external numbers.

  • Queue Number: 299
  • Queue Name: queue1
  • Queue Password: leave blank
  • CID Name Prefix: q:
  • Static Agents: 201
  • Agent Announcement: callqueue
  • Hold Music Category: default
  • Maximum Wait Time: 1 minute
  • Maximum Callers: 2
  • Join Empty: yes
  • Leave When Empty: no
  • Ring Strategy: ringall
  • Agent Timeout: 30 seconds
  • Retry: 2 seconds
  • Wrapup Time: 0
  • Call Recording: no
  • Frequency: 30 seconds
  • Announce Position: no
  • Announce Hold Time: no
  • Voice Menu: Unavailable Menu
  • Join Announcement: welcome
  • Failover to Voicemail: 201
  • Click the Submit Changes button after you complete the entries and then click the Red Bar to reload the Queue into Asterisk.

    Once you finish creating the call queue, we need to set it to handle incoming calls. Click the Incoming Calls tab in AMP, and set the Regular Hours and/or After Hours destination to the Call Queue we just created above. Click the Submit Changes button once again and then click the Red Bar to reload your changes into Asterisk. Now place either an internal call to the extension number of your call queue or just dial the external number that connects to your Asterisk system to take your new Queue for a test run.

    Customizing Voice Prompts. To customize the system with a voice announcement for your home or office, simply order a voice prompt to replace our welcome voice prompt. The agent announcement voice prompt should be fine as delivered. Once you download your new voice prompt from Allison, log into your system as root and copy the file to the /root folder. Then convert the .wav file to a .gsm file with a command like this using the name of the .wav file provided to you by Allison Smith:

    sox r16212345-4105.wav -r 8000 -c 1 welcome.gsm

    Now copy the file to your /var/lib/asterisk/sounds/custom directory and change the ownership of the file from root:

    cp welcome.com /var/lib/asterisk/sounds/custom
    chown asterisk:asterisk /var/lib/asterisk/sounds/custom/welcome.gsm

    If you'd prefer something more generic until your customized sound file arrives, change the Join Announcement entry from welcome to pls-wait-connect-call or one of the other Asterisk sound files we've provided in the download. As another interim solution, you might want to try Loquendo synthesized voice files which can be created and then downloaded from here using the Firefox or Safari browsers. Once you play your creation, just choose File, Save As and give it a name to download the .wav file to your desktop. Then convert it to .gsm as shown above. We never could get a download to work with Internet Explorer, but maybe it was just late.

    Implementing an Automatic Call Distribution System. For those that use Asterisk@Home at work, it's a two-minute drill to convert what we've built today into a full-blown Automatic Call Distribution (ACD) System. For each department in your office, simply create a separate queue and route that department's DID trunks to the queue. Then add a list of the department extensions separated by carriage returns in the Static Agents field. Finally, adjust the Ring Strategy and Caller Announcement options to meet your business requirements. Hovering the cursor over the Queue and Caller Announcement Options will show what choices are available and what the various options do.


    Headline News for the Busy Executive and the Lazy Loafer. Get your Headline News the easy way: Planet Asterisk, Planet Gadget, Planet Mac, and Planet Daily. Quick read, no fluff.

    Got a PDA or Web-Enabled Smartphone? Check out our new PDAweather.org site and get the latest weather updates and forecasts from the National Weather Service perfectly formatted for quick download and display on your favorite web-enabled PDA, cellphone, or Internet Tablet. And, of course, it's FREE!


    Some Recent Nerd Vittles Articles of Interest...

    Be Sociable, Share!

    14 Responses to “Asterisk Call Queues: The Smarter Way to Manage Incoming Calls”

    1. Keen says:

      Well, interesting projects, and I would like to try if not for the fact I’m using an older version of Asterisk@Home. I’ll like to install a new version soon, however I foresee Asterisk@Home 2.6 is on the way given that Asterisk 1.2.5 is out now http://www.asterisk.org/asterisk-1.2.5 so I shall wait till *@Home 2.7 is out before I download the ISO and install :P

      I wish someday we can all just upgrade by typing yum update

      :P

    2. Christopher says:

      You know, I think this has been asked before, and I’m afraid I already know the answer, but just in case Uncle Ward has a magic bullet here goes: Is there any way for the call to be dropped, if you don’t press any keys? As in, it calls all your phones, ring groups etc… and so long as no one presses the * key, it won’t answer (e.g. cell phone voicemail picking up, or even more complex, enter a password to accept the call (for temp number roaming – like when at someone elses house). Just curious.

    3. Mike says:

      Ward,
      REAL interesting project…and timely too;-) I have been working on a project to simulated two-way radio traffic using A@H 2.5 … I have noticed that if I create a Queue with MaxWaitTime of 0 (should be unlimited) any call which is dropped in that Queue is dropped in about 30 sec… on my system. From what little I could find this seems to be a known bug and can work around it for now by sending the call to the Queue using parameters…
      (ie.exten => 411,7,Queue(${CALLQ}|t||custom/ivrpause|3600)) even
      If I change the time in the mysql DB for any Queue it is written back (extensions_additonal.conf) upon the next Queue creation … I could finish my work then mod the DB or just stick with calling the Queue defining the time myself – which is working OK… just wondering if you had experienced this bug or any thoughts on this 8-) THX!!

    4. Jeffery says:

      Thank you for this great tutorial. I tried this today and I had one problem: I can only get the callqueue played on the static agent. If the call transfer to 411 (ring group,-> my cellphone), I accept the call then there will no callqueue play, so I can not use #86 to transfer this call to VM. Please help. Thanks.

    5. Lenz says:

      The queue timings are not always as you setup in the queue definition – once you get a hold of how a queue works, it is a good idea to have a look at Understanding queue logic to avoid a lot of confusion and common mistakes. Excellent article, by the way!

    6. Tim says:

      Hi, this is great and thanks for all the help this site has given me in the past.

      One query on the queues – is it possible to get the queue processing to start whilst the welcome message is playing? Testing this on my setup the Queue command doesn’t start building the extension list until after the welcome message has finished playing thus increasing the amount of time the caller is waiting for an answer. I tried using the Background command in extensions_additional.conf (being careful to make sure it didn’t get overridden – I actually changed the PHP in functions.php to make it persistent) but this doesn’t actually return full control to the extensions dialplan until the sound file has finished playing (not what I expected). Any suggestions appreciated.

    7. Geoff says:

      I am trying to do this but on stock Asterisk 1.2.5 (not @Home). I can’t figure out how to allow the ‘agent’ to transfer a call. Any key pressed at all immediately bridges the incoming call from the queue to the agent. Could somebody please guide me?

      (Third times a charm, let’s see if this actually gets posted?!?)

    8. Matt says:

      Just wondering if Christopher had any luck – or anyone is able too offer a similar solution?

      Thanks

      Matt

    9. Justin says:

      The sprint deal is bust. I called and they require you have sprint service at home. it even says that on the page you linked to on sprints site ?Ǩ Unlimited Sprint PCS to Home minutes (Exclusive Home & On the GoSM offer) translated to you can’t get it unless you subscribe to the home and cell services they offer. Bummer man you got me all excited.

      [WM: You posted this comment under the wrong article. The Sprint deal is available, but there are lots of Sprint reps that don't know about it. Take a look at Comment 7 under the Sprint article for suggestions.]

    10. Rob says:

      Ward,

      I’ve been using AAH 2.7 and Queues for months, all perfectly. Last night, the incoming calls are suddenly ringing our extentions and asking us to accept an incoming call in the pressing the star key. What have I done wrong?

      Rob

      [WM: Try rebooting.]

    11. Rob says:

      I tracked down the issue, I don’t know the solution. AAH is “Playing ‘custom/callqueue’ (language ‘en’)” This si new. How do I get rid of it? It seems to be a feature of queues.

    12. LT says:

      Is there a way to route specific MoH to specific extensions (in bound routes)?

      thanks

    13. gianrico says:

      About: ” call which is dropped in that Queue is dropped in about 30 sec ”
      You should use the command Answer() before the Queue(…) command. If you don’t use “Answer()” you could have that kind of issue. I have tried that in Asterisk 1.4.4 too.

      regards
      gianrico fichera
      itesys srl

    14. Paul Diem says:

      I don’t see what drives the called extension menu choices. When an extension answer an incoming call, what is the queue configuration and/or dialplan processes the * and #? I don’t see anything in the queue.conf or Queue application documentation describing how to do this and I don’t see anything on this page showing how that’s set up.

    Ringbinder theme by Themocracy