Asterisk config queues.conf

ACD (Automatic Call Distributor) distributes incoming calls in the order of arrival to the first available agent. The system answers each call immediately and, if necessary, holds it in a queue until it can be directed to the next available call center agent. Balancing the workload among agents ensures that each caller receives prompt and professional service.

Asterisk supports multiple call queues. They are defined in the queues.conf file and then referenced as arguments to the Queue application in extensions.conf. Agents are defined in the agents.conf file.

What is Asterisk

Asterisk is a free open source framework for building your own communication applications. Thanks to the tool kit, you can equip your business with a PBX solution on Linux, BSD and OS X. It can be used to support IP telephony with functions such as automatic call distribution, IVR systems, codec translation and more given sufficient Linux and telephony know-how.

General

Persistent Members

Store each dynamic member in each queue in the astdb so that when asterisk is restarted, each member will be automatically read into their recorded queues. Default is ‘yes’.

persistentmembers = yes

Keep Stats

Keep queue statistics during a reload. Default is ‘no’

keepstats = no

AutoFill Behavior

The old/current behavior of the queue has a serial type behavior in that the queue will make all waiting callers wait in the queue even if there is more than one available member ready to take calls until the head caller is connected with the member they were trying to get to.

The next waiting caller in line then becomes the head caller, and they are then connected with the next available member and all available members and waiting callers waits while this happens.

The new behavior, enabled by setting autofill=yes makes sure that when the waiting callers are connecting with available members in a parallel fashion until there are no more available members or no more waiting callers.

This is probably more along the lines of how a queue should work and in most cases, you will want to enable this behavior.

If you do not specify or comment out this option, it will default to no to keep backward compatibility with the old behavior.

autofill = yes

Autopause

Autopause will pause a queue member if they fail to answer a call

autopause=yes

Maxlen

Maximum number of people waiting in the queue (0 for unlimited)

maxlen = 0

Set Interface Var

If set to yes, just prior to the caller being bridged with a queue member the following variables will be set
MEMBERINTERFACE is the interface name (eg. Agent/1234)
MEMBERNAME is the member name (eg. Joe Soap)
MEMBERCALLS is the number of calls that interface has taken,
MEMBERLASTCALL is the last time the member took a call.
MEMBERPENALTY is the penalty of the member
MEMBERDYNAMIC indicates if a member is dynamic or not
MEMBERREALTIME indicates if a member is realtime or not

setinterfacevar=no

Set Queue Entry Var

If set to yes, just prior to the caller being bridged with a queue member the following variables will be set:
QEHOLDTIME callers hold time
QEORIGINALPOS original position of the caller in the queue

setqueueentryvar=no

Set Queue Var

If set to yes, the following variables will be set just prior to the caller being bridged with a queue member and just prior to the caller leaving the queue
QUEUENAME name of the queue
QUEUEMAX maximum number of calls allowed
QUEUESTRATEGY the strategy of the queue
QUEUECALLS number of calls currently in the queue
QUEUEHOLDTIME current average hold time
QUEUECOMPLETED number of completed calls for the queue
QUEUEABANDONED number of abandoned calls
QUEUESRVLEVEL queue service level
QUEUESRVLEVELPERF current service level performance

setqueuevar=no

Member Macro

If set, run this macro when connected to the queue member you can override this macro by setting the macro option on the queue application

membermacro=somemacro

Monitor Format

Calls may be recorded using Asterisk’s monitor/MixMonitor resource
This can be enabled from within the Queue application, starting recording when the call is actually picked up; thus, only successful calls are recorded, and you are not recording while people are listening to MOH.
To enable monitoring, simply specify “monitor-format”; it will be disabled otherwise.
You can specify the monitor filename with by calling Set(MONITOR_FILENAME=foo)
Otherwise it will use MONITOR_FILENAME=${UNIQUEID}
Pick any one valid extension for monitor format recording. If you leave monitor-format commented out, it will not record calls.

monitor-format = gsm|wav|wav49

Monitor Type

By setting monitor-type = MixMonitor, when specifying monitor-format to enable recording of queue member conversations, app_queue will now use the new MixMonitor application instead of Monitor so the concept of “joining/mixing” the in/out files now goes away when this is enabled.
You can set the default type for all queues here, and then also change monitor-type for individual queues within queue by using the same configuration parameter within a queue configuration block.
If you do not specify or comment out this option, it will default to the old ‘Monitor’ behavior to keep backward compatibility.

