VMware ESXi and vSphere Cluster Management

Define Call Queues in Asterisk with queues.conf

Learn how to define Asterisk call queues in queues.conf, use templates and strategies, reload app_queue.so, and verify queues with queue show.

An Asterisk call queue holds inbound callers until an eligible member can answer. A queue is useful for departments such as sales, marketing, support, or billing because callers can wait in an orderly line instead of calling individual extensions.

Asterisk is an open-source PBX and telephony platform. The app_queue.so module provides its call-queue functionality.

How a Queue Fits into Call Handling

A typical inbound call follows this flow:

An inbound call reaches the Asterisk dialplan.
The dialplan or an IVR selects a department such as sales or marketing.
The Queue() application places the caller into the selected queue.
The caller hears music on hold and queue announcements while waiting.
Asterisk chooses an eligible queue member according to the configured strategy.
The call is offered to the selected member or members.

A queue member is an endpoint, channel, agent, or other destination that can receive a queued call. Members may be configured statically, added dynamically, or managed through another application. A member can be configured but still be ineligible because they are logged out, paused, busy, unavailable, or otherwise unable to receive a call.

Use separate named queues for separate business functions. For example, a sales queue can have sales representatives as members, while a marketing queue can have marketing staff. A person who works in both departments can belong to both queues.

queues.conf Structure

The primary file for static queue definitions is /etc/asterisk/queues.conf. It uses section syntax similar to other Asterisk configuration files.

[general] contains global queue behavior.
A named section such as [sales] defines one queue.
A template section stores settings shared by several queues.
Inheritance lets a named queue reuse template values and override only the settings that differ.

The template marker (!) identifies a section as a template. A queue inherits from a template by placing the template name in parentheses after the queue name, such as [sales](queue_template).

Global Queue Settings

autofill

autofill controls how waiting callers are offered to available members. With autofill enabled, Asterisk can assign multiple waiting callers to multiple available members without unnecessary serial blocking. This generally improves utilization when several members become available at once.

shared_lastcall

shared_lastcall shares a member's recent queue-call timing across queues. This matters when the same member belongs to both sales and marketing. With shared recent-call information, selection and wrap-up restrictions can account for a call the member just handled in either queue.

Wrap-up time is a period after a call during which a member should not receive another queue call. The exact supported behavior, defaults, and option details can vary by Asterisk release. Check the documentation and configuration behavior for the version installed on your system before relying on a particular default.

Reusable Queue Templates

Templates avoid repeating the same options in every departmental queue. They also make policy changes easier: changing a shared value in one template can keep several queues consistent.

[general]
autofill=yes
shared_lastcall=yes

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

[marketing](queue_template)

[sales](queue_template)

In this example, marketing and sales inherit the music-on-hold class, distribution strategy, empty-queue behavior, and busy-member policy from queue_template. A queue-specific option can override an inherited value. For example:

[sales](queue_template)
musicclass=sales-moh

That queue uses the sales-moh music-on-hold class while retaining the other inherited settings.

Core Queue Options

Option	Configuration Scope	Example Value	Operational Effect	Important Considerations
`autofill`	`[general]`	`yes`	Allows waiting callers to be assigned to available members without unnecessary serial blocking.	Supported behavior and defaults can differ by Asterisk version.
`shared_lastcall`	`[general]`	`yes`	Shares recent-call timing for a member across queues.	Useful for members who work in more than one queue; review wrap-up policy as well.
`musicclass`	Queue or template	`default`	Selects the music-on-hold class heard by waiting callers.	The class must exist in the system's music-on-hold configuration.
`strategy`	Queue or template	`rrmemory`	Chooses the member-selection algorithm.	Select a strategy based on fairness, speed, specialization, and predictability.
`joinempty`	Queue or template	`no`	Controls whether callers may enter when no members are available.	When disabled, the dialplan must provide an alternate result such as voicemail or another destination.
`leavewhenempty`	Queue or template	`yes`	Controls whether waiting callers are removed when no members remain available.	Define what the dialplan or queue handling should do after removal.
`ringinuse`	Queue or template	`no`	Prevents offering a second queued call to a member already handling a call.	Busy state and device-state reporting must be accurate for this policy to work as intended.

