VMware ESXi and vSphere Cluster Management

Create Your First Asterisk Dialplan for Calls Between Two SIP Phones

Learn how to create and reload a basic Asterisk dialplan that lets two registered SIP phones call each other using extensions 101 and 105.

This lesson creates a small internal calling plan for two SIP phones. One phone will be reachable at extension 101 and the other at extension 105.

Lesson goal and completed environment

Asterisk is an open-source PBX and telephony platform. It processes calls according to a dialplan, which is a set of rules describing what Asterisk should do when someone dials a number.

By the end of this lesson, a caller in the local context will be able to dial:

• 101 to call the SIP peer named alice.
• 105 to call the SIP peer named bob.

This lesson assumes that:

• Asterisk is installed and running.
• You can access the Asterisk CLI.
• Two softphones or SIP phones are already configured as SIP peers.
• The peers are named alice and bob.
• Both phones can register successfully with Asterisk.

A dialed extension is a dialplan destination. It does not have to be the identity of the person making the call. For example, Bob can dial 101; Asterisk then follows the rule for extension 101 and calls Alice.

Verify SIP endpoint registration

Before testing a dialplan, confirm that the destination phones are available. A SIP peer is a configured SIP endpoint or account that Asterisk can contact. A softphone is software that behaves like a telephone and registers to Asterisk over SIP.

Open the Asterisk CLI, the interactive console used to inspect status, reload configuration, and observe calls. With the traditional chan_sip driver, run:

sip show peers

The peer listing generally includes each endpoint's name, host or address, status, and reachability. Look for entries corresponding to alice and bob. A healthy listing indicates that Asterisk knows the peer and can generally reach its registered address.

Configure the dialplan file

The traditional Asterisk dialplan is stored in:

/etc/asterisk/extensions.conf

This file is organized into contexts. A context is a named group of dialplan rules that also controls which extensions a caller may use. Context names are enclosed in square brackets.

Add a context named local with two internal routes:

[local]
exten => 101,1,Dial(SIP/alice)
same => n,Hangup()
exten => 105,1,Dial(SIP/bob)
same => n,Hangup()

The context assignment matters. The calling endpoint must be configured to enter the local context. If it enters another context, Asterisk will not search the local rules when the caller dials 101 or 105.

Understand extension and priority syntax

An extension declaration follows this general form:

exten => extension,priority,application(arguments)

• Extension: The number or pattern the caller dialed, such as 101.
• Priority: The ordered position of this step within the extension.
• Application: The Asterisk function to execute, such as Dial or Hangup.

Priority 1 is the first action for a matched extension. A single extension can contain several ordered actions.

The shorthand same => n means “use the next sequential priority for the current extension.” In the example, the first action for extension 101 has priority 1, and Hangup() receives the next priority.

exten => 101,1,Dial(SIP/alice)  ; priority 1: call Alice
same  => n,Hangup()             ; next priority: end processing

Create the two internal extension routes

The complete configuration maps two dialed numbers to two SIP channel targets:

The extension number and peer name have different jobs:

• 101 and 105 are dialplan destinations selected by the caller's digits.
• alice and bob identify configured SIP devices or accounts.

Peer names are case-sensitive configuration identifiers in many setups, so the names in Dial() must match the configured names exactly.

How the Dial application works

Dial initiates an outbound call leg to a channel destination. In traditional SIP channel syntax, SIP/alice means “create a SIP call to the peer named alice.” Similarly, SIP/bob targets Bob.

For Bob calling Alice, the normal progression is:

1. Bob dials 101.
2. Asterisk looks in Bob's current context for extension 101.
3. Asterisk executes Dial(SIP/alice).
4. Alice's phone rings.
5. Alice answers and Asterisk bridges the caller and destination call legs.
6. When the call ends, execution continues to Hangup().

Calling extension 101 may ring Alice even when the original caller is Bob. The number dialed is a destination chosen by the dialplan; it is not necessarily the caller's own extension.

Reload the dialplan

After saving /etc/asterisk/extensions.conf, reload the dialplan from the Asterisk CLI:

dialplan reload

A dialplan reload causes Asterisk to reread, parse, and activate the modified rules without restarting the full Asterisk service. Successful output should indicate that the file was parsed and that the local context and its extensions were accepted.

If the reload reports a parse error, or the expected context and extensions do not appear in the reload information, correct the configuration before placing a call. Common causes include a malformed context header, a missing comma, an invalid priority, or editing the wrong file.

Place and observe the first test call

1. Confirm that both alice and bob are registered.
2. Confirm that the calling endpoint is assigned to the local context.
3. From Bob's phone, dial 101.
4. Confirm that Alice's softphone rings.
5. Answer the call.
6. Verify two-way audio if the lab network supports media in both directions.
7. Hang up and confirm that the call terminates cleanly.

Watch the Asterisk console while testing. The console connects each dialplan step with the resulting call event, making it easier to determine whether a problem is caused by number matching, endpoint availability, or media connectivity.

Interpret basic Asterisk console output

Exact wording and channel identifiers vary by Asterisk version and configuration, but useful output normally includes these categories:

Channel names reveal the caller and destination call legs. They often include a unique sequence suffix, so do not rely on the exact suffix when comparing test calls. Focus on the peer names, the selected context and extension, and the call state.

Normal messages such as Called, ringing, and answered describe call progress. Registration failures, missing peers, invalid contexts, and parse errors indicate configuration or availability problems instead.

Troubleshooting

Dialing 101 or 105 does not reach the intended phone

• Run dialplan reload; the file may have been edited but not reloaded.
• Verify that the caller's endpoint uses the local context.
• Check that the dialed extension exists and is spelled correctly.
• Confirm that the Dial() target uses the correct peer name.

The called phone does not ring

• Run sip show peers and inspect the target endpoint's status.
• Confirm that the correct softphone account is logged in and registered.
• Compare the target in the dialplan with the configured peer name: SIP/alice must reference alice, and SIP/bob must reference bob.
• Check network connectivity and SIP registration settings.

Reload output reports an error

• Ensure the context header is enclosed in brackets: [local].
• Ensure each extension begins at priority 1.
• Use the next priority for the following action, either explicitly or with same => n.
• Check that every application line has valid syntax.
• Verify that edits were saved to /etc/asterisk/extensions.conf.

The console shows a call attempt but the target never answers

• Determine whether the target is ringing but simply has not been answered.
• Look for Called, ringing, and answered events.
• Check the target phone's registration state and network connectivity.
• Retry after confirming that the target peer is available.

The call does not terminate cleanly

• Ensure each route has Hangup() after Dial().
• Confirm that Hangup() is on the next priority for the same extension.
• Use console execution output to verify that the call entered the expected context and extension rather than a different route.

Exam-relevant notes

• extensions.conf contains contexts, extensions, priorities, and applications.
• A context controls which dialplan rules are available to an endpoint.
• Priority 1 is the first action for a matched extension.
• same => n means the next sequential priority for the current extension.
• Dial() calls a channel target; Hangup() ends call processing.
• An extension number such as 101 is a dialplan destination, while alice is a configured SIP peer identity.
• A registered endpoint must be reachable before Dial() can successfully call it.
• Use dialplan reload after changing the dialplan; a full service restart is not required for these rules.

The finished lesson configuration is available as the internal reference first dialplan lesson.