Asterisk Queues Tutorial

This tutorial covers the basics of setting up Asterisk (TM), the popular Open Source PBX system from Digium, to provide call center queue functionality. It's designed to be of wide appeal to all Asterisk users - so only the last section is specific to OrderlyQ.

Once you've set up your queues and started taking calls, you should also take a look at OrderlyQ, which is an add-on for standard Asterisk queues that allows your Callers to hang up and call back later without losing their place in the queue, resulting in substantial increases in Caller satisfaction and retention, and substantial savings for Call Center operators. There is a FREE TRIAL of OrderlyQ now available for Asterisk users - please contact us for further details, or Try It Now by calling +44 845 004 5412.

New: Try our new FREE statistics package for Asterisk, OrderlyStats.

The best place for further information about Asterisk and VoIP in general is voip-info.org.


First, you have a decision to make.

To route calls to your agents, you add the agents to a Queue, and then send your callers into the queue for distribution. Asterisk has three different methods for adding agents to your queue, and you need to choose which you are going to try first before proceeding. These are:

Phones
The simplest Asterisk queue set up is where you add your phones directly to the queue. This is ideal if each agent has his/her own desk, with their own dedicated phone that no-one else uses.
Extensions (Hot Desking)
Also known as Local Channels. In this model, Asterisk calls extensions in your dialplan, which are then routed to your agent's phones. This allows your agents to log in and out of different phones, so is ideal if two agents need to share the same phone, or if your agents move desks (hotdesking). This allows for the most versatile call center.
Agent Channels
Agent Channels provide the same hotdesking functionality as Extensions above. They are simpler to set up, but have been deprecated and are not supported in asterisk versions 1.6.2 and above.
 
 

We've produced three different versions of this tutorial, to cover the three different ways of setting up Asterisk queues. This version is the Phones version. You can switch to either of the others by clicking on the links above.

Not sure which method is right for you?
Though it's possible to use all three methods for different agents in the same queue, most call centers pick one method and stick with it.

Phones Tutorial Contents:
  1. Install Asterisk
  2. Install Phones
  3. Test Calls
  4. Configure Music On Hold
  5. Create Queues
  6. Queue Log In and Log Out
  7. Test Your Queue
  8. OrderlyQ Integration

If you're having any trouble setting up Asterisk queues, then please do ask us - even if you're not an OrderlyQ customer, we're always happy to help.

1. Install Asterisk & Other Dependencies
There are a number of things you'll need to get set up.

Asterisk

  • If you're starting from scratch, you might try an all-in-one distribution of Asterisk like Trixbox or AsteriskNOW. These include a precomplied Asterisk as well as an operating system for your hardware.


  • It's more likely that you are installing Asterisk on an existing system. Though there may be pre-compiled Asterisk packages available, we find it's best to compile Asterisk from source, as this tends to give the best performance in our experience. First of all, you'll need a computer running Linux. We run Debian, but any Linux will do.


  • Next you'll need to get Asterisk. We recommend you download the latest stable release. This tutorial is tested on 1.2.x, 1.4.x, 1.6.x and 1.8.x. You probably only need the basic Asterisk package, but the Addons and Sounds packages are also common choices.

    Asterisk has a few prerequisites of its own and is usually compiled from source (instructions), so if you don't have them, you might run into trouble during the compilation. If you're running Debian, you can get the prerequisites automatically by installing the Debian Asterisk package:

    > apt-get build-dep asterisk

    This will get you all the build dependencies and should prevent any compilation issues when you compile from source.


  • Hint: If you see timing errors or warnings while compiling or running Asterisk, you need to synchronize your clock. Debian users can do this easily with

    > apt-get install ntpdate


OrderlyStats

  • OrderlyStats will show you what's going on as you set up your queues and route the calls through to the Agents. You'll also need OrderlyStats to follow the screen shots in the tutorial, and perform one-click Agent log in and log out. You can either download and install it yourself, or sign up for the Managed Service.

    Note: You can complete this tutorial without using OrderlyStats - but the resulting system will not be as good.
    Once you've finished the installation/sign-up process and connected to your Asterisk, please log in and go to the Control Panel, which should look like this:

Note: If you already have queues and Agents set up on your Asterisk, these will be detected automatically when OrderlyStats connects to it for the first time.

Note: OrderlyStats will work with any Asterisk queue configuration, including AsteriskNOW, TrixBox and FreePBX - you don't have to follow the set-up described in this tutorial to use OrderlyStats.

Sox

This is optional - you will need it if you wish to use your own prompts to play to callers while they are in the queue. Asterisk does come with its own set of default prompts you can use for this purpse, so you can skip this section.
  • This is a utility for converting between different types of WAV files (a sound format). If you're using Debian, you can get it with

    > apt-get install sox

    If you're using other flavours of Linux, you may be able to find a pre-built package, otherwise you can download and compile the source code.

    Sox is very useful; for instance you can have Asterisk play your own messages and instructions to Callers by recording spoken messages in standard WAV file format, then converting them to GSM format with the following command:

    > sox inputfile.wav -r 8000 -c 1 outputfile.gsm

    or this to convert all the files in a directory:

    > for i in *.wav; do sox $i -r 8000 -c 1 $(basename $i .wav).gsm; done

    If you're interested in creating your own telephony applications then you might also take a look at OrderlyCalls. In this tutorial we'll be using Sox to help us with Music On Hold.

Lame

This is also optional - you will need it if you wish to play your own music on hold (that you have in MP3 format) that people will listen to while they are in your queue. Asterisk does come with its own set of music on hold you can use for this purpse, so you can skip this section.
  • Typically music on hold is provided through MP3 files, which is one of the few formats not supported by Sox. Lame is an MP3 encoder/decoder which we can use for conversion. There's no Debian package, so here are the instructions for compiling from source. First, download the source code bundle. Next extract it:

    > cd /usr/src
    > tar -xvzf /path/to/lame-3.96.1.tar.gz


    To compile and install from source:

    > cd /usr/src/lame-3.96.1
    > ./configure
    > make
    > make install


    If your installation is successful, then typing lame at the command line should print out usage information.


That's it for the prerequisites.



2. Install Phones
  • Once you've got Asterisk, you'll need at least two phones in order to test your phone system. In this tutorial we're going to use three - but don't worry - instead of buying hardware phones, we're going to use free SIP software phones instead, running on another computer on the local network.

    We use SJPhone from SJLabs (installation instructions), and X-Lite from CounterPath (installation instructions), and Express Talk from NCH (installation instructions), all running on the same Windows PC. You can use the FREE versions of all these phones to complete the tutorial.

    For this tutorial, name your ExpressTalk phone '1001', your X-Lite '1002', and your SJPhone '1003'. Edit your /etc/asterisk/sip.conf file and at the end add the following lines:
    [1001]
    ;ExpressTalk
    context=main
    type=friend
    Callerid="1001" <1001>
    username=1001
    secret=1001
    host=dynamic
    dtmfmode=RFC2833
    disallow=all
    allow=alaw
    
    [1002]
    ;XLite
    context=main
    type=friend
    username=1002
    Callerid="1002" <1002>
    secret=1002
    host=dynamic
    dtmfmode=RFC2833
    disallow=all
    allow=alaw
    
    [1003]
    ;SJPhone
    context=main
    type=friend
    Callerid="1003" <1003>
    username=1003
    secret=1003
    host=dynamic
    dtmfmode=RFC2833
    disallow=all
    allow=alaw
    

    If you are using your own sip.conf entries, you must make sure the Callerid and context are set as above to be able to follow the examples in this tutorial.
    Hint: If you want to hear Music On Hold with X-Lite, make sure Menu->Advanced System Settings->Audio Settings->Silence Settings->Transmit Silence is set to Yes.
    Note: We couldn't get DTMF (keypress) tones from the current version of SJPhone to work at all, so we'll use this as the Caller's phone for the rest of the tutorial. We'll use Express Talk (1001) as the first Agent phone, and X-Lite (1002) as the second.

Add Phones to OrderlyStats

