• 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 the latest Stable release, or the CVS HEAD. 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 won't get you the latest version of asterisk, however, so you should then download and install from source - this should take care of any compilation issues.




Hint: If you see timing errors or warnings while compiling asterisk, you need to synchronize your clock. Debian users can do this easily with > apt-get install ntpdate




• Once you've got Asterisk, you'll need at least two phones connected to it in order to test your queue functionality. Instead of buying hardware phones, you can use software phones. We use SJPhone from SJLabs, and X-Lite from Xten. Installation instructions are (here) and (here).
  
  

  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.

  Hint: It's a good idea to give your SIP phones numeric names (like 12345).

  Note: DTMF (keypress) tones from X-Lite are not detected by older versions of Asterisk. This issue seems to have been fixed as of Asterisk version 1.0.9.

  
  
  
• Sox. 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 resample -ql
  
  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 resample -ql; 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. 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. By the end of this section, you should have installed the soft phones and called the Asterisk example extensions so that you know everything is working.

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':

Asterisk 1.0.10 and below: ; ; Music on hold class definitions ; [classes] default => quietMP3:/var/lib/asterisk/mohmp3

Asterisk 1.2.x, 1.4.x and above: ; ; Music on Hold -- Sample Configuration ; [default] mode=quietmp3 directory=/var/lib/asterisk/mohmp3

To begin with, all the other classes are commented out. Note that although the syntax for musiconhold.conf has changed between Asterisk 1.0.x and 1.2.x, Asterisk 1.2.x will work with the old syntax (but will print a warning).

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.

Change the Music Player

The next step is to replace the MP3 player (mpg123) used by Asterisk with a player that plays RAW streams (an uncompressed audio format). There are three reasons for doing this.

1. Mpg123 is not licensed for use in commercial environments (without the written permission of the author).



2. Playing RAW streams is much more efficient than playing MP3s, as your server doesn't have to keep decoding and redecoding the files.



3. There's a bug in some versions of Asterisk which means that quite often it won't loop playback with mpg123 (a request to schedule message in the past?!?! message appears, and the caller hears silence).

We can fix all of these by creating a new music player called rawplayer.

Note: As of Asterisk 1.2.0, Mpg123 is no longer used by Asterisk, which has its own MP3 player. However, it's still a good idea to play raw files for performance reasons, and so Asterisk 1.2.x and 1.4.x support a new files mode for playing raw files.

Asterisk 1.0.10 and below: > vi /usr/bin/rawplayer Type in (or copy-and-paste) the following file: #!/bin/sh for name in $@; do cat $name ; done Once you've saved your new rawplayer, you must make it executable: > chmod 755 /usr/bin/rawplayer

Asterisk 1.2.x, 1.4.x and above: These versions of Asterisk are able to play raw files unaided, so there's no need to create a separate rawplayer.

Now that you've created your player, you also need 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.

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 class definitions
;

[classes]
default => custom:/var/lib/asterisk/mohmp3,/usr/bin/rawplayer

;
; Music on Hold -- Sample Configuration
;

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

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 mohmp3, and put your additional raw files in there, and add lines to your musiconhold.conf like this:

;
; Music on hold class definitions
;
[classes]
default => custom:/var/lib/asterisk/mohmp3,/usr/bin/rawplayer

;my new music class
myclass => custom:/var/lib/asterisk/mohmp3/mydirectory,/usr/bin/rawplayer

;
; Music on Hold -- Sample Configuration
;

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

[myclass]
mode=files
directory=/var/lib/asterisk/mohmp3/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.

Now that you've got your Music On Hold set up how you like it, it's time to start creating your queue. Each queue feeds callers to a number of Agents. An Agent is a person who will answer the calls coming from the queue.

So, the first step in setting up a queue is to define the agents. This is done in /etc/asterisk/agents.conf.

You should read the file to familiarise yourself with the settings, but you probably will be OK with all the defaults except one. By default, Asterisk requires agents to press '#' after picking up the phone in order for the caller to be connected (and if you're finding there's no sound when your agents pick up the phone, this is probably why). To disable this feature, find the line that looks like this:

