Asterisk queue configuration

Asterisk queue configuration

If you have Asterisk installed, it is probably worth running and configuring additional functionalities such as queue management. In systems such as FreePBX or Issabel, just use a ready-made button and the matter is done. It turns out that it’s not much more difficult if you wanted to do it yourself from scratch. This article will show you how to add queues and static and dynamic agents and will help you choose the most useful options.

Table of Contents

1) Basic queue configuration

In the queues.conf configuration file, create queues by specifying their numbers (names), strategy and list of agents that will handle them. It’s always worth having information about all available options at hand. Of course, we use our favorite website github where we have Asterisk configuration files (queues.conf.sample) . Let’s start editing the file and configure our first queue and global settings
					nano /etc/asterisk/queues.conf

1a) general section

Global settings can be found in the general section. An example general section of our queues.conf configuration file for Asterisk might look like this:
persistentmembers = yes
autofill = yes
monitor-type = MixMonitor


The persistentmembers setting has a default value of "no", but it is worth changing it to "yes". This will mean that information about queue members (i.e. agents or devices) is stored in the astdb database, so that it is retained even after the Asterisk system is restarted. Therefore, if an agent was in the queue before the system was restarted, after the system restart, this agent will be automatically added to the queue and its status will be preserved.

Astdb is a database built into the Asterisk telephone system. It is used to store various information related to the operation of the system, such as: - system configuration (e.g. SIP numbers, passwords, channel numbers) - application configuration (e.g. context names, sound file names) - call states (e.g. call ID, caller number, caller number, call start time, call duration) Astdb can be used by various modules and applications in Asterisk, for example: - app_queue module uses astdb to store queue status information - the CEL (Call Event Logging) module uses astdb to store information about call-related events

Setting autofill to "yes" means that waiting callers will connect to available queue members in parallel until there are no more members or waiting callers available. This is a more expected behavior of the queue than the default value "no", so it is necessary to change it. Otherwise, the queue will cause all waiting callers to wait in the queue, even if there is more than one available member ready to answer calls, until the primary caller is connected to the queue member he was trying to reach. The next waiting caller in the queue becomes the primary caller and is then connected to the next available member, and all available members and waiting callers wait for this to happen.

The shared_lastcall = yes option will ensure that information about the last received call will be transferred between the queues in which a given agent is currently logged in. This is a useful function if we want a given agent to have respected Wrap-up time in each queue, regardless of where he received the call. By default it is set to "no"

Wrap-up time is the time that a customer service center employee needs after a call with a customer to complete all necessary tasks related to that call, such as entering notes, updating systems, or preparing reports. This time is needed to allow the employee to move on to the next conversation and to ensure that all information related to the previous conversation has been recorded and processed correctly. The length of time needed for wrap-up time may vary depending on the job specifications, work quality standards and the industry in which the company operates.

The monitor-type = MixMonitor option is the only monitor-type variant currently supported. Since MixMonitor mixes audio by default, it is not necessary to use “joining/mixing” parameters for input/output files.

1b) queue section

Each subsequent section will be treated as a queue name. An example queue configuration for the Asterisk system may look like this:
					[queue_1] ; queue_1 - Kolejka testowa
timeout = 15
wrapuptime = 5
autopause = yes
autopausebusy = yes
announce-position-limit = 5

member => SIP/101,,,,no,20
member => SIP/102,,,,no
In square brackets we have the name of the section, which is also the unique name of the queue, in our example it is queue_1 The number of configuration options is very large. We will focus on some of the most important and most frequently used ones.
The strategy option determines how incoming calls are allocated to the queue among agents. The following strategies are possible
  • ringall – calls all available agents simultaneously until one of them answers (default option)
  • leastrecent – calls the agent who last ended the call
  • fewestcalls – calls the agent who has the fewest answered calls in this queue
  • random – assigns connections by selecting agents randomly
  • rrmemory – (Round-Robin Memory):  connections are distributed equally among agents in the queue, regardless of their load. Asterisk remembers which agent was last used and the next call is forwarded to the next agent. The order of queue members resulting from the configuration file
  • is maintained
  • rrordered – (Round-Robin Ordered) similarly to rrmemory, with the difference that calls are distributed evenly, but also taking into account the agent load. Asterisk tracks which agent was last used and redirects the next call to the least loaded agent in the queue. Thanks to this, the rrordered strategy allows for a more even distribution of the workload among agents.
  • linear – calls agents in the order specified in this configuration file. When using dynamic agents, they will be selected in the order in which they were added
  • wrandom – calls a randomly selected agent, but uses the penalty parameter assigned to the agent as a weight when calculating its position in the queue.
