The Ultimate Asterisk Dialplan Tutorial:If you are building a VoIP server using Asterisk, the most important thing you must master is the Dialplan.
This guide covers:
- Dialplan basics
- All major dialplan applications
- IVR creation
- Queue setup
- Voicemail
- Call recording
- Pattern matching
- Conditional routing
- AGI integration
- Conference bridge
- Real production office example
Everything in one place.
1️⃣ What is Asterisk Dialplan?
The Dialplan is the logic engine of Asterisk.
It tells the system:
- When a call comes
- Where to send it
- What sound to play
- Whether to record
- Whether to send to queue
- Whether to send to voicemail
- Whether to transfer externally
Dialplan file location:
/etc/asterisk/extensions.conf
2️⃣ Dialplan Basic Structure
[context-name]
exten => extension,priority,Application(arguments)
Example:
[internal]
exten => 1001,1,Answer()
same => n,Playback(hello-world)
same => n,Hangup()
Explanation
- Context → Call entry group
- Extension → Dialed number
- Priority → Execution order
- Application → Function executed
3️⃣ Most Important Dialplan Applications
Below are production-level examples.
🔹 Answer()
Answers incoming call.
exten => 2000,1,Answer()
🔹 Hangup()
Ends call.
same => n,Hangup()
🔹 Playback()
Plays audio file from:
/var/lib/asterisk/sounds/
same => n,Playback(welcome)
🔹 Dial() – Call Another Extension
exten => 1002,1,Dial(PJSIP/1002,20)
Rings extension 1002 for 20 seconds.
🔹 Dial External Number via Trunk
exten => _9X.,1,Dial(PJSIP/${EXTEN:1}@mytrunk)
Removes 9 before dialing outside.
🔹 Voicemail()
exten => 1001,n,Voicemail(1001@default)
🔹 Record()
exten => 700,1,Answer()
same => n,Record(test.wav,5,30)
same => n,Hangup()
🔹 MixMonitor() – Full Call Recording
exten => _X.,1,MixMonitor(${UNIQUEID}.wav)
same => n,Dial(PJSIP/${EXTEN})
🔹 Goto()
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()
4️⃣ Pattern Matching (Important for Production)
| Pattern | Meaning |
|---|---|
| _X. | Any number |
| _9X. | Starts with 9 |
| _NXX | 3 digit number |
| _1XXX | 4 digit starting with 1 |
Example:
exten => _1XXX,1,Dial(PJSIP/${EXTEN})
5️⃣ Create IVR (Interactive Voice Response)
IVR Example:
[ivr-menu]exten => s,1,Answer()
same => n,Playback(welcome)
same => n,Background(press-1-or-2)
same => n,WaitExten(5)exten => 1,1,Goto(internal,1001,1)
exten => 2,1,Goto(internal,1002,1)
exten => t,1,Playback(vm-goodbye)
same => n,Hangup()
6️⃣ Queue Configuration (Call Center)
In extensions.conf:
exten => 5000,1,Queue(support)
In queues.conf:
[support]
strategy=ringall
timeout=15
member => PJSIP/1001
member => PJSIP/1002
7️⃣ Conference Bridge
exten => 9000,1,Answer()
same => n,ConfBridge(9000)
8️⃣ AGI (Advanced Control with PHP/Python)
AGI allows external scripting.
exten => 7000,1,AGI(test.php)
You can build CRM integration, billing, API calls.
9️⃣ Business Hours Routing
exten => 6000,1,GotoIfTime(09:00-18:00,mon-fri,*,*?open,1)
same => n,Goto(closed,1)exten => open,1,Dial(PJSIP/1001)exten => closed,1,Playback(closed)
same => n,Hangup()
🔟 Complete Real Office Example (Production Ready)
[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 => 5000,1,Queue(support)exten => 9000,1,ConfBridge(9000)exten => _9X.,1,MixMonitor(${UNIQUEID}.wav)
same => n,Dial(PJSIP/${EXTEN:1}@mytrunk)
same => n,Hangup()
1️⃣1️⃣ Debugging & CLI Commands
Enter CLI:
asterisk -rvvv
Useful commands:
dialplan reload
dialplan show
core show applications
core show function
1️⃣2️⃣ Best Production Practices
✔ Always separate contexts (internal, external, ivr)
✔ Use pattern matching carefully
✔ Enable call recording if required
✔ Secure your trunks
✔ Always reload dialplan after changes
