VMware ESXi and vSphere Cluster Management

Asterisk Dialplan Extensions: Syntax, Contexts, Priorities, and Applications

Learn how Asterisk extensions work, including contexts, exact and pattern matches, priorities, applications, arguments, and dialplan reloads.

In Asterisk, an extension is a named dialplan entry made up of ordered call-processing steps. It is not necessarily a physical telephone, user, or endpoint. An extension can describe what Asterisk should do when a caller dials a number, when an incoming call reaches a service, or when another part of the dialplan transfers control to it.

The dialplan is Asterisk's call-processing logic. It determines how calls are answered, routed, given audio, transferred, or terminated. A call is processed on a channel, which is the call leg or communications path being handled by Asterisk.

How an Asterisk Extension Works

When a call arrives or a caller dials digits, Asterisk evaluates the current channel's context and looks for an extension name or pattern that matches the requested destination. A context is a named group of extensions and also acts as a routing and security boundary.

  1. A channel enters a context, such as internal or public.
  2. Asterisk performs extension matching using the dialed value or another requested extension identifier.
  3. A matching extension provides one or more ordered priorities.
  4. Each priority invokes a dialplan application.
  5. The application may allow execution to continue, branch to another location, transfer the call, or end it.

For example, an extension might answer a call, play an audio prompt, and then hang up. Another extension might send the call to a SIP endpoint using the Dial() application.

Extension Declaration Syntax

A traditional Asterisk extension declaration uses this general form:

exten => extension-name,priority,Application(argument1[,argument2...])

The declaration contains the exten keyword, the => delimiter, an extension name, a priority, an application, and an optional comma-separated argument list.

Component — Example — Meaning — Notes

exten — exten — Identifies an extension declaration — This keyword begins the line.

=> — => — Separates the keyword from the extension details — It is part of the standard declaration syntax.

Extension name — 100 or _2XX — The exact value or pattern to match — It is evaluated in the current context.

Priority — 1 or n — The execution position within the extension — Lower priorities run before higher priorities.

Application — Answer() — The operation performed at that step — Examples include answering, playing audio, dialing, and hanging up.

Application arguments — PJSIP/alice — Optional values that control the application — Multiple arguments are separated by commas.

Examples Without and With Arguments

An application can have no arguments:

exten => 100,1,Answer()

An application can have one argument:

exten => 200,1,Dial(PJSIP/alice)

An application can have multiple arguments, depending on that application's syntax:

exten => 300,1,SomeApplication(first-value,second-value)

Always check the documentation or CLI help for the specific application. The meaning, number, order, and format of arguments are application-specific.

Contexts and Extension Matching

A context is a named grouping of extensions. Contexts are declared with a bracketed section name in the dialplan:

[internal]
exten => 100,1,Answer()
exten => 100,n,Playback(hello-world)
exten => 100,n,Hangup()

The channel's assigned context determines where Asterisk searches for a matching extension. A channel in the internal context does not automatically have access to extensions defined only in the public context.

Concept — Role in Call Processing — Example

Context — Defines the set of extensions available to a channel — [internal]

Extension — Identifies a matching call-handling sequence — 100

Priority — Places one step in the sequence — 1 or n

Application — Performs an action on the call — Dial()

Application argument — Supplies data that controls the action — PJSIP/alice

Contexts are also a security boundary. Assigning an untrusted external caller to a context containing internal, privileged, or expensive outbound routes can expose those routes. Keep public, internal, and restricted destinations separated unless access is deliberately controlled.

Exact Extension Names

An exact extension matches one specific value:

[internal]
exten => 100,1,Dial(PJSIP/alice)
exten => 200,1,Dial(PJSIP/bob)

When a caller dials 100 in the internal context, Asterisk can select the first extension. Dialing 200 selects the second. The same number in another context can have a different meaning or may not exist.

Pattern Extensions

A pattern extension matches a class or range of dialed values rather than one exact value. A basic pattern uses an underscore prefix:

[internal]
exten => _2XX,1,Dial(PJSIP/${EXTEN})
exten => _2XX,n,Hangup()

In this introductory example, _2XX matches three-digit values beginning with 2. The ${EXTEN} variable represents the dialed extension value, so dialing 201 causes Asterisk to use PJSIP/201 as the destination argument.

Pattern matching must always be considered together with the current context. A pattern that exists in internal does not automatically apply to a channel assigned to public. Broad patterns should be reviewed carefully because they may expose destinations that were not intended to be reachable.

Priorities: Ordering Steps Within an Extension

A priority is the ordered position of a step within one extension. Asterisk normally executes lower priorities before higher priorities.

A simple extension with explicit numeric priorities looks like this:

[internal]
exten => 100,1,Answer()
exten => 100,2,Playback(hello-world)
exten => 100,3,Hangup()

The call flow is:

  1. Priority 1 runs Answer().
  2. Priority 2 runs Playback(hello-world).
  3. Priority 3 runs Hangup().

The n Priority Shorthand

The n priority means “the next priority.” It avoids manually numbering every later step:

[internal]
exten => 100,1,Answer()
exten => 100,n,Playback(hello-world)
exten => 100,n,Hangup()

The first step must establish a starting priority, commonly 1. Each reachable n step advances to the next priority in sequence. Priorities must form a valid reachable path. Missing, duplicated, or incorrectly ordered priorities can cause later actions not to run as intended.

Labels and Branching

