Defining Call Queues in Asterisk with queues.conf

Learn to define, template, load, and verify Asterisk call queues with queues.conf, including distribution strategies, queue behavior, and CLI troubleshooting.

An Asterisk queue is a call-handling construct that holds inbound callers until an eligible queue member can answer. A queue can play music on hold, apply entry and departure rules, and distribute calls according to a configured strategy.

Queue configuration is only one part of the complete call flow. The queue definition does not add agents, register endpoints, or route callers into the queue. Those responsibilities belong to separate configuration areas:

Queue definitions: Created in queues.conf.
Queue members: Static or dynamic agents, devices, endpoints, or interfaces that can receive queue calls.
Caller entry: Dialplan or an automated attendant sends callers to the Queue() application.
Agent and endpoint state: Registration, availability, pause, login, and device-state configuration determine whether a member is eligible.

A queue may be defined and loaded successfully even when it has no callers and no members. This is useful when building the configuration in stages.

How queues.conf is organized

The queue configuration file is commonly located at /etc/asterisk/queues.conf. The exact configuration directory can vary by installation, so use the active Asterisk configuration directory for your system.

The file normally contains a [general] section, optional template sections, and one section for each named queue:

[general] contains queue-wide defaults.
A template section stores reusable settings.
A named section such as [sales] defines one queue.

Section names become queue names. For example, [sales] creates a queue named sales, which can later be referenced by queue routing.

Templates and inheritance

A queue template is a reusable section whose settings can be inherited by multiple queues. The template marker is an exclamation mark in the section header:

[queue_template](!)
...

[marketing](queue_template)

[sales](queue_template)

The named queues inherit the options from queue_template. A queue can then add a new option or override an inherited option when it needs different behavior. Templates reduce repetition and make common queue behavior easier to maintain consistently.

Global queue settings

Settings in [general] affect queue operation globally unless a setting is supported and overridden at a more specific scope. Design these defaults carefully because a global choice can affect every queue.

[general]
autofill=yes
shared_lastcall=yes

autofill

autofill allows waiting callers to be assigned to available members efficiently rather than unnecessarily constraining assignments to a strictly serial pattern. This is useful when several members become available while multiple callers are waiting.

shared_lastcall

shared_lastcall shares a member's last-call tracking across queues. This matters when one member belongs to multiple queues: wrap-up time and recent-call information can be considered across those queues instead of independently.

Wrap-up time is a post-call interval during which a member is not offered another queue call. Sharing last-call information can help prevent a member from immediately receiving work from another queue when the operational policy expects one shared recovery interval.

Core queue behavior settings

Option	Configuration scope	Example value	Behavior	Operational consideration
`autofill`	`[general]`	`yes`	Allows waiting callers to be connected to available members efficiently.	Useful for queues with multiple callers and members; the global setting affects all queues.
`shared_lastcall`	`[general]`	`yes`	Shares member last-call or wrap-up tracking across queues.	Helpful when members serve multiple queues and should have shared cooldown behavior.
`musicclass`	Queue or template	`default`	Selects the music-on-hold class heard by waiting callers.	The class must be available in the music-on-hold configuration.
`strategy`	Queue or template	`rrmemory`	Selects the member-selection algorithm.	Choose according to fairness, ordering, simultaneous alerting, or weighting requirements.
`joinempty`	Queue or template	`no`	Controls whether a caller may enter when no eligible members are available.	`no` prevents entry in that condition; callers may need alternate handling in the dialplan.
`leavewhenempty`	Queue or template	`yes`	Controls whether callers already waiting leave when the queue becomes empty of eligible members.	This governs callers already in the queue and is different from `joinempty`, which governs new entry.
`ringinuse`	Queue or template	`no`	Controls whether a member already handling a call may be rung for another queue call.	`no` is appropriate when a member should handle only one call at a time.

Join and departure rules

joinempty and leavewhenempty answer different questions:

joinempty=no: Should a new caller be allowed to enter when no eligible member is available? Usually no.
leavewhenempty=yes: Should callers already waiting be removed if all eligible members later disappear? Usually yes when callers should be sent quickly to alternate handling.

