What Is an Asterisk Dialplan?

Learn how Asterisk dialplans route calls using contexts, extensions, priorities, and applications, with beginner-friendly examples and troubleshooting steps.

An Asterisk dialplan is the set of executable instructions that controls how Asterisk handles telephone calls. Asterisk is an open-source PBX and communications platform. The dialplan provides its call-processing and call-routing logic.

When a call arrives, a caller dials an internal number, or someone enters a feature code, the dialplan determines what happens next. It can connect the caller to a phone, play an announcement, send a call to voicemail, route a call to a trunk, or end the call.

The dialplan is both configuration and a small scripting language. Asterisk interprets its instructions in order while the call is active.

Where the Dialplan Is Configured

The traditional primary dialplan file is:

/etc/asterisk/extensions.conf

Many installations split the dialplan into additional files and include those files from extensions.conf or another active configuration file. Therefore, editing a file does not necessarily change the running system unless that file is included in the loaded configuration.

After changing dialplan configuration, reload it through the Asterisk command-line interface (CLI):

asterisk -rvvv
dialplan reload

Always confirm that the intended rule is present in the loaded dialplan rather than assuming that a successful file edit took effect.

The Four Core Dialplan Building Blocks

Most introductory dialplan rules can be understood through four components:

Asterisk generally processes a call in this order:

1. The call enters a context.
2. Asterisk matches the dialed value against an extension in that context.
3. Priority 1 begins the matching extension's instruction sequence.
4. Applications run in priority order.

Contexts: Routing Scopes and Security Boundaries

A context is a named section of the dialplan. Its name appears in square brackets:

[local]

Contexts act as routing scopes. They determine which extensions are available to a call. An extension defined in one context is not automatically available to callers placed in another context.

This separation is important for security. An endpoint, trunk, or inbound route should receive a context that exposes only the destinations it needs. For example, an administrator might organize contexts for:

• Local users and internal extensions.
• Inbound calls from a provider.
• Authorized outbound dialing.
• Special services such as voicemail or feature codes.

Endpoint registration and inbound or trunk configuration determine which context a call enters. Context assignment therefore controls which numbers and services a caller can reach. A context that exposes unrestricted outbound routes to an untrusted source can create a toll-fraud risk.

Extensions: Dialed Identifiers and Matching Rules

An extension is a dialed identifier or matching rule that starts a call-flow path. It does not necessarily represent a physical phone. For example, 100 can be a dialplan extension that instructs Asterisk to call a device associated with Alice, but the dialplan extension and the device are separate concepts.

The usual declaration form is:

exten => extension,priority,application(arguments)

Explicit numeric extensions are easy to read:

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

Asterisk also supports pattern extensions, which match groups of possible dialed values. Patterns are useful for outbound dialing and larger numbering plans, but begin with explicit extensions until the basic call flow is clear.

Priorities and Sequential Execution

A single extension can contain several ordered actions. Priority 1 is normally the starting step. Later priorities run in sequence unless an application changes the call's control flow or ends the call.

This two-step example answers a call, plays a sound, and then hangs up:

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

The same keyword repeats the preceding extension. The n priority means “next priority,” allowing Asterisk to assign the next sequential number automatically. The equivalent explicit priorities would be 1, 2, and 3.

Applications and Actions

An application is a callable Asterisk action used in a dialplan step. The application appears in the final position of an extension line, followed by optional arguments:

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

Here, Dial is the application and SIP/alice is its argument. Dial asks Asterisk to place a call to a target channel or endpoint. If the target answers, Asterisk bridges the caller's call leg and the destination's call leg.

Other common beginner applications include:

• Answer() answers the call.
• Playback() plays an audio prompt.
• Hangup() ends the call.
• VoiceMail() sends a call to voicemail.
• Goto() transfers execution to another context, extension, or priority.

Reading a Basic Dialplan Entry

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

SIP/alice is a historical-style SIP target. Current Asterisk systems commonly use the PJSIP stack and write the target as:

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

The exact target must match the channel technology and endpoint configuration in use. A dialplan extension named 100 does not automatically mean that the endpoint is also named 100; the two names may correspond, but they are not the same concept.

How Asterisk Processes a Dialed Call

This model applies to both internal calls and inbound calls. The main difference is how the call enters the system and which context is assigned to it.

Local and Inbound Contexts

Separating contexts makes permissions easier to understand. A local-user context can contain internal destinations, while an inbound context can expose only the destinations intended for callers from a provider.

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

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

In this simplified example, a caller entering local can use extensions 100 and 101. A caller entering inbound sees only extension 200. The actual context assignments belong in endpoint and trunk configuration, not merely in the dialplan text.

Related Concepts That Should Not Be Confused

SIP is the Session Initiation Protocol used by many VoIP devices and by legacy Asterisk channel configurations. PJSIP is a common modern SIP stack and endpoint configuration framework in Asterisk. The channel prefix in Dial() must match the technology used by the deployment.

Safe Introductory Administration Practices

• Test changes with a non-production extension whenever possible.
• Keep local, inbound, and outbound routing in purpose-specific contexts.
• Reload the dialplan after editing and inspect the loaded result through the CLI.
• Check the exact context, extension number, channel technology, and endpoint identifier.
• Review permissions from each endpoint and trunk type to ensure callers cannot reach unintended destinations.

Useful CLI commands include:

asterisk -rvvv
dialplan reload
dialplan show local

dialplan show local displays the loaded rules for the local context. This is often more useful than inspecting a file because it confirms what Asterisk currently knows.

Troubleshooting Basic Dialplan Problems

Invalid extension or no route

If a caller receives an invalid-extension or no-route result, the dialed extension may not exist in the context entered by the call. The endpoint or trunk may also have the wrong context, or the configured number may differ from the number being dialed.

• Identify the call's entering context.
• Run dialplan show for that context.
• Confirm that the expected extension is loaded.
• Check the endpoint or trunk context assignment.

The extension matches, but the device does not ring

This usually means the dialplan rule was found but the Dial() target could not be reached. The endpoint may be unavailable or unregistered, the technology prefix may be wrong, or the endpoint name may not match the configuration.

• Verify endpoint status in the Asterisk CLI.
• Check the exact identifier inside Dial().
• Confirm whether the system uses SIP/ or PJSIP/.

An edit has no effect

The edited file may not be included, the dialplan may not have been reloaded, or a syntax problem may have prevented the rule from loading.

• Run dialplan reload and review CLI output.
• Use dialplan show local to verify the active rule.
• Check include statements and the actual configuration path.

A caller reaches restricted destinations

Review context assignments first. The caller may have been placed in an overly permissive context, or internal, inbound, and outbound rules may have been combined without adequate separation.

• List the extensions reachable from the caller's context.
• Separate user classes and call sources into appropriate contexts.
• Test permissions from each endpoint and trunk type.

Summary

An Asterisk dialplan is the interpreted call-routing logic that tells Asterisk what to do with calls. A context provides the routing scope, an extension selects a call-flow path, a priority orders its instructions, and an application performs each action. A basic rule such as Dial(PJSIP/alice) connects a matched dialplan extension to a configured endpoint, provided that the caller entered the correct context and the endpoint is available.

For the next step, review Asterisk dialplan fundamentals alongside endpoint, trunk, and inbound-route configuration.