monitor-type = MixMonitor

UpdateCDR behavior.

This option is implemented to mimic chan_agents behavior of populating CDR dstchannel field of a call with an agent name, which you can set at the login time with AddQueueMember membername parameter.

updatecdr = no

Shared lastcall

shared_lastcall will make the lastcall and calls received be the same in members logged in more than one queue.
This is useful to make the queue respect the wrapuptime of another queue for a shared member

shared_lastcall=no

queue specific config

Musicclass

Musicclass sets which music applies for this particular call queue.
The only class which can override this one is if the MOH class is set directly on the channel using Set(CHANNEL(musicclass)=whatever) in the dialplan.

music

Servicelevel

Second settings for service level (default 0)
Used for service level statistics (calls answered within service level time frame)
servicelevel = 60

New feature (Jul 31, 2005 CVS HEAD)

Periodic announcements are available in queues using the new periodic-announce and periodic-announce-frequency options. This allows a message like “Thank you for holding, your call is important to us.” to be played at regular intervals while a caller is in the queue. e.g:

periodic-announce = thank-you-message
periodic-announce-frequency = 60 ; every 60 seconds

Weight New feature (Jan 06, 2005):

Gives queues a ‘weight’ option, to ensure calls waiting in a higher priority queue will deliver its calls first. Only delays the lower weight queue’s call if the member is also in the higher weight queue. Thanks to k3v for this option
Weight of queue – when compared to other queues, higher weights get first shot at available channels when the same channel is included in more than one queue.

weight=0

weight = expects an integer value

This option may cause a queue deadlock – please see Bug Note 6196 http://bugs2.digium.com/view.php?id=6196 for information and patch

Also there is undocumented option – queue-callerannounce. It allows to play file to caller.

Join empty

If there are calls queued, and the last agent logs out, the remaining incoming callers will immediately be removed from the queue, and the Queue() call will return, If leavewhenempty” is set to “strict”.
“joinempty” set to “strict” will keep incoming callers from being placed in queues where there are no agents to take calls. The Queue() application will return, and the dial plan can determine what to do next.
This setting controls whether callers can join a queue with no members.
There are three choices:

yes – callers can join a queue with no members or only unavailable members
no – callers cannot join a queue with no members
strict – callers cannot join a queue with no members or only unavailable members
loose – same as strict, but paused queue members do not count as unavailable (new in 1.6)

joinempty = yes

Asterisk 1.8:

paused – a member is not considered available if he is paused
penalty – a member is not considered available if his penalty is less than QUEUE_MAX_PENALTY
inuse – a member is not considered available if he is currently on a call
ringing – a member is not considered available if his phone is currently ringing
unavailable – This applies mainly to Agent channels. If the agent is a member of the queue but has not logged in, then do not consider the member to be available
invalid – Do not consider a member to be available if he has an “invalid” device state. This generally is caused by an error condition in the member’s channel driver.
unknown – Do not consider a member to be available if we are unable to determine the member’s current device state.
wrapup – A member is not considered available if he is currently in his wrapuptime after taking a call.

Leave When Empty – New feature (Sep 28, 2004):

Introduced right after the v1.0 release
If you wish to remove callers from the queue when new callers cannot join, set this setting to one of the same choices for ‘joinempty’

leavewhenempty = yes

If you are using CVS-HEAD and agents the queue app sees the agents as queue members always thus breaking this try:
leavewhenempty=strict

NOTE: In version 1.0.9 (and perhaps other versions of the 1.0 release series), you must use Asterisk cmd AddQueueMember instead of Asterisk cmd AgentCallbackLogin or Asterisk cmd AgentLogin if you want the options leavewhenempty and joinempty to work properly. If you have any static queue members defined as “Member => Agent/XXXX” in your Queue definition, Asterisk will considered the Queue in-use, regardless of whether any Agents are logged in or not. AddQueueMember() on the other hand will dynamically add and remove the interface from the queue… and these options will work properly.

Event Member Status

If this is set to yes, the following manager events will be generated:
QueueMemberStatus
(may generate a WHOLE LOT of extra manager events)

eventmemberstatus = no

Report Hold Time

If you wish to report the caller’s hold time to the member before they are connected to the caller, set this to yes.

reportholdtime = no

Ring Inuse