Most often, our clients use the ringall, leastrecent or fewestcalls strategies

The "penalty" parameter determines the priority (weight) of the agent in the queue. The lower the "penalty" value, the higher the priority a given agent has. This means that an agent with a lower penalty value will have a greater chance of receiving a call than an agent with a higher penalty value. By default, the "penalty" value for each agent in the queue is set to 0. However, you can manually change this value for specific agents to adjust the queue priorities to suit your individual needs. For example, when one agent in the queue is more trained in a particular product or service than others, he or she can be assigned a lower "penalty" value so that he or she has a better chance of handling a call for that product or service. It is worth noting that the "penalty" parameter does not work in isolation, but works with other queue configuration parameters such as "ring strategy", "timeout" and "wrap-up time". Together, these parameters allow you to adapt the call handling process to individual needs and preferences within your company or organization.

The context option allows you to remove a call from the queue and redirect the call directly to an extension matching that specific context.

With joinempty, when a caller tries to join a queue, members of that queue are checked. If all agents are deemed unavailable due to any of the conditions listed for this option, the caller will not be able to enter the queue. For the leavewhenempty option, the status of queue members is checked periodically while the caller is in the queue. If all agents are unavailable due to any of the  conditions listed for this queue, the caller will be removed from the queue.
The timeout option refers to the waiting time for the agent’s response. If the agent does not answer the call within the specified time, the call will be forwarded to the next agent. The retry option tells you after how many seconds an attempt will be made to reconnect to an agent that has not previously received a call from the queue.
The wrapuptime option specifies the time the agent has to finish handling the connection after disconnecting from the client. After this time, the queue will see the agent ready to answer the next call.

The autopause = yes option changes the status from ready to pause for an agent who does not answer the call. However, autopausebusy = yes will also change the agent’s status to pause when the device on which the agent is logged in has a busy status when the agent does not answer the call.

The musicclass option specifies which announcement class applies to this particular call queue. The only class that can override this class is to set the MOH class with the m option when invoking the Queue application, or set directly on the channel with Set(CHANNEL(musicclass) =my_recording) in the dialplan

The MOH class refers to functionality that allows playing music on hold (MOH - Music On Hold) for a person who is waiting for a call in a queue. Then, instead of hearing the line busy tone, he or she can hear music while waiting, which is more pleasant for the user. The MOH class in Asterisk allows you to select and configure various on-hold music sources, such as audio files in WAV or MP3 format. It is also possible to configure specific waiting music for specific events or channels, allowing for personalized information and experiences received by the call waiting person.

The announce-position = yes option will cause the client waiting in the queue to hear information about his position while waiting for the call to be answered. When the value of this option is equal to “more“, the client will be informed that it is waiting for more connections than the specified limit. It is specified in the announce-position-limit option. You can force the provision of only a single information about the position in the queue by setting the value announce-position = limit Then the information will be provided when the client reaches the position specified in the announce-position-limit option

The announce-holdtime option is responsible for providing waiting customers with an estimated wait time. It can take the values: “yes”, “no” or “once”. The wait time for this last value will only be reported once.

The announce-frequency option determines how many seconds information about the position in the queue or the estimated waiting time will be played.

The reportholdtime=no option will cause the agent, just before establishing communication, to receive no information on how long the client has been waiting for the connection.
The periodic-announce option specifies the name of the sound file containing additional information that is played periodically to the client while waiting in the queue. The repetition time is specified by the periodic-announce-frequency option

Now let’s discuss how to assign agents to a queue. We can do this in two ways: by assigning static agents or adding agents dynamically.

2) Static agents

Entries starting with the member keyword show us which agents are permanently assigned to the queue.

In this particular case, we have two permanently assigned agents, defined as 101 and 102 in the sip.conf configuration file. If we would like to add additional agents permanently or remove some from the queue, we must manually edit them here.
					member => SIP/101,,,,no,20
member => SIP/102,,,,no

The full syntax of the member entry is as follows:

					member => interface,[,penalty][,membername][,state_interface][,ringinuse][,wrapuptime]

Here’s what each argument means:

  • interface – specifies which interface will be used for this queue member. The interface can be defined as a phone number, SIP URI, or other protocol identifier.
  • penalty – an optional argument that specifies how much the agent should be “penalized” if it does not answer a call from the queue. The higher the value, the less likely the agent will receive the next call in the queue.
  • membername – an optional argument that allows you to name the agent or interface, making it easier to identify the agent in logs or reports.
  • state_interface – an optional argument that allows you to specify a different interface whose state will also change when an agent is added to the queue or receives a call.
  • ringinuse – an optional argument that determines whether calls will be routed to agents that already have active connections. If you set this value to yes, calls will only be routed to agents who are not busy.
  • wrapuptime – an optional argument that specifies how long the agent should remain in the Wrap-up state after terminating the call. The Wrap-up state allows the agent to finish working with the previous customer and prepare to handle the next call.

