Asterisk Dialplan: Asterisk dialplan intro (Latest Versions)

The Asterisk dialplan is the brain of call routing. It decides what happens when a call arrives: play audio, collect DTMF, ring an agent, send to queue, forward to voicemail, or trigger an API.

Many tutorials explain dialplan in a confusing way. This guide explains dialplan cleanly for latest Asterisk versions, with examples that work with PJSIP (modern standard).

If you understand this file, you can build: IVR, inbound routing, outbound routing, call center flows, and automation.

Where the Dialplan Lives

The main dialplan file is:

/etc/asterisk/extensions.conf

Many production systems split dialplan into multiple files and include them from extensions.conf. But learning starts with this file.

After editing dialplan, reload it from Asterisk CLI:

asterisk -rvvv
dialplan reload

Dialplan Concepts You Must Know

• Context → a container of rules (like a folder)
• Extension → what number/pattern was dialed (like 1001 or _9X.)
• Priority → step number inside an extension (1,2,3...) or n
• Application → action taken (Dial, Playback, Answer, Hangup, etc.)

In simple words: Context → Extension → Steps → Actions.

A Minimal Dialplan Example (Works on Latest Asterisk)

Add this to extensions.conf:

[from-internal]
exten => 1000,1,Answer()
 same => n,Playback(hello-world)
 same => n,Hangup()

What happens:

• When someone dials 1000 in context from-internal
• Asterisk answers the call
• Plays a file (hello-world)
• Hangs up

How Context Is Chosen (The Part People Miss)

Dialplan does nothing unless a channel enters a context. Context comes from:

• PJSIP endpoint setting: context=from-internal
• Inbound trunk setting: context=from-trunk
• Call files / AMI originate: specify context explicitly

Example PJSIP endpoint snippet:

[1001]
type=endpoint
context=from-internal
...

If the endpoint context is wrong, your dialplan “does not work” because calls never enter the expected context.

Dialing Phones in PJSIP (Modern Way)

In old tutorials you may see: Dial(SIP/1001) which is legacy.

Modern Asterisk uses PJSIP:

[from-internal]
exten => 1001,1,Dial(PJSIP/1001,20)
 same => n,Hangup()

This rings extension 1001 for 20 seconds.

Priorities: Using 1,2,3 vs Using "same => n"

Both are valid. But modern dialplan prefers readability:

exten => 2000,1,Answer()
 same => n,Playback(welcome)
 same => n,Hangup()

n means “next priority”. This prevents mistakes when inserting new steps.

Dialplan Logging (So You Can Debug)

The fastest way to debug dialplan is to add logs:

exten => 3000,1,NoOp(Entered 3000 in from-internal)
 same => n,Verbose(2,Caller is ${CALLERID(all)})
 same => n,Hangup()

You can see logs in CLI while calling:

asterisk -rvvv

Common Beginner Mistakes That Break Dialplan

• Editing dialplan but forgetting dialplan reload
• Endpoint context is different than the dialplan context
• Typing wrong extension number or missing underscores in patterns
• Audio file name is wrong (Playback fails silently)
• Call hits a different rule first because of pattern order

The number one mistake is: calls not entering the context you think.

Dialplan Structure for Real Projects

A clean structure looks like:

• from-internal → internal extensions and features
• from-trunk → inbound DID handling
• outbound → outgoing dial rules and trunk selection
• ivr-main → IVR menus
• queues → queue entry points

Don’t put everything inside one context. Split it logically.

Quick Test Dialplan for Verification

Add this to test dialplan quickly:

[from-internal]
exten => 9999,1,Answer()
 same => n,Playback(vm-goodbye)
 same => n,Hangup()

If you dial 9999 and hear goodbye, then your endpoint context + dialplan reload is working.

Key Takeaway

Dialplan is not complicated once you understand the structure: Context → Extension → Priorities → Applications.

And in modern Asterisk, always prefer: PJSIP channels and PJSIP-based dialing.

Once this foundation is clear, the next topics (Dial(), Playback(), variables, IVR, queues) become easy.