Table of Contents
1) Basic queue configuration
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
[general]
persistentmembers = yes
autofill = yes
shared_lastcall=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
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.
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
[queue_1] ; queue_1 - Kolejka testowa
strategy=ringall
context=default
leavewhenempty=unavailable
joinempty=paused
timeout = 15
retry=1
wrapuptime = 5
autopause = yes
autopausebusy = yes
musicclass=default
announce-position=yes
announce-position-limit = 5
announce-holdtime=yes
announce-frequency=15
reportholdtime=no
periodic-announce=recordings/wav/annoucement
periodic-announce-frequency=15
member => SIP/101,,,,no,20
member => SIP/102,,,,no
queue_1 The number of configuration options is very large. We will focus on some of the most important and most frequently used ones. 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 callfewestcalls– calls the agent who has the fewest answered calls in this queuerandom– assigns connections by selecting agents randomlyrrmemory– (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 torrmemory, 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 addedwrandom– calls a randomly selected agent, but uses thepenaltyparameter assigned to the agent as a weight when calculating its position in the queue.
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.
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. 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. 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.
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. 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.
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 toyes, calls will only be routed to agents who are not busy.wrapuptime– an optional argument that specifies how long the agent should remain in theWrap-upstate after terminating the call. TheWrap-upstate 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
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
[queue_dynamic_agents]
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()
asterisk -rv
core show application queue
Here are some options that can be used in the Queue command in extensions.conf:
- timeout: Sets the waiting time for each call in the queue before forwarding it to the next agent. Example: Queue(myqueue,t,,,30)
- musicclass: Sets the wait music for queued calls. Example: Queue(myqueue,t,default)
- maxlen: Sets the maximum queue length – when the queue reaches this value, new connections will be rejected. Example: Queue(myqueue,t,,,10)
- 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”)
- 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!