If you want the queue to avoid sending calls to members whose devices are known to be ‘in use’ (via the channel driver supporting that device state)

uncomment this option. (Note only the SIP channel driver currently is able to report ‘in use’.)

; ringinuse = no

New feature: Position announcement

Introduced into Asterisk after v0.7.2. See the file queues.conf.sample for configuration options like


  ; Calls may be recorded using Asterisk's monitor resource 
  ; This can be enabled from within the Queue application, starting recording 
  ; when the call is actually picked up; thus, only successful calls are 
  ; recorded, and you are not recording while people are listening to MOH. 
  ; To enable monitoring, simply specify "monitor-format"; it will be disabled 
  ; otherwise. 
  ; 
  ; monitor-format = gsm|wav|wav49 
  
  ; How often to announce queue position and/or estimated holdtime to caller (0=off) 
  ; 
  ;announce-frequency = 90 
  ; 
  ; Should we include estimated hold time in position announcements? 
  ; Either yes, no, or only once; hold time will not be announced if <1 minute 
  ; 
  ;announce-holdtime = yes|no|once 
  ; 
  ; Use these sound files in making position/holdtime announcements. The 
  ; defaults are as listed below -- change only if you need to. 
  ; 
  ;queue-youarenext = "queue-youarenext" ; ("You are now first in line.") 
  ;queue-thereare = "queue-thereare" ; ("There are") 
  ;queue-callswaiting = "queue-callswaiting" ; ("calls waiting.") 
  ;queue-holdtime = "queue-holdtime" ; ("The current est. holdtime is") 
  ;queue-minutes = "queue-minutes" ; ("minutes.") 
  ;queue-minute = "queue-minute" ; ("minute.") 
  ;queue-thankyou = "queue-thankyou" ; ("Thank you for your patience.") 
  ;Note: when the semicolons don't work, leave them out e.g.:
  ;queue-thankyou=yoursoundfile
  ;
  ; Note that a timeout to fail out of a queue may be passed as part of application call 
  ; from extensions.conf: 
  ; Queue(queuename|[options]|[optionalurl]|[announceoverride]|[timeout]) 
  ; example: Queue(dave|t|||45)

Understanding announcements

The key point with announcements is that they are only played within the timeout/retry period set on the queue. For the most part this works OK as when all queue members are busy/unavailable, the timeout/retry period is effectively ignored (i.e. you can consider the queue to always be in this state) and announcements will be played as per your setting of the announce-frequency and periodic-announce-frequency parameters. When a handset is available and the queue is ringing it, the timeout/retry timeouts become critical. For example, if you want announcements every 20 seconds, but the timeout is set to 60 seconds, when a queue member is ringing, you will only ever get announcements every 60 seconds.

Queue position announce?
Either yes or no. If turned off, only the holdtime will be announced (as configured in announce-holdtime) (1.6.X default=no)
‘announce-position’ = yes | no

‘announce-frequency’ controls how often the queue position (if ‘announce-position’ is set), estimated hold time (‘announce-holdtime’) and the thank you file (‘queue-thankyou’) are played.

‘min-announce-frequency’ defines a minimum time which must pass between position/holdtime announcements. This stops the caller receiving multiple queue position announcement messages in quick succession for a queue that has many callers and is being serviced quickly.

‘periodic-announce-frequency’ defines how often the file(s) defined in ‘periodic-announce’ are played.

Note that calls are not offered to queue members whilst the announcement is playing and it is possible for callers to slip ahead in the queue as a result. For example, call 1 arrives and is queued. Call 2 arrives ten seconds later and is queued. After twenty seconds, call 1 is played the periodic announce message. Exactly one second after call 1 starts hearing the message an agent becomes free. Since call 1 is tied up with announcements, call 2 is successfully offered to the agent. Call 1 remains on hold and yet a call which arrived later has been serviced.

Wrapuptime

This setting can be in agents or in the queue. But it needs to be in the queue.conf file for agents that are are listed as members.
After a successful call, how long to wait before sending a potentially free member another call (default is 0, or no delay);
wrapuptime=15

Memberdelay

This sets a delay period between the time that the member answers the call and when it is connected.
If you wish to have a delay before the member is connected to the caller (or before the member hears any announcement messages), set this to the number of seconds to delay.
memberdelay = 5

timeoutrestart

