Asterisk course

What Is an Asterisk Dialplan?

Learn how Asterisk dialplans use contexts, extensions, priorities, and applications to control inbound and outbound call routing.

An Asterisk dialplan is the collection of rules that controls how Asterisk processes and routes calls. It tells Asterisk what to do when a call arrives, when a user dials an internal number, or when someone enters a feature code or external destination.

The dialplan handles both inbound call handling and outbound call routing. For example, it can send an incoming trunk call to an automated attendant, connect an internal user to another phone, or select a trunk for an external number.

A dialplan resembles a small scripting language, but it is primarily a configuration-based call-processing language rather than a traditional general-purpose programming language. Its statements select actions and control call flow.

Where Asterisk Dialplan Rules Are Stored

The conventional file for dialplan rules is /etc/asterisk/extensions.conf. Many installations keep simple rules there, while larger systems split rules across included configuration files. PBX management software may also generate dialplan sections instead of having an administrator edit every rule directly.

After changing a dialplan file, load the changes into Asterisk. From the Asterisk CLI, the usual command is:

dialplan reload

Use a controlled change process on production systems: save a backup, make a small change, reload at an appropriate time, and test both permitted and restricted call paths.

The Four Main Dialplan Building Blocks

Most introductory dialplan rules can be understood through four related concepts:

• Context: a named section that groups rules and defines a caller's routing boundary.
• Extension: a dialable value or matching rule within a context.
• Priority: one ordered step in the handling sequence for an extension.
• Application: the action Asterisk performs at that step.

The standard extension declaration has this form:

exten => extension,priority,application(arguments)

The commas and the ordering are structurally significant. Spaces may be added to improve readability, but they do not replace the required commas. The word exten is the extension declaration keyword; it is not the extension number itself.

Contexts: The Dialplan's Routing Boundaries

A context is a named section of dialplan rules. Its name appears in square brackets, such as [local]. Contexts group extensions and determine which destinations are available to a channel.

A channel is a call leg or communication path handled by Asterisk. When a channel enters the dialplan, it enters an assigned context. An inbound trunk, a registered phone, and another local call can each be assigned different starting contexts.

Context isolation means that an extension in one context is not automatically available to a caller in another context. Routing between contexts must be deliberately provided, commonly through controlled includes or applications such as Goto().

This makes contexts a core permissions and security mechanism. For example, internal phones may be allowed to call other internal extensions, while a restricted device may be prevented from reaching outbound rules. Assigning an untrusted caller to a context with unrestricted external dialing can create a serious toll-fraud risk.

For a related explanation of this boundary concept, see Asterisk contexts.

Extensions: What A Caller Can Match

An extension is a dialable identifier or matching rule inside a context. It may represent a phone, voicemail box, menu choice, queue, feature code, or outbound route.

In Asterisk, the word extension does not necessarily mean a physical telephone extension. A value such as 100 can identify a user, but it can also start an announcement, send a caller to voicemail, or perform another action.

A literal extension matches one value:

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

A pattern extension matches a range or format of dialed numbers instead of one literal value. Pattern extensions begin with an underscore, for example:

exten => _X.,1,Dial(PJSIP/trunk/${EXTEN})

Pattern syntax has additional rules and should be designed carefully, particularly for outbound permissions. The important introductory distinction is that 100 is literal, while an underscore-prefixed value describes a matching rule.

See Asterisk extensions for a focused discussion of extension matching.

Priorities and Sequential Execution

A priority is one ordered execution step for an extension. Multiple priorities form a call-flow sequence. Asterisk normally executes the priorities for the matching extension in order unless an application redirects the call, ends it, or otherwise changes control flow.

The first step commonly uses numeric priority 1. Later steps may use 2, 3, and so on. The commonly used n notation means “the next sequential priority,” which makes it easier to insert or reorder steps:

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

Here, the call is answered first, the hello-world sound is played next, and the call is then ended. An extension with only one application has only one priority, such as priority 1 in a single-line Dial() rule.

Read more about dialplan priorities when you begin using branching and more complex call flows.

Applications and Arguments

An application is a built-in dialplan action performed at a priority. Application arguments are values inside parentheses that tell the application how to operate.

• Answer() answers a call.
• Dial() attempts to call one or more destinations or endpoints.
• Playback() plays a sound file.
• VoiceMail() sends a caller to voicemail handling.
• Hangup() ends a call.
• Goto() transfers execution to another location in the dialplan.