In order for OrderlyStats to start tracking calls to and from your Phones, you need to add the Phones to OrderlyStats. To do this, go to the Agents page (in the menu on the left hand side of the Control Panel) and hit Add Interface at the bottom of the page, and enter in SIP/100X (where X is 1 and then 2 - don't add the third one as this is being used to represent the Callers) for each of the two agent Phones like this:

Adding the first Agent Phone...Adding the second Agent Phone...

Agent Details
You should also fill in the rest of the details for each Agent, and hit Save Changes at the bottom of the page to save before adding the next Agent:

The username and password fields are for the Agent Toolbar - more about this later.

Note: The LINE Agent is automatically created by the system, and is used to indicate that a call has been answered, but not by an Agent.

Create Phone Extensions

Next, we need to create extensions for your phones, so that Asterisk can dial them.

WARNING If you are running asterisk 1.6.x or 1.8.x, you should first bypass the default AEL dialplan, otherwise your extensions.conf file will be ignored. You can do this by running the following commands as root:
> mv /etc/asterisk/extensions.ael /etc/asterisk/extensions.ael.save
> asterisk -rx "core restart now"
Note: You must restart asterisk for this change to take effect.

Now add the following to the end of your /etc/asterisk/extensions.conf file:

    
    [main]
    ;Phone Extensions
    exten => _1XXX,1,NoOp(Dialling phone ${EXTEN})
    exten => _1XXX,n,Dial(SIP/${EXTEN},,rotwh)
    exten => _1XXX,n,Hangup
    
    

Next do an Asterisk reload by typing reload (or module reload for Asterisk 1.6 or 1.8) at the Asterisk command line (which you can reach by typing asterisk -vvvr).

Here we have created a new context for your phone calls, called main. Calls made from your phones will arrive in the context specified in each phone's sip.conf entry (which we have already set to main).

We've also defined a pattern-matching extension, which will match any four digit number 1000 to 1999. The extension dials the corresponding SIP phone.



3. Test Calls

Let's make some calls! To recap, we have set up agent John Doe using phone 1001 (ExpressTalk), and agent Jane Smith using phone 1002 (X-Lite). We're using SJ-Phone to represent your callers.

So, let's use SJPhone to call John Doe, by dialling 1001. You'll see the call come up as an INBOUND call to John Doe in the OrderlyStats Control Panel:
John's phone Ringing with the inbound call from SJPhone / 1003.

After answer, John is shown as Talking to Caller 1003.

Hint: If the time counters do not start at 0s, you need to make sure the clock on your OrderlyStats machine is correctly set, AND that the clock on your browser machine is correctly set.
On Linux you can do this automatically with the ntpdate package. On Windows you can set the System Clock to automatically get the correct time with the Internet Time dialog.

The system will now also log calls from 1001 (ExpressTalk) as belonging to John. To test, use John's phone (ExpressTalk) to dial SJPhone (1003), and you should see the call come up as an OUTBOUND call in the OrderlyStats Control Panel:
John makes an outbound call to 1003.

Now we're going to test the second Agent, Jane Smith (1002), using X-Lite.

To test Jane's phone, dial 1002 from John's phone (ExpressTalk). As this is an internal call, each leg of the call will be shown separately in the Control Panel, as an INBOUND call to Jane, and an OUTBOUND call from John:

John (1001) makes an internal call to Jane (1002).

The call is only shown once in the OrderlyStats reports (historical logs), as an INTERNAL call:

John misses an inbound call, makes an outbound call, calls Jane but she doesn't answer, and then calls Jane and she does answer. Calls are shown with the most recent at the top of the page (but you can change the sort order using the arrows at the top of each column).



4. Configure Music On Hold

Asterisk Music On Hold

When callers call Asterisk, you can play them music. Asterisk is designed to play MP3 files by default. You can play a single file or groups of files; in the latter case Asterisk will play each file in order, then repeat (assuming your caller is still on hold by that point).

  • To specify groups of files, you put them in the same directory.
  • To play a single file you create a directory and put the single file in it.

You can also specify multiple different groups of files to play under different circumstances.

The default group of music on hold files is in

/var/lib/asterisk/mohmp3

This directory contains three sound files in MP3 format.

To tell Asterisk about your groups of files, you list them as classes in /etc/asterisk/musiconhold.conf, which initially has just one class defined called 'default':

;
; Music on Hold -- Sample Configuration
;

[default]
mode=quietmp3
directory=/var/lib/asterisk/mohmp3

To begin with, all the other classes are commented out.

Test Default Configuration

We'll start by testing the default configuration. Add the following lines to /etc/asterisk/extensions.conf, inside a context you can reach with your phones.

exten => 2000,1,Answer
exten => 2000,2,SetMusicOnHold(default)
exten => 2000,3,WaitMusicOnHold(20)
exten => 2000,4,Hangup

Next do an Asterisk reload to tell Asterisk about the new extension.

> asterisk -r
CLI> reload

Now dial extension 2000 with your phone. You should hear the default music.

Note: If you hang up and call back, the music starts where it left off, not at the beginning. This is an efficiency measure in Asterisk, as it's much less computationally expensive to produce one music stream shared between all callers, rather than a separate stream for each new call.

Play Your Own Music

You'll probably want to change the music played to suit your own tastes, so find an MP3 of some music you'd like to play to your callers. A good source of free classical MP3s is classiccat.net.

Upload your chosen MP3(s) to your asterisk server, and put them in /var/lib/asterisk/mohmp3 and delete the other MP3s there.

Shutdown and restart asterisk - a reload won't do as the music streams do not reset themselves on reload. Then dial extension 2000 again with your phone. You should hear the music you've chosen.

Convert Music File Type

Using MP3s creates load on your system, as Asterisk has to use processor power to decode the files over and over again every time they are played. Playing RAW streams is very much more efficient.

Here's how to convert your MP3 files to RAW format.

> cd /var/lib/asterisk/mohmp3

Let's assume you have a single file in this directory called mymusic.mp3. The following will convert it into a 16-bit WAV file:

> lame --decode mymusic.mp3 mymusic.wav

Next you have to convert it from a WAV file to a RAW file. We'll use Sox for this:

> sox -V mymusic.wav -r 8000 -c 1 -w mymusic.raw

This converts the WAV file to RAW (binary) format at the appropriate sample rate (8kHz).

You should remove any leftover MP3 and WAV files from the directory, and move the RAW files to /var/lib/asterisk/moh

You also need to update /etc/asterisk/musiconhold.conf to play your new raw file. Change it so it looks like this:

;
; Music on Hold -- Sample Configuration
;

[default]
mode=files
directory=/var/lib/asterisk/moh

Remember to shutdown and restart Asterisk, as you've made changes to your Music On Hold configuration, and test again by calling extension 2000.

Create Additional Music Classes

You might want to play different music for different occasions. If you want to do this, then create a new directory inside moh, and put your additional raw files in there, and add lines to your musiconhold.conf like this:

;
; Music on Hold -- Sample Configuration
;

[default]
mode=files
directory=/var/lib/asterisk/moh

[myclass]
mode=files
directory=/var/lib/asterisk/moh/mydirectory

Once you've defined your classes, you can test them by changing the entry for extension 2000 in /etc/asterisk/extensions.conf:

exten => 2000,1,Answer
;Play my new music class, instead of the default.
exten => 2000,2,SetMusicOnHold(myclass)
exten => 2000,3,WaitMusicOnHold(20)
exten => 2000,4,Hangup

Note: Remember to restart Asterisk if you've made any changes to your music on hold system.



5. Create Queues

Now you've defined your Agents and their phones, you're ready to set up a queue.

Queue definitions are found in /etc/asterisk/queues.conf. As you'll see there are a lot of configuration options; here are two example queues to get you started.

[Sales]
music=default
strategy=ringall
eventwhencalled=yes
timeout=15
retry=1
wrapuptime=0
maxlen = 0
announce-frequency = 0
announce-holdtime = no

[CustServ]
music=default
eventwhencalled=yes
strategy=ringall
timeout=15
retry=1
wrapuptime=0
maxlen = 0
announce-frequency = 0
announce-holdtime = no

These queues will ring all assigned Agents when a new Caller arrives, and will not make any announcements regarding queue size, estimated wait etc.

If you've defined a custom music class, you can set your queue to use it with the music parameter.

Do an Asterisk reload, and the new queues will appear in the Control Panel within 10 seconds:

New queues appear automatically in OrderlyStats

It is possible to assign static Agents to your queues in queues.conf with a member line like this:

member => SIP/1001@main ;Adds John Smith to queue

However, this is not a good idea as static Agents cannot then be logged in and out of queues dynamically - they are permanently assigned instead. This means that static Agents have the following drawbacks:

  • Static Agents cannot log in and out when they arrive for work and leave for home,
  • Static Agents' session times cannot be tracked,
  • Callers cannot be automatically routed away from the queue if no-one's there to answer them,
  • Static Agents cannot be dynamically reassigned to different queues, and
  • Static Agents' phones are rung all the time, regardless of whether the Agent is present to answer, so you will have a room full of ringing phones all the time.

These drawbacks are removed by using dynamic Agents instead as described in the next section.

Hint: You can use Group functionality to assign groups of Agents to queues, but many of our users have had problems with this system, so we don't recommend it. It's much better to add Agents individually to each queue.
Hint: If you have already set up your Asterisk queues, you should remove any 'member =>' lines from your queues.conf, otherwise your agents won't be able to dynamically log in and out of your queues. You can manage agent assignment in the OrderlyStats Agents page.


6. Queue Log In and Log Out

To recap, so far we have defined our Agents and the phones they use.

We have also defined two queues, so the last thing we need to do is create the mechanism that allows Agents to log in and out of the queues, so they can start receiving queued calls.

The Hard Way

Skip to The Easy Way if you're using OrderlyStats.

If you're not using OrderlyStats, you can provide your Agents with numbers to dial to log in and out of individual queues, but you must then give your queues numeric names. Here is an example:

    
    [macro-queue-login]
    exten => s,1,Set(agent=${ARG1})
    exten => s,n,Set(queue=${ARG2})
    exten => s,n,NoOp(Queue login agent ${agent} to queue ${phone});
    exten => s,n,AddQueueMember(${queue},SIP/${agent});
    exten => s,n,Playback(agent-loginok)
    
    [macro-queue-logout]
    exten => s,1,Set(agent=${ARG1})
    exten => s,n,Set(queue=${ARG2})
    exten => s,n,NoOp(Queue logout agent ${agent} from queue ${phone});
    exten => s,n,RemoveQueueMember(${queue},SIP/${agent});
    exten => s,n,Playback(agent-loggedoff)
    
    
    [main]
    ;...
    
    exten => _3XXX1,1,Answer
    exten => _3XXX1,n,Read(Agent,Agent-user)
    exten => _3XXX1,n,Macro(queue-login,${Agent},${EXTEN:0:4})
    exten => _3XXX1,n,Hangup
    
    exten => _3XXX11,1,Answer
    exten => _3XXX11,n,Read(Agent,Agent-user)
    exten => _3XXX11,n,Macro(queue-logout,${Agent},${EXTEN:0:4})
    exten => _3XXX11,n,Hangup
    
    

This has the following limitations:

  • All your queue names must be four digits long and start with the number 3 (which is not user-friendly), and
  • The Call Center Manager cannot manage which Agent is assigned to each queue, and
  • Agents who are members of multiple queues will have to log in and log out of each one separately, and
  • Agents may not be able to perform login or logout if their phone is already ringing or in use, and
  • There is no support for Agent prioritisation (using the Penalty system), and
  • There is no support for wrap-up (using the Pause system).

The Easy Way

The easy way to do queue login and logout is with OrderlyStats. OrderlyStats comes with an Agent Toolbar that your Agents use to log in and out of their queues. The first step is to assign the Agents to the queues, using the Agents page - click on the 'None' link at the end of each Agent's row to open the assigner dialog, like this:

Assigning John to Sales and CustServ Assigning Jane to CustServ

Although the Agents are now assigned, they won't start taking calls until you log them in with the Login button (), which you can do from this page as Call Center Manager.

Agent Toolbar

For your Agents to log themselves in and out of your queues, they need the Agent Toolbar. You should have already set them up with a username and password for this in the 'Add Phones to OrderlyStats' section above. Once logged in, the toolbar looks like this:

Jane's Agent Toolbar showing an answered INBOUND call.

To Log Out of all her queues, Jane just needs to hit the Log Out button. She can log in to all her assigned queues with one touch by hitting the Log In button.

If your Agents need time to wrap up after each call before taking the next call, they can do this by hitting the Pause button during the call, or aftwerwards. This will prevent the queue(s) to which they are assigned from sending them more calls until they hit the Resume button.

The OrderlyStats Reports will show you Agent session times, and also time spent in wrap up after each call,

Note: The Toolbar Login/Logout function logs an Agent in or out of all the queues to which the Agent is assigned in the Agents page.

Agents do not have direct control over which queues they are assigned to with the Agent Toolbar. This is by design.

As Call Center Manager, you can do this yourself at any time using the Agents page to reassign Agents on the fly, or log them in and out yourself using the Log In/Log Out buttons next to each Agent in the Control Panel. You retain full control of which queue(s) each Agent is assigned to.


Hint: Some versions of Asterisk contain a bug that prevents agents from initialising correctly when Asterisk is restarted. You can check to see if your version of Asterisk is affected by restarting Asterisk, and then running queue show or show queues from the command line. If your agents are shown as Invalid, then you can easily fix this by adding the following lines to the preload section of your /etc/asterisk/modules.conf file:
 
preload => pbx_config.so
preload => chan_local.so
preload => chan_sip.so


7. Test Your Queue

The last step is to provide an extension for incoming Callers to ring into the queue. Add the following lines to /etc/asterisk/extensions.conf at the end of the [main] context.

exten => 3001,1,Answer
exten => 3001,n,Ringing
exten => 3001,n,Wait(2)
exten => 3001,n,Set(_doVoicemail=no)
exten => 3001,n,Queue(CustServ,twh)
exten => 3001,n,Hangup

exten => 3002,1,Answer
exten => 3002,n,Ringing
exten => 3002,n,Wait(2)
exten => 3002,n,Set(_doVoicemail=no)
exten => 3002,n,Queue(Sales,twh)
exten => 3002,n,Hangup


Next do an Asterisk reload.

To test your queue, use SJPhone (1003) to dial extension 3001 (CustServ).

You should hear music on hold through SJPhone, and the other phones will start ringing.

You will see something like this in the Control Panel:

A queued call in the CustServ queue. Jane's phone is ringing, but John is currently Paused, so no calls are placed to him.

Note that if there are no Agents available, the Caller will hear music on hold indefinitely.

Hint: If you want to change this behaviour, then add leavewhenempty=yes to the queue's entry in queues.conf, and replace the Hangup line in the above example with, for instance, a call to leave Voicemail instead. As of Asterisk 1.2.0, this is the default behaviour.

That's it for the tutorial. You should now have a fully functioning Call Center system with dynamic Agents. Realtime and historical reports and dynamic Agent assignment are provided through OrderlyStats.

The next section covers integration with our OrderlyQ add-on, which helps you

  • Answer more Callers without hiring additional staff,
  • Improve Caller satisfaction, and
  • Improve Agent morale.

OrderlyQ works with any Asterisk-based queue, so if you need help increasing your answer rate, make sure you ask us for a free trial.



8. OrderlyQ Integration

To get ORDERLYQ , please contact us so we can set up a queue for you.

OrderlyQ works with your existing Asterisk queues to distribute Callers to your Agents. Callers are given an estimated wait time, and invited to hang up and call back at any time without losing their place, so this is great if you don't have enough Agents to cope with demand, or if you're looking to reduce your staffing costs. Call Centers using OrderlyQ typically reduce their abandonment to less than 1/3 of its former value.

Once we've set up your account, we'll send you your Queue Code (see below), and also give you access to our configuration screens so you can configure OrderlyQ to suit your needs.

In order to work with your Asterisk queues, you'll need to make the following configuration changes on your Asterisk server. The whole process shouldn't take more than about five minutes.

Install OrderlyQ Sounds

OrderlyQ uses its own sounds to play to your Callers to tell them how long they will be waiting, and tell them that they have the option to hang up and call back without losing their place. Once you've signed up, we'll send you a link to an archive file that contains the necessary sounds. Run the following commands to install them on your Asterisk server:

> cd /var/lib/asterisk/sounds
> tar -xvzf /path/to/OrderlyQSounds.tar.gz

This will create a new subdirectory called OrderlyQ containing all the sounds used by the application.

Hint: You can provide your own sounds for your Callers to hear by overwriting the sounds in the OrderlyQ directory.

Set Up Manager Access

OrderlyQ listens for queue events through Asterisk's Manager protocol. In order to do this, OrderlyQ must be able to access your server, which means you need to edit /etc/asterisk/manager.conf.

First enable Manager by setting enabled = yes in the [general] section at the top of the file.

Next add the following lines:

[MyUsername]
secret=MyPassword
deny=0.0.0.0/0.0.0.0
permit=85.13.195.164/255.255.255.255
permit=87.117.198.14/255.255.255.255
read = system,call,log,verbose,command,agent,user,config,reporting,dialplan
write = call,log,verbose,command,Agent,user

You should change the username and password to something more secure. The deny and permit lines help ensure that only OrderlyQ can receive messages from your Asterisk server.

Note: For additional security, we can encrypt the Manager session if required. Please Contact us for further details.
Hint: If you're having trouble connecting to our servers, test with telnet to port 4573. If you can't get through, it probably means you need to open up your firewall on ports 4573 (FastAGI, Outgoing) and 5038 (Manager, Incoming).

Route calls through OrderlyQ

The last step is to send Callers through OrderlyQ on the way to your Agents. To do this you need to modify /etc/asterisk/extensions.conf. The following example assumes you have already set up a queue as outlined in this tutorial.

exten => 2020,1,Answer
exten => 2020,2,Ringing
exten => 2020,3,Wait(2)

;Set music for Callers in OrderlyQ
exten => 2020,4,SetMusicOnHold(default)  

;Send Callers to OrderlyQ.
exten => 2020,5,agi(agi://qqq.orderlyq.com/orderlyq?queueCode=QUEUE_CODE&username
=MyUsername&password=MyPassword&AsteriskQueueName=MyQueue)   ;All one line.

exten => 2020,6,Queue(MyQueue|r)

exten => 2020,7,Hangup

There are two new lines here, and a slight change to one of the pre-existing lines.

The first line sets the music on hold to play while Callers are in OrderlyQ.

The second line is the call to OrderlyQ, which will manage the call until it's time for it to be answered by one of your Agents.

The agi call contains variables that tell OrderlyQ how to access queue information on your server. There are four parameters (separated by the '&' character).

  • The first parameter, queueCode, should be the numerical Queue Code of the OrderlyQ queue you're using (which is shown in your member's control panel).
  • The second and third parameters are the username and password defined in your manager.conf file.
  • The last parameter is the name of the queue to protect (as defined in queues.conf, and as listed in the Queue call two lines below).

The call to Queue on the next line has also been modified to play the ringing tone, instead of music on hold.

The reason for this is that OrderlyQ ensures that Callers will only be on hold for a very short time once they leave the OrderlyQ system, so it's better to play them the ringing tone to indicate that their call is about to be answered, rather than more Music On Hold (as hearing more Music On Hold is likely to make them hang up).

Hint: If you're not in the US, you'll probably want to change the ring tone being played to suit the phones in your country. You can do this by editing the country=us line in the [general] section of /etc/asterisk/indications.conf.
Note: Don't worry if your queue system is different from the one described in this tutorial, or if you're not using Asterisk - you can still use OrderlyQ.
Note: Asterisk 1.0.x and 1.2.x users should also apply the FastAGI contingency patch, to prevent calls from being dropped should your servers become unable to reach ours for any reason. Contingency handling is built into Asterisk 1.4.x already, so there's no need to apply the patch if you have this version or above.

Finally do an Asterisk reload, and your Callers will never have to wait on hold again!