For example, a caller might enter while a member is available. If that member then logs out or becomes unavailable, leavewhenempty determines what happens to the caller who is already waiting.

Busy members

With ringinuse=no, Asterisk avoids offering another queue call to a member whose device state indicates that the member is already in use. If device state is inaccurate, this setting cannot by itself guarantee correct behavior.

Choosing a distribution strategy

The strategy option controls how Asterisk chooses the next eligible member. The terms available and eligible include the effects of member state, pause state, penalties, and settings such as ringinuse.

Strategy	How members are selected	Memory or ordering behavior	Best-fit use case
`rrmemory`	Starts with the member after the one who received the previous call.	Remembers the previous starting point and wraps around the member list.	Fair rotation across members.
`ringall`	Rings all available members at the same time until one answers.	Simultaneous alerting rather than one-member-at-a-time selection.	Fast response when every available agent should be alerted.
`leastrecent`	Selects the member who was called least recently.	Uses elapsed time since each member's last queue call.	Equalizing time since the last assignment.
`fewestcalls`	Favors the member with the fewest completed queue calls.	Balances call counts rather than elapsed time.	Distributing a similar number of completed calls to each member.
`random`	Selects an available member randomly.	No fixed rotation or configured order is guaranteed.	When random assignment is acceptable.
`rrordered`	Offers calls according to the configured member order.	Preserves configured order instead of using the remembered round-robin starting point of `rrmemory`.	Predictable ordered rotation based on configuration.
`linear`	Offers calls in configured member order.	Uses a fixed priority sequence.	Strict priority ordering.
`wrandom`	Randomizes selection using member penalties as weights.	Penalty values influence selection probability or preference.	Skill or priority weighting where some members should be selected differently.

For example, choose ringall when speed matters more than evenly distributing calls. Choose linear for a fixed priority list. Choose leastrecent or fewestcalls when balancing workload is the main goal. Choose wrandom when member penalties are part of a weighted skills or priority design.

Round-robin with memory

Suppose a queue has three available members in configured sequence: Member 1, Member 2, and Member 3. With rrmemory:

The first call is offered starting with Member 1.
If Member 1 answers, the next call starts with Member 2.
After Member 3 receives a call, the next starting point wraps back to Member 1.

This remembered starting point differs from simply scanning from the first configured member on every call.

Creating marketing and sales queues

The following example applies common behavior globally, defines a reusable template, and creates two named queues without duplicating every option:

[general]
autofill=yes
shared_lastcall=yes

[queue_template](!)
musicclass=default
strategy=rrmemory
joinempty=no
leavewhenempty=yes
ringinuse=no

[marketing](queue_template)

[sales](queue_template)

Both marketing and sales inherit the template's music-on-hold class, distribution strategy, entry and departure rules, and busy-member behavior. To give sales a different strategy, add an override in its section:

[sales](queue_template)
strategy=ringall

Defining these sections does not assign members and does not route calls. Members and caller routing are separate next steps.

Loading the queue configuration

The queue application and module must load successfully before queues can operate. The module commonly involved is app_queue.so, which implements queue functionality and the Queue() application.

After saving queues.conf, access the Asterisk CLI and reload the module:

module reload app_queue.so

Read the reload output. A successful reload should not be assumed if the CLI reports parsing errors, missing dependencies, or module failures. Correct any reported problem before testing the queues.

Legacy agents.conf dependency

Some older or legacy-compatible deployments require an agents.conf file to exist before the queue module loads, even when its contents are not being used for the current queue design. If that applies to the installed system, create the placeholder with:

touch /etc/asterisk/agents.conf

Do not assume this requirement applies to every Asterisk release. Confirm the behavior and required files against the installed version and its module configuration. If the module still fails, inspect the CLI error rather than repeatedly reloading.

Verifying queues from the Asterisk CLI

Use queue show to inspect all configured queues:

queue show

To inspect one queue, provide its name:

queue show sales

Queue status output can include the queue name, active call count, maximum capacity, strategy, hold and talk statistics, waiting count, completed-call count, abandoned-call count, service level, members, and callers. The exact formatting varies by Asterisk version.

An output pattern like the following indicates that the definitions loaded but the queues have not yet been staffed or used:

marketing has 0 calls (max unlimited) in 'rrmemory' strategy
  No Members
  No Callers

sales has 0 calls (max unlimited) in 'rrmemory' strategy
  No Members
  No Callers

0 calls: No active queue calls are present.
rrmemory: The configured distribution strategy is visible.
No Members: No eligible agents or interfaces have been added yet.
No Callers: No callers are waiting, either because routing is not configured or no test call has entered.

Exam-relevant distinction: A queue shown by queue show is loaded, but it is not necessarily ready to serve callers. Staffing, endpoint availability, and dialplan routing are separate requirements.

Queue configuration lifecycle

Stage	Action	Command or configuration area	Expected result
Create configuration	Define global settings, a template, and named queues.	`/etc/asterisk/queues.conf`	The file contains valid queue sections and inherited options.
Create any required legacy placeholder file	Create the file only if the installed deployment requires it.	`touch /etc/asterisk/agents.conf`	The legacy file-existence dependency is satisfied.
Reload queue module	Apply the saved configuration.	`module reload app_queue.so`	CLI output reports a successful reload without configuration errors.
Inspect queues	Confirm names and inherited behavior.	`queue show` or `queue show sales`	Named queues appear with the expected strategy and statistics.
Add members	Configure static or dynamic queue members.	Member configuration and queue administration	Members appear in the queue and become eligible when available.
Route callers into a queue	Send inbound calls to the queue application.	Dialplan using `Queue()` or an automated attendant	Callers enter the intended queue when entry conditions permit.
Place test calls	Test entry, music, availability, distribution, and departure behavior.	Inbound test call and Asterisk CLI	Calls reach the correct members and follow the selected policy.

Troubleshooting common problems

The queue module does not load or reload

Review the CLI reload output for syntax, parsing, dependency, or module errors.
Confirm that the edited queues.conf is in the active Asterisk configuration directory.
On a legacy deployment, confirm that /etc/asterisk/agents.conf exists.
Check the installed Asterisk version because module and legacy-agent behavior differs between releases.

Correct the reported condition, reload app_queue.so, and inspect the result again.

A named queue is missing from queue show

Confirm the file was saved and the section header is exactly named, such as [marketing](queue_template).
Check that you edited the configuration directory used by the running Asterisk process.
Reload app_queue.so after making changes.
Look for a parse error that prevented the section from loading.

The queue appears but says No Members

This normally means only the queue definition exists. Add static or dynamic members, verify their endpoint registration where applicable, and confirm that they are not paused or otherwise unavailable.

Callers cannot enter

Confirm that inbound dialplan or attendant logic invokes Queue() with the correct queue name.
Check whether joinempty=no is blocking entry because no eligible members exist.
Check spelling and capitalization of the queue name used by routing.

Then add routing, staff the queue, or intentionally adjust the entry policy.

Waiting callers leave unexpectedly

If leavewhenempty=yes is inherited from the template, callers may be removed when no eligible members remain. Review the template and queue-specific overrides, then decide whether callers should leave immediately or receive alternate handling.

A busy member receives another queue call

Check whether ringinuse is enabled. Set it to no when members should not receive another queue call while already busy. If the setting is correct, investigate endpoint and device-state reporting.

What to configure next

After the queues load and appear in queue show, continue with:

Add static or dynamic queue members.
Configure member penalties or skills if the selected strategy uses them.
Build inbound dialplan or automated-attendant paths that call Queue(marketing) or Queue(sales).
Test calls entering the queue, hearing music on hold, waiting for members, and leaving when conditions change.
Verify the selected strategy with multiple available members and test busy-member behavior.

For endpoint and routing foundations, see Registering Phones To Asterisk, The Dial Application, and Using Templates.