VMware ESXi and vSphere Cluster Management

Route Incoming Calls to Asterisk Queues with Dialplan Extensions

Learn how to create Asterisk queue access extensions, connect local callers to named queues, configure members, reload settings, and troubleshoot queue routing.

Asterisk can send callers to a queue where calls are distributed among available members. This lesson shows how to create dialable queue entry points for marketing and sales, make those extensions reachable from a local dialing context, define queue members, and verify the complete call path.

How the Queue application works

Queue() is an Asterisk dialplan application. It accepts the current caller and places that caller into a named call-distribution queue. A queue then attempts to deliver the call to an eligible member according to its configured policy.

A queue access extension and a queue definition are different things:

• The queue access extension is a dialable number in the dialplan. It determines how a caller enters the queue.
• The queue definition describes the queue's members and behavior. It is commonly stored in queues.conf.

A typical call flow is:

1. The caller dials an extension such as 605.
2. The dialplan executes an entry action, such as a diagnostic log message.
3. Queue(marketing) starts queue processing.
4. An available marketing member may receive the call.
5. If the caller abandons, a timeout or queue rule applies, no member is available, or another exit condition occurs, Queue() returns and later dialplan priorities handle the result.

Contexts and queue entry extensions

A context is a named section of the dialplan that defines which extensions are available to a caller. Context boundaries are important for both organization and access control: a phone can normally dial only extensions in its assigned context or in contexts included by that context.

A dedicated [queues] context keeps queue entry points together. In this example, extension 605 reaches marketing and extension 705 reaches sales.

Define the queue access numbers

[queues]
exten => 605,1,Verbose(2,${CALLERID(all)} entering marketing)
same => n,Queue(marketing)
same => n,Hangup()

exten => 705,1,Verbose(2,${CALLERID(all)} entering sales)
same => n,Queue(sales)
same => n,Hangup()

An Asterisk dialplan extension consists of an extension name or number, an ordered priority, and an application. For example, 605,1,Verbose(...) means that priority 1 of extension 605 runs Verbose().

same => n continues the current extension at the next automatically assigned priority. The example therefore executes the applications in this order:

1. Verbose() logs the caller's identity and destination.
2. Queue() sends the caller to the named queue.
3. Hangup() terminates the channel if queue processing returns to this priority sequence.

Mapping access extensions to named queues

The argument passed to Queue() is an internal queue name. It must match the corresponding queue section in queues.conf. The number a caller dials does not need to be the same as that internal name: 605 is the public or internal access number, while marketing is the queue identifier used by Asterisk.

Caller identification and diagnostic logging

Verbose() writes a diagnostic message at a selected verbosity level. The expression ${CALLERID(all)} expands to the channel's caller identity representation, which helps identify who entered the queue.

Verbose(2,${CALLERID(all)} entering marketing)

The verbosity level affects when the message appears in the Asterisk console and logs. If the console verbosity is lower than the level used by Verbose(), the message may not be displayed there. Logging output can also depend on the active Asterisk logging configuration.

Make queue extensions reachable from local phones

Defining 605 and 705 in [queues] does not automatically make them available to every phone. Add the queue context as an include inside the local dialing context used by the relevant endpoints.

[local]
include => queues

An include makes extensions from one context available while Asterisk is processing calls in another context. The directive must be placed inside the correct context block. It should not be treated as a global directive or placed in an unrelated context.

The endpoint's configured context must ultimately lead to [local], or to another context that includes [queues]. For example, if a phone has context=local, it can use the included queue extensions. If a trunk or endpoint uses a restricted context without that include, dialing 605 may produce an invalid extension result.

Define queue members in queues.conf

Callers cannot be effectively served until the target queues have usable members. queues.conf is commonly used for static queue definitions and members. A static member is declared in configuration and loaded with the queue configuration. A dynamic member is added or removed while Asterisk is running through queue-management mechanisms.

[marketing]
member => PJSIP/marketing-agent-1
member => PJSIP/marketing-agent-2

[sales]
member => PJSIP/sales-agent-1
member => PJSIP/sales-agent-2

Replace these example interfaces with names that actually exist in the PBX. A member interface may be a supported device or channel interface, such as a PJSIP endpoint, a Local channel, or another valid Asterisk interface. The spelling and format must match the configured endpoint or channel.

The section names are significant: [marketing] satisfies Queue(marketing), and [sales] satisfies Queue(sales). Queue deployments commonly also configure distribution strategy, member timeout, retry behavior, announcements, music on hold, and availability rules.

Configuration responsibility by file

Understand the post-Queue() sequence

Queue() does not guarantee that the caller will connect to an agent. It can return when the caller abandons the call, a timeout or queue rule is reached, no members are available, all members are ineligible, or another configured exit condition occurs.

The simple baseline uses Hangup() after Queue(). A production dialplan may instead play an announcement, send the caller to voicemail, route to an overflow queue, or offer a callback before terminating the call.

exten => 605,1,Verbose(2,${CALLERID(all)} entering marketing)
same => n,Queue(marketing)
same => n,Hangup()

Apply and verify the configuration

After editing extensions.conf, reload the dialplan from the Asterisk CLI:

dialplan reload

After editing queues.conf, reload the queue configuration when supported by the installed Asterisk version and permitted by your operational procedures:

queue reload all

Verify that the extensions and queues are loaded:

dialplan show 605@queues
queue show marketing
queue show sales

Inspect the queue output for the expected members and their availability. Then place a controlled test call to 605 and 705. Observe the Asterisk console, queue status, caller treatment, and whether the correct member endpoints ring.

Queue call flow

Troubleshooting

The queue number is reported as an invalid extension

• Confirm that the caller's endpoint or trunk uses the expected context.
• Confirm that include => queues is inside the correct local context block.
• Run dialplan show 605@queues and check that the extension exists.
• Run dialplan reload after editing extensions.conf.

The extension runs but no agent receives the call

• Run queue show marketing or queue show sales.
• Check that the queue name in Queue() exactly matches the section in queues.conf.
• Verify that the queue has members and that their interface names are valid.
• Check endpoint registration, device state, member pause state, busy status, and other availability conditions.

A configuration change has no effect

• Verify that you edited the file actually used by the deployment.
• Reload the appropriate subsystem and review CLI or log messages for syntax errors.
• Use dialplan and queue show commands to inspect active state rather than relying only on file contents.
• Check whether a GUI, template generator, or configuration-management process overwrote the manual change.

No caller-entry diagnostic appears

• Increase console verbosity as appropriate for the test.
• Confirm that the call entered the expected extension and context.
• Check the configured Asterisk log destinations.

Operational and security considerations

• Control which phones, trunks, and users can reach queue entry points through endpoint context assignments and context includes.
• Do not expose internal queue access numbers to untrusted callers unless that access is intentional.
• Use descriptive queue names and log messages so administrators can identify the destination quickly.
• Document the relationship between each dialing number, its dialplan context, its Queue() argument, and its queue section.
• Plan behavior for waiting callers, unavailable members, no-answer members, queue timeouts, overflow, and other exit conditions.

Summary

A queue route has two connected layers: the dialplan provides a dialable entry extension, while queues.conf defines the named queue and its members. In this example, callers use 605 for marketing and 705 for sales. The [local] context includes [queues], allowing authorized local endpoints to reach those numbers. After reloading both relevant configurations, verify the dialplan, queue members, and controlled test calls.

For the next stage, see allowing calls into the queue as part of a broader queue-access design.