A label is a readable name associated with a priority. Labels can make branch destinations easier to understand than numeric positions. They are useful when a call flow has different paths, such as success, failure, timeout, or menu branches.

[service]
exten => 500,1,Answer()
exten => 500,n,SomeApplication()
exten => 500,n(success),Playback(success-message)
exten => 500,n(failure),Playback(failure-message)

The exact way a label is reached depends on the application and the dialplan logic. Treat labels as names for reachable priority locations, not as separate extensions.

Priority form — Meaning — Example usage

Explicit numeric priority — A specific execution position — exten => 100,2,Playback(hello-world)

n next priority — The next sequential position after the previous step — exten => 100,n,Hangup()

Named label — A readable name for a priority or branch destination — exten => 100,n(done),Hangup()

Dialplan Applications

An application is the operation performed at one extension priority. Applications can answer calls, play audio, collect input, route calls, set variables, transfer control, or terminate calls.

  • Answer() answers the channel.
  • Playback(hello-world) plays an audio file or prompt.
  • Dial(PJSIP/alice) attempts to connect the call to an endpoint.
  • Hangup() ends the call.

Applications may accept zero, one, or multiple arguments. Arguments change what the application does. For example, the destination passed to Dial() determines which endpoint Asterisk attempts to reach, while the media name passed to Playback() determines which audio is played.

Application behavior affects what happens next. An application may return normally and allow the next priority to execute, end the call, transfer control, or branch based on its result. Consult application-specific documentation before relying on a particular result or argument format.

Reading a Basic Extension

Consider this complete extension:

[internal]
exten => 100,1,Answer()
exten => 100,n,Playback(hello-world)
exten => 100,n,Hangup()

Read each line as a step belonging to extension 100 in the internal context:

  1. exten declares a dialplan extension.
  2. => separates the declaration keyword from its fields.
  3. 100 is the extension name. A caller must match this value in the current context.
  4. 1 is the first priority, and it invokes Answer().
  5. The first n invokes Playback() at the next priority. Its argument, hello-world, identifies the audio prompt.
  6. The second n invokes Hangup() at the following priority, ending the call.

The resulting flow is: match extension 100, answer the call, provide audio, and terminate the call.

Routing a Call to Another Endpoint

An extension does not have to play media. It can route a call to another endpoint:

[internal]
exten => 200,1,Dial(PJSIP/alice)
exten => 200,n,Hangup()

Here, 200 is the extension name, priority 1 invokes Dial(), and PJSIP/alice is the destination argument. The later Hangup() provides cleanup after the dialing application returns.

Separating Contexts

Different contexts can provide different call flows:

[internal]
exten => 100,1,Dial(PJSIP/alice)

[public]
exten => s,1,Playback(custom/welcome)
exten => s,n,Hangup()

An internal channel can match extension 100 in internal. A public incoming call can enter public and begin at the s extension, commonly used when no digits were dialed and the call is being handled as a service entry point. These contexts do not share access merely because they are in the same file.

Configuration Location and Reload Workflow

In a traditional Asterisk installation, dialplan extensions are commonly organized in:

/etc/asterisk/extensions.conf

Place each extension definition under its intended bracketed context. After changing the file, reload the dialplan before testing:

asterisk -rx "dialplan reload"

Verify that the new definitions are loaded:

asterisk -rx "dialplan show"

When local administrative access is available, the interactive console can provide more detailed output:

asterisk -rvvv

Use the console to observe which context and extension Asterisk selects and which priorities execute. A reload makes the dialplan configuration available to new call processing; it does not replace the need to test the actual channel, context, match, and application behavior.

Troubleshooting Extension Execution

The Call Does Not Reach the Expected Extension

  • Verify that the channel is assigned to the expected context.
  • Check whether the dialed value exists as an exact extension or matches a pattern.
  • Use dialplan show to inspect the loaded dialplan rather than only the file on disk.
  • Reload the dialplan after configuration changes and check for errors.

Only the First Action Runs

  • Check that priorities are consecutive or correctly use n.
  • Confirm that later priorities belong to the same extension name and context.
  • Review whether the previous application ends the call, transfers control, or branches elsewhere.
  • Use the verbose Asterisk console to observe execution.

An Application Is Invalid or Unavailable

  • Check the spelling and capitalization of the application name.
  • Verify the application's supported argument syntax.
  • Use application help from the Asterisk CLI.
  • Confirm that the module providing the application is installed and loaded.

An External Caller Reaches a Restricted Route

  • Assign external callers to a restricted context.
  • Keep public and internal routes in separate contexts.
  • Review broad patterns such as _2XX and test which dialed values they accept.
  • Do not place privileged or expensive routes in a context accessible to untrusted callers.

Exam-Relevant Summary

  • An Asterisk extension is a named sequence of dialplan instructions, not necessarily a physical phone.
  • A context groups extensions and limits which destinations a channel can access.
  • Extension matching occurs within the channel's current context.
  • An extension declaration follows the structure exten => name,priority,Application(arguments).
  • Priorities define execution order; lower numbers run first.
  • n means the next sequential priority.
  • An application performs the action at a priority, and its arguments control that action.
  • Applications can continue, branch, route, transfer, or terminate call processing.
  • Pattern extensions match classes of dialed values and require careful security review.
  • After editing /etc/asterisk/extensions.conf, reload and verify the loaded dialplan.

For a concise reference, see Asterisk dialplan extensions.