Application behavior, available arguments, and destination syntax depend on the Asterisk version, installed modules, and channel technology. Consult the documentation for the specific application and installation before relying on advanced options. The Dial application and Answer application are useful next topics.

A Minimal Dialplan Example

The smallest useful internal calling example is:

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

Call flow for this example:

1. A caller's channel enters the local context.
2. The caller dials 100.
3. Asterisk matches extension 100.
4. Priority 1 runs the Dial() application.
5. Asterisk attempts to call the configured endpoint named alice.

Successful dialplan matching does not guarantee a successful call. The endpoint must exist in Asterisk's configuration and be registered, reachable, or otherwise available through its channel technology.

SIP and PJSIP Destination Notation

The destination passed to Dial() includes a channel technology prefix. Older systems using the chan_sip driver commonly use SIP/alice. Current deployments commonly use the chan_pjsip driver and PJSIP/alice.

Both examples use the same dialplan concepts. The exact destination syntax depends on the active channel driver and endpoint configuration. Do not assume that a SIP/ destination works on a system configured only with PJSIP.

How Asterisk Processes a Call

At a high level, call routing follows this sequence:

1. A channel enters an assigned context.
2. Asterisk compares the dialed value with literal extensions and pattern extensions in that context.
3. When a rule matches, Asterisk begins at its first priority.
4. Each application performs an action using its arguments.
5. The call continues to the next priority, is redirected, reaches another destination, or ends.

An inbound trunk starts in a context assigned to that trunk. A registered endpoint starts in the context assigned to that endpoint. Local users may share an internal context or be separated into contexts according to organizational permissions.

As a result, outbound permissions and destination availability are consequences of dialplan design. A caller can reach only what the starting context and its deliberate routing provide.

Context Separation Example

Two contexts can expose the same internal extension while having different permissions:

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

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

Both contexts can allow a caller to reach extension 100. The restricted context should not automatically contain external dialing rules. If external routing is later added, place it only in contexts assigned to callers who are authorized to use it, and review any deliberate routes between contexts.

Safe Introductory Administration

• Use descriptive context names such as [internal], [restricted], or [from-trunk].
• Add comments explaining unusual routing decisions and permission boundaries.
• Put test extensions in a limited context before making them available to production callers.
• Check the resulting active dialplan after edits, not just the text file.
• Never assign untrusted or restricted callers to a context that permits unrestricted external dialing.

Useful Asterisk CLI commands include:

dialplan show
dialplan show local

dialplan show displays loaded dialplan entries, while dialplan show local displays the loaded entries for one context. These commands help confirm that a change was parsed and loaded.

Troubleshooting Common Dialplan Problems

Extension 100 does not match

• The channel may have entered a different context from the one containing extension 100.
• The rule may not have loaded because of a syntax error or because the dialplan was not reloaded.
• The dialed digits may not match the literal extension or any pattern.

Run dialplan show, verify the context assigned to the trunk or endpoint, and review CLI output during a test call.

The rule matches, but Dial cannot reach alice

• The endpoint name may not match the configured endpoint.
• The endpoint may be unregistered or unavailable.
• The channel prefix may be wrong, such as using SIP/ where the deployment uses PJSIP/.

Confirm the endpoint configuration and registration status, check the channel technology, and inspect CLI call output for the reason reported by Dial().

A restricted user can place unauthorized calls

• The endpoint or trunk may be assigned to an overly permissive context.
• A context may include or route to outbound rules unintentionally.
• Rules may have been copied into a restricted context without reviewing their access implications.

Review the assigned context, list its available extensions, and test internal, emergency, and external dial strings according to organizational policy.

Only the first action runs

• Priorities may be missing, out of order, or incorrectly written.
• An earlier application may transfer control, terminate the call, or fail.
• An application may require arguments that were omitted or malformed.

Read the priorities in execution order, increase CLI verbosity during a test call, and check the documentation for each application's expected arguments and return behavior.

Key Takeaways

• The dialplan is Asterisk's call-processing logic for inbound, internal, and outbound calls.
• Rules are conventionally stored in /etc/asterisk/extensions.conf, although installations may use included or generated files.
• A context groups rules and limits what a channel can access.
• An extension is a dialable value or matching rule, not necessarily a physical phone.
• Priorities order the steps for a matching extension.
• Applications perform the actions, and arguments control those actions.
• Dial() can call configured endpoints through technologies such as PJSIP or legacy SIP.
• Always verify context assignments, endpoint configuration, loaded rules, and outbound permissions before deploying changes.