;ackcall=yes

and change it so it looks like this:

ackcall=no

Calls to your agents will now connect as soon as they pick up the phone. (Note: As of Asterisk 1.2.0, ackcall=no is the default setting.)

Now it's time to set up your agents. For each person who will be answering calls, add a line at the end of the agents.conf file, so it looks something like

agent => 1001,4321,Agent One
agent => 1002,5432,Agent Two
agent => 1003,6543,Agent Three

The first number is the Agent Code (username) used to identify individual agents, and the second is the agent's password.

Each agent will be using a phone to receive calls. Rather than force every agent to use the same phone all the time, Asterisk supports 'hot-desking', so agents can use any phone registered to the system.

In order to do this, each phone needs its own line in extensions.conf (in addition to any configuration in /etc/asterisk/sip.conf, or the other protocol-specific configuration files).

So, we'll add lines to /etc/asterisk/extensions.conf for each of the phones your agents will be using. Let's assume your agents will be using three SIP phones named 12345, 12346, and 12347. Then your extensions.conf should contain the following:

exten => 12345,1,Dial(SIP/12345)

exten => 12346,1,Dial(SIP/12346)

exten => 12347,1,Dial(SIP/12347)

This allows the system (and other phones) to dial your SIP phones by dialing a fixed extension.

Do an Asterisk reload in order to upload your changes, and try dialling one of your phones from another phone.

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's a simple example queue to get you started.

[MyQueue]
music=default
strategy=ringall
timeout=15
retry=5
wrapuptime=0
maxlen = 0
announce-frequency = 0
announce-holdtime = no
member => Agent/1001
member => Agent/1002
member => Agent/1003

This queue will ring all three 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.

Hint: We don't use the Group functionality to assign groups of agents to queues, as many of our users have had problems with this system. It's much better to add agents individually to each queue.

Hint: Although Asterisk supports it, we also don't recommend adding interfaces directly to queues, as they may not always be staffed. If this happens, your phones will ring even when there are no people to answer them. It's also impossible to track individual agent performance when interfaces are used.

Although you've defined your agents and the phones they will be using, you also need a way for your agents to log in and out of the system, so they can start and stop receiving calls.

To do this, you need to create special extensions for your agents to ring to tell the system when they are available.

Open up /etc/asterisk/extensions.conf and add the following lines (replacing mycontext with the name of your context):

;Agent Login
exten=> 2001,1,AgentCallbackLogin(|${CALLERIDNUM}@mycontext)

;Agent Logout 
exten=> 2002,1,AgentCallbackLogin(|l)

If you have Asterisk 1.2.x or above, then you need two of these |, like this:

;Agent Login
exten=> 2001,1,AgentCallbackLogin(||${CALLERIDNUM}@mycontext)

;Agent Logout
exten=> 2002,1,AgentCallbackLogin(||l)

When an agent dials 2001, the agent will be prompted to enter a username (e.g. 1001) and password (e.g. 4321). All queue calls will then be routed to the agent's phone (through the extension you created for the phone in Step 4).

When an agent dials 2002, the agent is again asked to enter the username and password, and also a new extension. The agent can enter a new extension to ring when calls come in (useful when switching desks), or press '#' to log out of the system so no more calls are routed to that agent.

Do an Asterisk reload, and try logging in and out as an Agent.

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

exten=> 2020,1,Answer
exten=> 2020,2,Ringing
exten=> 2020,3,Wait(2)
exten=> 2020,4,Queue(MyQueue)
exten=> 2020,5,Hangup

Next do an Asterisk reload.

To test your queue, you'll need at least two soft phones. Log in as an agent using SJPhone (by dialling 2001), and then call 2020 from XLite.

You should hear music on hold through XLite, and SJPhone will start ringing. Once you accept the call with SJPhone (press '#' if this doesn't happen when you pick up), the call will be connected.

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. Note: As of Asterisk 1.2.0, this is the default behaviour.

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.

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
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!