Choosing a Queue Strategy

A queue strategy is the algorithm Asterisk uses to select the next eligible member. Eligibility is more important than the configured member list: a member who is paused, logged out, unreachable, busy when ringinuse=no, or in wrap-up may be skipped.

Strategy	Member Selection Method	Best Use Case	Fairness and Predictability Notes
`ringall`	Rings all eligible members at the same time.	Fast response when any available person can answer.	Can create simultaneous ringing and does not provide a sequential individual order.
`leastrecent`	Selects the member who has gone longest without receiving a queue call.	Teams seeking time-based fairness.	Fair over call history, but results depend on member availability and prior queue activity.
`fewestcalls`	Selects the member with the smallest completed-call count.	Balancing completed queue-call volume.	Useful for workload balancing; counts and eligibility can make short-term results uneven.
`random`	Chooses an eligible member at random.	Teams where simple distribution is acceptable.	Not predictable and may produce uneven results over a small number of calls.
`rrmemory`	Uses sequential rotation and continues after the member selected for the previous call.	Ongoing rotation across a similarly skilled team.	Fair and easy to understand over multiple calls, but unavailable members are skipped.
`rrordered`	Uses round-robin behavior while honoring configured member ordering.	Rotation where the configured order is operationally meaningful.	More predictable than random selection; confirm exact version behavior locally.
`linear`	Attempts members in their configuration order.	Specialized or tiered handling where order matters.	Highly predictable, but early members may receive more calls than later members.
`wrandom`	Chooses randomly with member penalties influencing selection.	Weighted or skill-oriented distribution.	Less predictable than ordered strategies; understand penalty values before deployment.

Choose rrmemory when fair ongoing rotation is the priority. Choose ringall when response speed is more important than individual distribution. Choose linear or rrordered when predictable member order matters. Use leastrecent or fewestcalls for workload balancing, and weighted or random strategies when member specialization or flexible distribution is more important than strict predictability.

Define Marketing and Sales Queues

The following complete example creates two departmental queues with shared behavior:

[general]
autofill=yes
shared_lastcall=yes

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

[marketing](queue_template)

[sales](queue_template)

Here, callers cannot enter when no eligible members are available because joinempty=no. Waiting callers are removed if no members remain available because leavewhenempty=yes. A member who is already on a call is not offered another call because ringinuse=no.

These sections do not add static members or cause inbound calls to reach either queue. Next, add static or dynamic members using the member-management method selected for your deployment, and route calls to the exact queue names from the dialplan or IVR.

Supporting Configuration Prerequisite

Some Asterisk versions or queue-module setups expect /etc/asterisk/agents.conf to exist, even when you do not use it to manage members. Modern deployments may use other static or dynamic member-management methods, but the file can still be required by the installed module behavior.

touch /etc/asterisk/agents.conf

Run the command with suitable privileges and confirm that the file is readable by the Asterisk process. Do not assume that creating this file replaces your chosen member-management configuration.

Apply Queue Changes Safely

After creating or editing queues.conf, reload the queue application from the Asterisk CLI:

module reload app_queue.so

Reloading app_queue.so applies queue-module configuration without restarting the entire Asterisk service. A full restart affects all active telephony services and is normally unnecessary for a queue-definition change.

Verify Queues with the Asterisk CLI

Use this command to display all loaded queues, their members, callers, and metrics:

queue show

To inspect one queue in more detail, use:

queue show sales

