If you’re working with VoIP and PBX systems, understanding the dialplan in Asterisk is essential. The dialplan controls how calls are handled, routed, recorded, and processed.
In this complete tutorial, you’ll learn:
- What is a dialplan
- Dialplan syntax
- Most important dialplan applications
- Real working examples
- Advanced call routing techniques
What is Asterisk Dialplan?
The Dialplan is a set of instructions that tells Asterisk what to do when a call is received.
It is configured inside:
/etc/asterisk/extensions.conf
Every call entering Asterisk goes to a context, then to an extension, and executes applications step by step.
Basic Dialplan Structure
[context-name]
exten => extension,priority,Application(arguments)
Example:
[internal]
exten => 1001,1,Answer()
same => n,Playback(hello-world)
same => n,Hangup()
Explanation
- internal → Context
- 1001 → Extension number
- 1 → Priority
- Answer() → Application
- same => n → Next step
Most Important Dialplan Applications (With Examples)
1️⃣ Answer()
Answers an incoming call.
exten => 1000,1,Answer()
2️⃣ Hangup()
Ends the call.
exten => 1000,n,Hangup()
3️⃣ Playback()
Plays a sound file from:
/var/lib/asterisk/sounds/
exten => 1000,n,Playback(hello-world)
4️⃣ Dial()
Used to call another extension or trunk.
exten => 2000,1,Dial(PJSIP/1001,20)
This will ring extension 1001 for 20 seconds.
5️⃣ Echo()
Used for testing audio.
exten => 600,1,Answer()
same => n,Echo()
6️⃣ Voicemail()
Send caller to voicemail.
exten => 1001,n,Voicemail(1001@default)
7️⃣ Record()
Record call audio.
exten => 700,1,Answer()
same => n,Record(test.wav,5,30)
same => n,Hangup()
8️⃣ MixMonitor()
Record full conversation.
exten => _X.,1,MixMonitor(${UNIQUEID}.wav)
same => n,Dial(PJSIP/${EXTEN})
9️⃣ Goto()
Jump to another extension or context.
exten => 500,1,Goto(internal,1001,1)
🔟 GotoIf()
Conditional routing.
exten => 800,1,Set(TIME=${STRFTIME(${EPOCH},,%H)})
same => n,GotoIf($[${TIME} > 17]?closed,1)
same => n,Playback(open)
same => n,Hangup()exten => closed,1,Playback(closed)
same => n,Hangup()
Pattern Matching in Dialplan
| Pattern | Meaning |
|---|---|
| _X. | Any number |
| _9X. | Numbers starting with 9 |
| _NXX | 3-digit number |
Example:
exten => _9X.,1,Dial(PJSIP/${EXTEN:1})
Removes 9 before dialing.
Real Office Example (Complete Flow)
[internal]exten => 1001,1,Dial(PJSIP/1001,20)
same => n,Voicemail(1001@default)
same => n,Hangup()exten => 1002,1,Dial(PJSIP/1002,20)
same => n,Voicemail(1002@default)
same => n,Hangup()exten => _9X.,1,Dial(PJSIP/${EXTEN:1}@mytrunk)
same => n,Hangup()
Advanced Applications
Queue()
Send call to call center queue.
exten => 5000,1,Queue(support)
ConfBridge()
Create conference room.
exten => 9000,1,Answer()
same => n,ConfBridge(9000)
AGI()
Run external script (PHP / Python).
exten => 7000,1,AGI(test.php)
Useful CLI Commands
asterisk -rvvv
dialplan reload
dialplan show
core show applications
To list all applications:
core show applications
