Asterisk Dialplan Contexts: Isolation, Call Entry Points, and Security
Learn how Asterisk contexts connect channels to dialplan logic, isolate call flows, define classes of service, and protect internal destinations.
An Asterisk context is a named section of the dialplan. It defines the extension space and call-routing logic available to a channel when a call enters Asterisk.
The dialplan is the collection of Asterisk call-processing rules that determines what happens when a call reaches an extension. An extension is a dialable destination or pattern with one or more ordered processing steps, called priorities. A channel is an active call leg or communication path associated with a phone, trunk, endpoint, or application.
Contexts are therefore more than labels used to organize a large configuration. They are deliberate boundaries that control which dialplan logic a call can initially reach.
What a Context Does
A context contains extensions and the priorities associated with those extensions. When a call arrives through a channel, Asterisk begins dialplan execution in the context assigned to that channel.
[from-internal]
exten => 200,1,Answer()
exten => 200,n,Playback(demo-thanks)
exten => 200,n,Hangup()In this example, from-internal is the context, 200 is the extension, and the numbered lines are its ordered priorities. The call answers, plays audio, and then hangs up.
The traditional dialplan file is extensions.conf, normally located at /etc/asterisk/extensions.conf. A context is declared with a bracketed section name such as [from-internal].
Contexts and Isolation
Extensions in one context are not normally reachable from another context. If extension 200 exists in from-internal but not in from-carrier, a call currently executing in from-carrier cannot normally dial 200 just because that extension exists elsewhere.
This isolation is a dialplan boundary, not merely an organizational convention. A context limits the extension space searched for the current call. Moving between contexts must be explicitly designed, usually with a controlled dialplan application such as Goto().
The same extension can exist in multiple contexts and perform different actions. A trusted internal caller might reach extension 200 as an employee phone, while an inbound caller might reach a different 200 definition, or receive an invalid-extension response if no matching definition exists in the inbound context.
Context, Extension, and Channel Relationship
| Component | What it represents | How it affects call routing |
| Channel | An active call leg connected to a device, trunk, or application. | Provides the call's entry point and carries its current dialplan location. |
| Channel configuration | Driver-specific settings for an endpoint, peer, trunk, or other source. | Selects the initial context in which the call starts processing. |
| Context | A named section of the dialplan. | Limits the extensions and call-processing logic initially available to the channel. |
| Extension | A number, name, or pattern inside a context. | Identifies the dialplan branch to execute. |
| Priority | An ordered step within an extension. | Determines the sequence of applications executed for that extension. |
Channel-to-Dialplan Entry Points
Channel configuration selects the context in which calls from a particular channel begin. The exact setting depends on the channel technology and Asterisk version, but a common form is:
context=from-internalFor example, a PJSIP endpoint, legacy SIP peer, or another channel-driver object may have a context setting. When a call arrives from that source, Asterisk uses the configured value to determine which context is searched first.
The setting does not mean that the channel can automatically use every context. It identifies the initial dialplan location. Any later transition must come from an intentional dialplan path or another controlled mechanism.
Security Boundaries
Contexts help prevent untrusted callers from reaching internal extensions, long-distance routes, administrative features, or other privileged dialplan functions. An external carrier call should normally enter a context that handles only published numbers, menus, queues, reception, or other intended inbound services.
External channels should not normally share the same permissive context as trusted internal phones. If an inbound trunk, public-facing SIP endpoint, or other untrusted source is assigned to from-internal, it may gain access to internal extension patterns and outbound routes defined there.
Possible consequences include unauthorized internal calls, toll fraud, exposure of administrative features, unintended access to voicemail or call-control functions, and disclosure of internal routing behavior. Contexts reduce this risk by narrowing the call's initial extension space, but patterns and explicit transfers must also be reviewed.
| Call source | Assigned context | Trust level | Permitted destinations | Security purpose |
| Carrier-originated inbound call | from-carrier | Untrusted | Published numbers, menus, queues, and reception | Prevents direct access to internal dialing and privileged routes. |
| Employee phone | from-internal | Trusted, subject to policy | Internal extensions and approved outbound destinations | Provides normal employee calling service. |
| Lobby phone | restricted-phone | Restricted | Emergency, reception, and local destinations | Limits capabilities on a shared or exposed device. |
| Authorized staff phone | from-privileged | Privileged | Broader approved destination classes | Separates exceptional permissions from ordinary users. |
| Service account or application | service-account | Application-specific | Only the extensions required by the service | Limits automation and application call paths. |
Classes of Service
A class of service is the set of destinations and calling capabilities granted to a user or call source. Separate contexts can implement different classes of service, such as:
- Local-only users: may call local destinations but not broad outbound routes.
- Internal users: may call employee extensions and approved external destinations.
- Unrestricted users: may reach additional destination classes when business policy authorizes it.
- Inbound callers: may use published menus, queues, or reception routes without internal dialing access.
- Service accounts: may access only the narrow branches needed by an application.
This design is different from relying solely on device identity. A phone's endpoint name or caller identity is useful for assigning policy, but the context determines which dialplan logic is available after the channel enters Asterisk. A secure design combines correct endpoint or trunk configuration with narrow contexts and carefully reviewed patterns.
Separate Inbound and Internal Call Sources
A common design places carrier calls and employee calls in different contexts:
[from-carrier]
exten => 18005550100,1,Goto(incoming-menu,s,1)
[incoming-menu]
exten => s,1,Answer()
exten => s,n,Playback(custom/welcome)
exten => s,n,Hangup()Here, a call arriving from the carrier can use the published number and move to a dedicated menu. It does not gain access to internal extension definitions merely because those definitions exist in another context.
Employee phones can enter a separate context:
[from-internal]
exten => 200,1,Dial(PJSIP/200)
exten => 201,1,Dial(PJSIP/201)For a complete automated menu, see Create An Automated Attendant. For queue-based inbound routing, see Defining The Queues.
Context Names and Reserved Sections
Ordinary context names should use letters, digits, hyphens, and underscores. Descriptive names should identify the call source or trust level.
| Name | Valid syntax | Appropriate use | Reason |
from-internal | Valid | Trusted internal phones | Clearly describes the source. |
from-carrier | Valid | External carrier calls | Communicates an untrusted inbound boundary. |
restricted_phone | Valid | Lobby or restricted devices | Uses an allowed underscore and describes policy. |
staff2 | Valid | A narrowly defined staff class | Uses letters and digits. |
public callers | Avoid | Not recommended | Contains a space and is less consistent for configuration. |
from.internal | Avoid | Not recommended | Uses punctuation outside the ordinary naming categories. |
Some dialplan sections have special purposes and should not be reused as ordinary call-routing contexts. The general configuration section is [general], the default behavior section is [default], and the global-variable section is [globals]. Treat these names according to their special roles rather than using them for endpoint classes.
Explicit Cross-Context Routing with Goto
The Goto() application intentionally redirects dialplan execution to a specified context, extension, and priority. It is useful when a restricted call needs one narrowly defined route into another context.
[restricted-phone]
exten => 0,1,Goto(reception,200,1)
[reception]
exten => 200,1,Dial(PJSIP/200)This branch allows the restricted phone to reach reception through one explicit destination. It does not automatically grant access to every extension in reception.
Cross-context routing should be narrowly controlled and reviewed for authorization implications. An intentional transfer to one approved destination is different from accidental exposure caused by assigning an external trunk to a permissive internal context. Review every Goto() destination, especially when the source can be reached by an external caller.
See The Goto Application for more detail about intentional dialplan transfers.
Same Number, Different Behavior
The current context determines which definition of an extension is considered. For example:
[from-internal]
exten => 500,1,Dial(PJSIP/500)
[from-carrier]
exten => 500,1,Playback(custom/public-service)
exten => 500,n,Hangup()An internal caller dialing 500 reaches the employee device, while a carrier caller dialing 500 reaches the public service. If 500 is absent from the carrier context, the inbound caller receives an invalid-extension result instead.
Configuration and Design Checklist
- List every channel source: internal endpoints, external trunks, gateways, applications, and service accounts.
- Assign each source a context based on its trust level and required call flows.
- Keep inbound contexts limited to published destinations and required services.
- Use separate contexts for restricted, standard, and privileged classes of service.
- Review wildcard patterns because a broad pattern can undermine an otherwise sensible boundary.
- Review every
Goto()and other cross-context route for authorization. - Use descriptive names such as
from-internal,from-carrier, andrestricted-phone. - Reload or otherwise apply dialplan changes according to the deployment method after editing the configuration.
Troubleshooting Context Problems
Invalid Extension Even Though the Number Exists
- The extension may be defined in a different context.
- The channel may be assigned to an unintended context.
- The expected number or pattern may be absent from the inbound context.
Identify the channel's current context in call logs or the Asterisk CLI. Then verify the endpoint, peer, trunk, or channel configuration and confirm that the target extension is defined in the context actually entered by the call.
External Callers Can Reach Restricted Destinations
- An inbound trunk or endpoint may be assigned to an internal context.
- The inbound context may contain overly broad patterns.
- A
Goto()path may expose a privileged context without validation.
Review the context assigned to every external source, inspect wildcard patterns and cross-context routes, and reduce inbound access to only the required public call flows.
A Context Appears to Be Ignored
- The dialplan file may have been edited without being reloaded.
- A different dialplan configuration source may be active.
- A reserved section name may have been used incorrectly.
- The channel configuration may point to a differently named context.
Confirm that the active dialplan contains the intended context. Check spelling, case, and punctuation in both the dialplan and channel configuration, then reload or apply the changes using the procedure appropriate to the deployment.
A Context Name Causes Unexpected Behavior
Check for unsupported characters, a collision with a special-purpose section, or a mismatch between the name in extensions.conf and the channel configuration. Ordinary names should use letters, digits, hyphens, and underscores consistently.
Exam-Relevant Notes
- A context is a named section of the Asterisk dialplan.
- A channel enters the dialplan through the context selected by its channel configuration.
- Extensions in separate contexts are isolated unless a deliberate route crosses the boundary.
- The same extension can have different behavior in different contexts.
- Contexts are useful security boundaries and classes-of-service mechanisms.
- External channels should not normally enter a permissive internal context.
Goto()provides an intentional context, extension, and priority transition.extensions.conftraditionally contains contexts and extension logic, usually under/etc/asterisk/.[general],[default], and[globals]are special-purpose sections, not ordinary endpoint contexts.
Summary
A context determines where a channel begins processing the Asterisk dialplan and which extensions it can initially access. By separating carrier calls, internal users, restricted devices, privileged users, and service accounts, administrators can create clear call-flow boundaries and enforce different classes of service.
Use explicit cross-context routing only when it is required and authorized. Correct context assignment, narrow extension patterns, careful Goto() paths, and regular configuration review are central to a secure Asterisk dialplan.