Status Field	What It Represents	Expected Value for a Newly Defined Empty Queue	What to Investigate if Unexpected
Queue name	The named queue section loaded by Asterisk.	`marketing` or `sales`.	Check the file path, section spelling, inheritance syntax, and reload result.
Call count	Number of callers currently waiting.	Zero callers, often displayed as `No Callers`.	Check active test calls, dialplan routing, and caller-exit behavior.
Maximum callers	The configured capacity for waiting callers.	Often the system or queue default if not explicitly configured.	Check the queue's capacity-related settings and local version output.
Strategy	The active member-selection algorithm.	`rrmemory` for the example.	Confirm the inherited value, any queue-specific override, and successful reload.
Hold time	Recorded or current waiting-time metric, depending on version and activity.	Usually zero or an empty initial value.	Check whether calls have entered the queue and how the installed version reports metrics.
Talk time	Recorded or current average talk-time metric.	Usually zero or an empty initial value.	Check completed queue calls and local metric definitions.
Member status	Configured members and whether they are available, paused, busy, logged in, or reachable.	`No Members` because only the queue was defined.	Add or log in members and check endpoint reachability and pause state.
Caller status	Waiting callers and their position or state.	`No Callers`.	Check whether the dialplan invokes the intended queue and whether callers were refused by `joinempty`.

An immediately defined queue commonly reports both No Members and No Callers. That is expected: the queue exists, but no members have been added and no calls have been routed into it yet. Confirm that both named queues appear and that their displayed strategy matches the intended value.

Troubleshooting

The queue module does not load or reload

Review the Asterisk CLI messages generated by module reload app_queue.so.
Check for syntax errors in /etc/asterisk/queues.conf.
Confirm that the file is in the correct location and readable by Asterisk.
Confirm that /etc/asterisk/agents.conf exists if the installed version requires it.
Check whether app_queue.so is available, enabled, and free of unmet dependencies.

The queues do not appear in queue show

Verify that the definitions were saved in /etc/asterisk/queues.conf.
Check section names and template inheritance expressions.
Reload app_queue.so and correct any parsing errors before running queue show again.

The queue reports No Members

Defining a queue alone does not create members. Add static members, have dynamic members log in, or use the selected external member-management method. Also check whether existing members are paused, logged out, busy, unreachable, or unavailable.

Callers cannot enter the queue

joinempty=no can prevent entry when no eligible members are present. The dialplan must handle the resulting refusal or alternate path. Also verify that the dialplan or IVR invokes Queue() with the exact section name, such as sales.

Distribution seems unfair

Confirm the displayed strategy and test several calls rather than judging from one call. Only eligible members participate. Pauses, penalties, busy status, device availability, wrap-up restrictions, and the number of active members can all make distribution appear uneven.

A shared member receives calls too quickly

For a member assigned to both sales and marketing, confirm shared_lastcall=yes. Then review the member's wrap-up-time policy and assignments across both queues. Shared recent-call behavior helps coordinate queue selection, but it does not replace a deliberately designed wrap-up policy.

Next Configuration Steps

Add static queue members or configure dynamic member login and logout.
Route inbound calls into Queue() from extensions.conf, an IVR, or an automated attendant.
Configure announcements, periodic messages, timeouts, maximum callers, caller exit behavior, and overflow destinations.
Set member penalties when skill or priority-based routing is needed.
Define agent pause, availability, and wrap-up policies.
Test calls with available, busy, unavailable, paused, logged-out, and absent members.
Test both departments separately and test a member who belongs to both queues.

Once the queues, members, and routing are connected, verify real call behavior rather than relying only on configuration output. Confirm that waiting callers hear the intended music, eligible members ring according to the selected strategy, busy members are handled as expected, and no-member conditions follow the intended alternate route.

Exam- and Operations-Relevant Notes

queues.conf defines queues; it does not automatically define members or dialplan routes.
[general] holds global settings such as autofill and shared_lastcall.
[queue_template](!) creates a reusable template, while [sales](queue_template) inherits it.
Queue-specific settings can override inherited template values.
ringinuse=no is the key setting in the example for avoiding a second offered call to a member already on a call.
joinempty controls entry when no members are available; leavewhenempty controls waiting callers after members become unavailable.
module reload app_queue.so is the targeted reload command; a full Asterisk restart is not normally required.
queue show confirms loaded queue names, strategies, member state, callers, and operational metrics.

For related work, see Define call queues in Asterisk as the reference point for this queue-configuration topic.