Example usage:

member => SIP/101,,,,no,20 – means that the SIP interface named “101” will be used as the queue agent, with default parameters preceding the ringinuse option, which is set to “no” here. Of course, this option could be set for the entire queue, but as you can see, it can be set for each agent separately. Similarly, the last wrapuptime value set to 20, for this particular agent, will overwrite the global value for the entire queue from our example set to 5

3) Dynamic agents

To enable the use of dynamic agents, we must additionally modify the dialplan. In the extensions.conf file, we add a section responsible for assigning dynamic agents to a specific queue and restart the dialplan
					nano /etc/asterisk/extensions.conf
exten => _*1*X!,1,NoOp(Dynamic agent request)
 same => n,Set(sip=SIP/${CUT(CUT(SIP_HEADER(From),@,1),:,2)})
 same => n,Set(queue=queue_${EXTEN:3})
 same => n,AddQueueMember(${queue},${sip})
 same => n,NoOp(Request status: ${AQMSTATUS})
 same => n,GotoIf($["${AQMSTATUS}"="ADDED"]?added:)
 same => n,GotoIf($["${AQMSTATUS}"="MEMBERALREADY"]?memberalready:)
 same => n,GotoIf($["${AQMSTATUS}"="NOSUCHQUEUE"]?nosuchqueue:)
 same => n(added),Playback(agent-loginok)
 same => n,Goto(hangup)
 same => n(memberalready),RemoveQueueMember(${queue},${sip})
 same => n,Playback(agent-loggedoff)
 same => n,Goto(hangup)
 same => n(nosuchqueue),Playback(invalid)
 same => n,Goto(hangup)
 same => n(hangup),Hangup()

					asterisk -x 'dialplan reload'

Thanks to this configuration, by selecting the *1*<queue number> key configuration on the agent’s device, we will dynamically attach this agent to the indicated queue. By pressing this key combination again, the agent will leave the queue. The AddQueueMember and RemoveQueueMember functions are responsible for this. If we do everything correctly, we will hear the agent-loginok message. Additionally, if the queue name is incorrect, we will receive the invalid message.

4) Queue application

Of course, no call would be added to the queue unless we directed it there. The Queue application called from the dialplan is responsible for this. An example section in our extensions.conf file might look like this

					nano /etc/asterisk/extensions.conf
					exten => my_extension,1,NoOp(Call from ${CALLERID(num)} to ${EXTEN})
 same => n,Answer(1)
 same => n,Queue(queue_1)
 same => n,Hangup()

Here we are the application being invoked with only one parameter, the queue name. However, many configuration parameters can be included at this level. Their full description can be obtained by entering the asterisk console and running the command showing us the existing options.
					asterisk -rv
core show application queue


Here are some options that can be used in the Queue command in extensions.conf:

  1. timeout: Sets the waiting time for each call in the queue before forwarding it to the next agent. Example: Queue(myqueue,t,,,30)
  2. musicclass: Sets the wait music for queued calls. Example: Queue(myqueue,t,default)
  3. maxlen: Sets the maximum queue length – when the queue reaches this value, new connections will be rejected. Example: Queue(myqueue,t,,,10)
  4. announce: Sets the announcement that will be played to the client before it is redirected to the queue. Example: Queue(myqueue,t,”Thank you for waiting”)
  5. monitor-format: Sets the queued call recording format. Example: Queue(myqueue,t,,,m(ulaw))

Note: The above examples are just a demonstration and may vary depending on the specific implementation on your Asterisk system.

The full syntax for the Queue command is below

Queue(queuename[,options[,URL[,filename[&filename2[&...]][,timeout[,AGI[,macro[,gosub[,rule[,position]]]]] ]]]])

A detailed description of each option is in asterisk documentation

As you can see, both simple and more advanced queue functions no longer hold any secrets for us. I invite you to follow our blog.

If you would like tomonitor everything that is happening on your PBX, try our proprietary software VOIPERO

The system has recently been launched and is now available completely free of charge. Installation and configuration takes a few minutes

Find out what the VOIPERO system has to offer when it comes to live reporting and monitoring VoIP systems based on Asterisk.

Of course, it can also share information about queues!

Share this post

Do you have questions or you need an offer?

Contact us!

Most popular

Related Posts

We Have Launched

Monitoring & Reporting of Your VoIP Server