Key Takeaways
- An Asterisk dialplan issue is one of the most frequent causes of dropped calls, routing failures, and unreachable extensions in contact center environments.
- The dialplan lives in /etc/asterisk/extensions.conf and controls every call routing decision Asterisk makes.
- Most errors stem from incorrect context names, missing priorities, syntax mistakes, or improperly loaded modules.
- The verbose command in the Asterisk CLI is your first diagnostic tool, it shows real-time call flow and pinpoints exactly where execution fails.
- Systematic testing using dialplan show, core reload, and log analysis resolves the majority of dialplan faults without downtime.
An Asterisk dialplan issue can silently cripple an entire contact center operation, calls drop mid-route, extensions become unreachable, and agents sit idle without a single ring. Asterisk’s dialplan is the central routing engine for every inbound and outbound call, and when it breaks, the consequences are immediate and measurable.
This guide walks through what the dialplan is, why it fails, and exactly how to diagnose and fix the most common errors encountered in production environments.
What Is the Dial Plan in Asterisk?
The dialplan in Asterisk is the core call-routing logic that instructs the system what to do with every call, whether it arrives from a SIP trunk, an internal extension, or an outbound dialer campaign. It is defined primarily in /etc/asterisk/extensions.conf, though it can also be loaded from a database via Asterisk Realtime Architecture (ARA) or through external scripts using AGI (Asterisk Gateway Interface).
The dialplan is structured around three fundamental components:
Contexts
A context is a named block inside extensions.conf that groups related routing rules together. Calls enter a context when they arrive, and routing decisions execute within that context. Incorrect context assignment is one of the most frequent sources of an Asterisk dialplan issue; if an incoming call is directed to a context that doesn’t exist, it simply fails.
[inbound-sales]
exten => _NXXNXXXXXX,1,Answer()
exten => _NXXNXXXXXX,n,Queue(sales_queue)
exten => _NXXNXXXXXX,n,Hangup()Extensions
An extension is a pattern (a specific number or a wildcard like _NXXNXXXXXX) that matches an incoming dialed number. When a caller dials a number, Asterisk scans the active context for a matching extension and begins executing its instructions.
Priorities
Priorities are the sequential steps within an extension. They run top-to-bottom. Using n as a priority means “next in sequence,” which is standard practice and less error-prone than manually numbering each step.
The combination of context + extension + priority forms what Asterisk calls a dialplan entry point, and a fault at any level of this hierarchy will cause a routing failure.
What Is an Asterisk Dialer?
An Asterisk dialer is an automated outbound or inbound calling system built on top of the open-source Asterisk telephony framework. In contact center deployments, the Asterisk dialer uses the dialplan to manage how calls are initiated, routed to agents, handled on no-answer, and disposed of after the conversation ends.
Asterisk itself is the underlying engine. What most enterprise contact centers deploy is a management layer on top of it, such as VICIdial, which extends Asterisk’s raw capabilities with a web-based agent interface, campaign management, lead list handling, real-time reporting, and dialer-mode controls (predictive, preview, progressive, and manual).
When an Asterisk dialer encounters a dialplan issue, the entire outbound campaign can stall. Calls may originate but fail to connect agents, or they may complete the customer-side pickup but fail to bridge the agent leg, resulting in dead air, one of the most damaging experiences in any outbound operation.
What Does It Mean When You Get a Call from Asterisk?
When someone receives a call that appears to originate “from Asterisk,” it typically means the call was placed by an Asterisk-based telephony system without a properly configured Caller ID (CID). By default, if no CallerID is set in the dialplan or the trunk configuration, Asterisk may present the system’s hostname or the literal string “Asterisk” as the caller name.
In a contact center context, this is often a configuration oversight, specifically, a missing or malformed Set(CALLERID(…)) application in the dialplan.
Here is what the fix looks like:
exten => _NXXNXXXXXX,1,Set(CALLERID(name)=DialerKing Support)
exten => _NXXNXXXXXX,n,Set(CALLERID(num)=18005551234)
exten => _NXXNXXXXXX,n,Dial(SIP/trunk/${EXTEN})Beyond caller ID misconfiguration, receiving a call labeled “Asterisk” can also indicate a test call originating from an internal system, a misconfigured SIP peer, or an automated notification triggered by a monitoring script.
In either case, the root cause is always in the dialplan or trunk configuration, and it is fully correctable.
What Is Verbose in Asterisk Dialplan?
The verbose command in Asterisk is a diagnostic output mechanism that displays real-time call processing events directly in the Asterisk CLI (Command Line Interface). It is the single most useful tool for diagnosing any Asterisk dialplan issue.
Enabling Verbose Mode
From the Asterisk CLI, run:
asterisk -rvvvvvEach v increases the verbosity level. A level of 3–5 (-rvvv to -rvvvvv) is typically sufficient for dialplan debugging. At these levels, you will see:
- Which context a call enters
- Which extension pattern is matched (or why it fails to match)
- Each application executed at every priority step
- Any error messages, such as “Unable to find extension” or “No such application”
- Channel variable values as they are set and evaluated
Reading Verbose Output
Here is a simplified example of what verbose output looks like during a routing failure:
-- Executing [s@inbound-sales:1] Answer("SIP/trunk-00000001", "") in new stack
-- Executing [s@inbound-sales:2] Queue("SIP/trunk-00000001", "sales_queue") in new stack
[ERROR] Unable to find extension 'sales_queue' in context 'inbound-sales'
-- Auto fallthrough, channel 'SIP/trunk-00000001' status is 'UNKNOWN'This output immediately tells you that the queue named sales_queue does not exist or is not loaded – a specific, actionable finding. Without verbose logging, this failure would appear to the outside world as a call that connected and then immediately dropped.
Enabling Persistent Verbose Logging
For persistent log capture (important in production), enable full logging in
/etc/asterisk/logger.conf:
[logfiles]
full => notice,warning,error,debug,verboseThen reload the logger: asterisk -rx “logger reload”
The Most Common Asterisk Dialplan Issues and How to Fix Them
Understanding the anatomy of the dialplan makes troubleshooting significantly faster. The following are the errors encountered most often in contact center deployments.
1. Wrong or Missing Context
Symptom: Calls arrive but immediately disconnect. Verbose shows “No such extension” or “Context not found.”
Cause: The SIP peer, trunk, or AGI script is directing the call to a context name that either doesn’t exist in extensions.conf or has a typo.
For SIP trunks: /etc/asterisk/sip.conf → context=inbound-sales
For PJSIP: /etc/asterisk/pjsip.conf → context=inbound-sales
Confirm the exact same name appears as [inbound-sales] in extensions.conf
grep -n "context=" /etc/asterisk/sip.conf
grep -n "^\[" /etc/asterisk/extensions.confContext names are case-sensitive. Inbound-Sales and inbound-sales are two different contexts.
2. Extension Pattern Mismatch
Symptom: Some calls route correctly; others fail. Verbose shows “Extension X not found in context Y.”
Cause: The dialplan contains patterns that don’t cover the format of numbers actually being dialed. For example, a pattern of _NXXNXXXXXX (10-digit US format) will not match an 11-digit number starting with 1.
; Match 10-digit numbers
exten => _NXXNXXXXXX,1,Goto(inbound-handler,s,1)
; Also match 11-digit numbers with leading 1
exten => _1NXXNXXXXXX,1,Goto(inbound-handler,s,1)Use dialplan show [context] in the CLI to list all active extension patterns and verify coverage:core# dialplan show inbound-sales
3. Priority Gaps and Incorrect Priority Numbers
Symptom: Call execution stops mid-flow, often silently. The caller hears silence or fast busy.
Cause: Manual priority numbering with a gap (e.g., priorities jump from 2 to 4, skipping 3). Asterisk stops execution at the missing step.
; Correct — uses 'n' for auto-sequencing
exten => s,1,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(welcome)
exten => s,n,Queue(support)
exten => s,n,Hangup()4. Missing or Unloaded Modules
Symptom: Verbose shows “No such application: Queue” or “No such application: AGI.”
Cause: The Asterisk module that provides the application is not loaded. Applications like Queue(), AGI(), MixMonitor(), and VoiceMail() each require their respective modules to be loaded at runtime.
# From Asterisk CLI
core show modules like queue
module load app_queue.so
For a permanent fix, ensure the module is listed (and not commented out) in
/etc/asterisk/modules.conf:
load => app_queue.so
load => app_agi.so5. Variable Substitution Failures
Symptom: Calls route to the wrong destination. Queue names, extension numbers, or IVR paths appear literally as ${VARIABLE_NAME} in logs instead of resolving.
Cause: A channel variable was referenced before it was set, or it was set in one context and referenced in another where it is out of scope.
exten => s,1,Set(CAMPAIGN_QUEUE=sales_queue)
exten => s,n,Verbose(1,Routing to queue: ${CAMPAIGN_QUEUE})
exten => s,n,Queue(${CAMPAIGN_QUEUE})The Verbose() application will print the resolved value directly to the CLI output, confirming whether substitution worked.
6. Configuration Not Reloaded After Changes
Symptom: You edited extensions.conf but the behavior hasn’t changed.
Cause: Asterisk reads dialplan configuration at startup or on explicit reload. File edits do not take effect automatically.
# Reload only the dialplan
asterisk -rx "dialplan reload"
# Or reload all configuration
asterisk -rx "core reload"Verify the reload succeeded by checking for any parse errors in the output. Syntax errors in extensions.conf will prevent the new configuration from loading.
Step-by-Step Dialplan Debugging Process
When an Asterisk dialplan issue is reported but the specific cause is unclear, follow this systematic process:
Step 1 — Reproduce the fault with verbose active
Open the Asterisk CLI with asterisk -rvvvvv and trigger the failing call. Capture the full output.
Step 2 — Identify the last successful step
Scroll through the verbose output and find the last application that executed normally. The line immediately after it is where execution stopped.
Step 3 — Check the context and extension
Confirm the context exists in extensions.conf and the extension pattern matches the dialed number.
Step 4 — Validate module availability
Run core show applications and verify every application used in the failing dialplan section is available.
Step 5 — Reload and retest
After making corrections, run dialplan reload and retest the call.
Step 6 — Review
/var/log/asterisk/full For errors that only appear under load (race conditions, resource exhaustion), review the persistent log file rather than relying solely on CLI output.
Real-World Use Case: Routing Failure in a High-Volume Outbound Campaign
A contact center running a large predictive dialing campaign reported that roughly 15% of connected calls were dropping within two seconds of the customer answering. Agents saw the calls appear briefly on their screen and then disconnect.
— Executing [answered@outbound-campaign:1] AGI(“Local/…”,”crm_bridge.php”) in new stack [ERROR] AGI Script crm_bridge.php failed to execute
— Auto fallthrough, channel status is ‘UNKNOWN’
Root Cause: A recent PHP update on the server had changed the binary path. The AGI script crm_bridge.php invoked /usr/bin/php which no longer existed at that path, it had moved to /usr/bin/php8.1.
The drop rate returned to baseline within minutes – no service interruption, no campaign restart required.
This example illustrates a key principle: an Asterisk dialplan issue is not always a dialplan syntax problem. External dependencies called by the dialplan – AGI scripts, database connections, application modules, are equally capable of causing routing failures, and verbose logging is the tool that reveals exactly which layer is at fault.
Frequently Asked Questions
What is an Asterisk dialer❓
An Asterisk dialer is an automated calling system built on the Asterisk open-source telephony engine. It originates or receives calls and routes them through the dialplan to agents, queues, IVR menus, or voicemail systems. In contact center deployments, dialers are typically operated through management platforms like VICIdial, which add campaign control, agent interfaces, and reporting on top of Asterisk’s core routing capabilities.
What does it mean when you get a call from Asterisk❓
A call labeled “Asterisk” or showing “Asterisk” as the caller name typically indicates that the originating system, an Asterisk-based telephony server – has not been configured with proper Caller ID settings. In the dialplan, the Set(CALLERID(name)=…) and Set(CALLERID(num)=…) applications should be used to assign the correct display name and number before the call is created. It can also indicate a test call or a misconfigured SIP peer sending the system’s default identity
What is verbose in Asterisk dialplan❓
Verbose in Asterisk is a logging mode that prints detailed real-time call processing information to the Asterisk CLI or log files. It shows which context a call enters, which extensions and priorities execute, what applications run, and where failures occur. It is enabled by launching the CLI with an asterisk -rvvvvv. The Verbose() application can also be inserted directly into a dialplan to print custom diagnostic messages at specific points in the call flow.
Why does Asterisk say “No such extension” even when the extension exists❓
This usually means the call is entering a different context than where the extension is defined. Verify that the context= setting in sip.conf or pjsip.conf for the incoming peer or trunk matches exactly, character for character, including case, with the context name in extensions.conf. Also confirm that the dialed number format matches the extension pattern. A pattern like _NXXNXXXXXX will not match an 11-digit number. Use dialplan show [context-name] to inspect what patterns are actually loaded.
Conclusion
A well-maintained Asterisk dialplan is the foundation of reliable contact center operations. When an Asterisk dialplan issue surfaces, whether it’s a routing failure, a dropped call, or a mismatched extension, the path to resolution is consistent: enable verbose logging, trace the call through the dialplan step by step, and systematically verify contexts, patterns, modules, and variables.
The majority of dialplan errors are entirely preventable with disciplined configuration practices: use n for priorities, validate context names across all config files, keep modules explicitly loaded, and always reload after changes. For complex deployments running VICIdial or custom AGI integrations, these habits become even more critical as the number of interdependencies grows.
If your team is dealing with persistent dialplan faults, integration failures, or needs expert-level Asterisk configuration support, DialerKing’s engineering team is available to help.
Contact us for a technical consultation tailored to your contact center environment.