If timeoutrestart is set to yes, then the time out for an agent to answer is reset if a BUSY or CONGESTION is received.
This can be useful if agents are able to cancel a call with reject or similar.
(I found that when agents return NOANSWER (ring, no-answer) this also causes the queue to move to the next agent in a round robin)
timeoutrestart = yes

Strategy

Calls are distributed among the members handling a queue with one of several strategies

ringall: ring all available channels until one answers (default)
roundrobin: take turns ringing each available interface (depreciated in 1.4, use rrmemory)
leastrecent: ring interface which was least recently called by this queue
fewestcalls: ring the one with fewest completed calls from this queue
random: ring random interface
rrmemory: round robin with memory, remember where we left off last ring pass
linear: Rings interfaces in the order they are listed in the configuration file. Dynamic members will be rung in the order in which they were added. (new in 1.6)
wrandom: Rings a random interface, but uses the agent’s penalty as a weight (new in 1.6)

Rings random interface, but uses the member’s penalty as a weight when calculating their metric.
So a member with penalty 0 will have a metric somewhere between 0 and 1000, and a member with penalty 1 will have a metric between 0 and 2000, and a member with penalty 2 will have a metric between 0 and 3000.
Please note, if using this strategy, the member penalty is not the same as when using other queue strategies.
It is ONLY used as a weight for calculating metric.

;strategy=rrmemory

Timeout

How long do we let the phone ring before we consider this a timeout…
Timeout in seconds when calling an agent
timeout=15

Retry

How long do we wait before trying all the members again?

retry = 5

Context

A context may be specified, in which if the user types a SINGLE digit extension while they are in the queue, they will be taken out of the queue and sent to that extension in this context.
context=<context>
This is the context that is used to allow the caller to exit with a key for further action. For example, press “1” to leave a message

Default Rule

If you wish to implement a rule defined in queuerules.conf (see configs/queuerules.conf.sample from the asterisk source directory for more information about penalty rules) by default, you may specify this by setting defaultrule to the rule’s name

defaultrule = myrule

announce

The “announce = XXX” option in queues.conf makes Asterisk play the XXX announcement to the member of the queue who picks up the call in a similar manner to the A() option of the Dial() cmd. This can also be invoked in the Queue() application (‘Queue(queuename,options,URL,announceoverride,timeout,AGI,macro,gosub,rule)’).

Note that the announcement is played in the language set on the answering device, not in the language of the originating channel.

Examples

http://astrecipes.net/?n=42

Tutorials

- Asterisk Queues Tutorial (from Orderly Software).

Notes

The penalty parameter: You can have agents that are less likely to take calls (e.g. imagine a sales queue, you’d have the sales people with no penalty, you might have the receptionists with a penalty of 1 and us propeller heads in technical support with a penalty of 2). The technical support people would only be offered a call from the sales queue if all the sales people and the receptionists were busy.
If you include groups in your queue definition the calls get routed in the order of the group regardless of the specified strategy. So I just have a member= line for each agent.

member => Agent/@1 ; a group
member => Agent/501 ; a single agent
member => Agent/:1,1 ; Any agent in group 1, wait for first available, but consider with penalty

Some notes about roundrobin and rrmemory

roundrobin is not to be confused with “circular call distribution”, infact even using roundrobin without memory subsequent calls are circulated between agent, here in detail it’s how it works, by kpfleming.

round robin mode remembers the last agent it _started_ with for a new call, and starts with the next agent in the list. If you have three agents, the first call will go to agent 1->2->3, the next call will go to 2->3->1, the next call will go to 3->2->1, etc.

rrmemory mode remembers the last agent it tried to _call_, regardless of who it started with, so that the next call will go the agent after the last one who answered. If you have three agents and the first call rings 1->2 (and is answered), then the next call will ring 3->1 (and is answered), then the next call will ring 2->3->1, etc. For the first call, if agent 2 answered it in round robin mode, they would still be the first agent for the next call, but rrmemory mode will move past them.

You can, however, achieve circular call distribution by using round robin mode and putting a different penalty on each agent, in the order you wish them to be called. app_queue will always try all agents with no penalty, then the ones with penalty 1, etc. NOTE that this does not apply to 1.4.13 (an possibly earlier versions). There is no ’roundrobin’ strategy any more and ‘rrmemory’ will continue to try the lowest priority handset(s) – there is no way of doing circular call distribution any more.