Your First Working Asterisk Dialplan

Your Asterisk server is installed but nothing happens when you try to make a call. This guide gets you from zero to a working system, endpoints that register, phones that call each other, and audio that plays. The smallest possible proof that everything is wired up.

What You Need Before Starting

• Asterisk 18 or later, installed and running
• SSH access to the Asterisk server
• A softphone to test with (Linphone, MicroSIP, or Zoiper all work)
• A text editor you're comfortable with

Registering Your First Endpoints

Before the dialplan can do anything, you need phones that can connect to Asterisk. PJSIP handles this. Open /etc/asterisk/pjsip.conf and add a minimal transport and two endpoints:

;── Transport ─────────────────────────────────────
; Tells Asterisk which IP and port to listen on for SIP traffic.

[transport-udp]
type = transport
protocol = udp
bind = 0.0.0.0:5060

;── Extension 200 ─────────────────────────────────

[200]
type = endpoint
context = internal
disallow = all
allow = ulaw,alaw
auth = 200-auth
aors = 200

[200-auth]
type = auth
auth_type = userpass
username = 200
password = changeme200

[200]
type = aor
max_contacts = 1

;── Extension 201 ─────────────────────────────────

[201]
type = endpoint
context = internal
disallow = all
allow = ulaw,alaw
auth = 201-auth
aors = 201

[201-auth]
type = auth
auth_type = userpass
username = 201
password = changeme201

[201]
type = aor
max_contacts = 1

Each endpoint needs three objects: an endpoint (call settings), an auth (credentials), and an aor (address of record, where the phone registers). The context = internal line is critical; it tells Asterisk which part of the dialplan this phone can access.

Reload PJSIP:

asterisk -rx "pjsip reload"

Now configure your softphone to register with username 200, password changeme200, and point it at your Asterisk server's IP on port 5060. Check registration:

asterisk -rx "pjsip show endpoints"

You should see endpoint 200 with a contact listed. If the contact column is empty, the phone hasn't registered, check the IP, port, and credentials.

The Shortest Working Dialplan

With endpoints registered, you need a dialplan to handle calls. Open /etc/asterisk/extensions.conf and replace everything in it with:

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

That's it. Three lines. Reload and test:

asterisk -rx "dialplan reload"

Call extension 100 from a registered phone. If you hear the "hello world" prompt, your dialplan is working.

What Just Happened

Those three lines contain the four building blocks of every Asterisk dialplan:

Context: [internal] is a container that groups extensions together. Endpoints are assigned to a context in their PJSIP configuration (context = internal). A phone can only reach extensions in the context it's placed in, which is how you control who can dial what.

Extension: 100 is the number someone dials. Extensions don't have to be numeric; they can be names, patterns, or special identifiers like s (start) and i (invalid).

Priority: 1 is the first step. n means "next" and auto-increments. Every extension runs its priorities in order, top to bottom.

Application: Answer(), Playback(), and Hangup() are the actual work. Answer picks up the channel, Playback plays an audio file, Hangup tears it down.

Making Two Phones Call Each Other

A hello-world prompt proves the dialplan works, but you want phones to ring. Add extensions for your endpoints:

[internal]
; -- Test extension
exten => 100,1,Answer()
same => n,Playback(hello-world)
same => n,Hangup()

; -- Extension 200 (desk phone)
exten => 200,1,Dial(PJSIP/200,30)
same => n,Voicemail(200@default,u)
same => n,Hangup()

; -- Extension 201 (softphone)
exten => 201,1,Dial(PJSIP/201,30)
same => n,Voicemail(201@default,u)
same => n,Hangup()

Dial(PJSIP/200,30) rings the PJSIP endpoint named 200 for 30 seconds. If nobody answers, the call falls through to Voicemail().

Reload the dialplan:

asterisk -rx "dialplan reload"

From extension 201, dial 200. The desk phone rings. If nobody picks up after 30 seconds, voicemail answers.

Debugging When It Doesn't Work

If calls fail silently, Asterisk's CLI tells you why. Connect to it:

asterisk -rvvv

The v flags control verbosity, more v's, more detail. Three is usually enough. Now make a call and watch the output. Common problems:

"No matching extension": The dialed number doesn't exist in the context the phone is assigned to. Check that context = internal in pjsip.conf matches the [internal] header in extensions.conf.

"Endpoint not found": The Dial() target doesn't match a configured PJSIP endpoint. Check that Dial(PJSIP/200) matches an endpoint named 200 in pjsip.conf.

"Channel not registered": The phone isn't connected. Check pjsip show endpoints to see registration status.

No output at all: The call isn't reaching Asterisk. Check firewall rules and that the phone is pointed at the right IP and port.

What to Do Next

You have a working dialplan with internal calling. From here:

• Add a ring group so multiple phones ring at once: see the Ring Group snippet
• Build an IVR menu with Background() and WaitExten(): see the Simple IVR snippet
• Add time-based routing for business hours: see the Time-Based Routing snippet
• Set up voicemail: the Voicemail() and VoicemailMain() applications handle this

The key concept: everything in Asterisk flows through the dialplan. Every incoming call, outbound route, voicemail check, and conference bridge is an extension with priorities running applications. Once you understand that pattern, the rest is just learning which applications exist and what arguments they take, which is what the reference section is for.