VMware ESXi and vSphere Cluster Management

Asterisk Dialplan Priorities

Learn how Asterisk uses numeric priorities, n, and same => to execute multi-step extensions in extensions.conf.

Asterisk executes a dialplan one step at a time. A priority is the ordered execution position of an application inside an extension. Understanding priorities lets you build predictable call flows and add or remove steps without accidentally changing their order.

What priorities do

The dialplan is Asterisk's call-routing logic, commonly configured in extensions.conf. A context is a named group of extensions that defines the dialing scope available to a channel.

An extension is a dialable pattern or identifier with one or more ordered application steps. A single extension can contain several steps. Each step invokes one Asterisk application, such as playing audio, sending a caller to voicemail, or ending a call.

When a caller reaches an extension in a context, Asterisk runs that extension's applications according to their priorities. The priority identifies which step runs first, second, third, and so on.

Priority syntax

A dialplan step in extensions.conf commonly uses this format:

exten => extension,priority,application(arguments)

The four parts have distinct roles:

Extension identifier — The dialable number or pattern, such as 100.

Priority — The execution position for this step, such as 1, 2, or n.

Application — The Asterisk action to execute, such as Playback(), Voicemail(), or Hangup().

Application arguments — Values supplied to the application to control its behavior, such as a sound name or mailbox number.

Priorities are associated with a particular extension within a particular context. The same priority number can therefore appear for many different extensions without creating a conflict.

Numeric execution order

With explicit numeric priorities, Asterisk uses the priority values to determine the intended sequence. For example:

[example-context]
exten => 100,1,Playback(tt-weasels)
exten => 100,2,Voicemail(10)
exten => 100,3,Hangup()

The call flow is:

  1. Priority 1 runs Playback(tt-weasels), playing the prompt.
  2. Priority 2 runs Voicemail(10), directing the caller to mailbox 10.
  3. Priority 3 runs Hangup(), terminating the call.

The physical order of matching configuration lines is not the call-flow order. Asterisk follows the priority values for the extension. For example, the lines below are deliberately arranged differently in the file:

[example-context]
exten => 100,3,Hangup()
exten => 100,1,Playback(tt-weasels)
exten => 100,2,Voicemail(10)

The intended execution remains priority 1, then 2, then 3: playback, voicemail, and hangup. Rearranging lines does not change that sequence when the extension and priority values remain unchanged.

Priorities should form a valid, reachable sequence for the intended call path. If a later step is missing, incorrectly numbered, or attached to another extension, the call may not continue as expected.

Using the n priority

n means the next sequential priority for the current extension. It was introduced in Asterisk 1.2. Instead of manually renumbering every later step, you can use n after an initial numeric priority.

[example-context]
exten => 100,1,Playback(tt-weasels)
exten => 100,n,Voicemail(10)
exten => 100,n,Hangup()

Here, the first line explicitly establishes priority 1. The first n becomes priority 2, and the second n becomes priority 3.

The first priority must still be explicitly specified. A dialplan cannot begin with n because Asterisk needs an initial numeric position from which to calculate the next priority.

The main benefit is maintainability. If you insert another step between playback and voicemail, later n steps continue to represent the next position without requiring you to change every following number.

Using same =>

same => continues the extension declared by the preceding extension line. It avoids repeating the extension identifier on every subsequent line.

[example-context]
exten => 100,1,Playback(tt-weasels)
same => n,Voicemail(10)
same => n,Hangup()

This compact form combines both shortcuts:

  • same => reuses extension 100.
  • n selects the next sequential priority.
  • The first line still uses an explicit priority, 1.

Use same => only while defining additional priorities for the same extension. If the next step belongs to a different extension, declare that extension explicitly instead of continuing with same =>.

Ways to write consecutive priorities

Explicit numeric priorities — First step: exten => 100,1,Playback(tt-weasels) — Following steps: exten => 100,2,... and exten => 100,3,... — Best use: maximum visibility and precise numbering.

n priorities — First step: exten => 100,1,Playback(tt-weasels) — Following steps: exten => 100,n,... — Best use: sequential flows where later steps should automatically advance.

same => with n — First step: exten => 100,1,Playback(tt-weasels) — Following steps: same => n,... — Best use: compact, readable definitions with several steps for one extension.

Complete example: prompt, voicemail, and hangup

Suppose a caller dials extension 100. The caller should hear an audio prompt, be transferred to voicemail mailbox 10, and then have the call terminated.

[example-context]
exten => 100,1,Playback(tt-weasels)
exten => 100,2,Voicemail(10)
exten => 100,3,Hangup()

Playback(tt-weasels) runs first and plays the specified sound prompt. Its argument, tt-weasels, identifies the prompt.

Voicemail(10) runs second and directs the caller to mailbox 10. The value 10 is an application argument.

Hangup() runs third and terminates the current call. The empty parentheses indicate that this application needs no argument in this example.

Troubleshooting priority problems

A call does not reach a later application

  • Verify that the caller reached the expected extension and context.
  • Check that the next priority exists and belongs to that extension.
  • Confirm that the application at the previous step returns to the dialplan when appropriate.
  • Review the priority sequence for gaps, incorrect values, or an unintended branch.

Steps appear to run unexpectedly after lines are rearranged

Inspect the numeric priority values rather than the physical line placement. Asterisk chooses the sequence from the priorities associated with the extension.

A dialplan beginning with n fails

Change the first step to an explicit numeric priority, normally 1. Use n only on subsequent sequential steps.

A later step is attached to the wrong extension

Review the preceding extension declaration. same => reuses the relevant preceding extension, so using it after the extension has changed—or where a new extension should be declared—can attach a step to the wrong call target.

Summary

  • A priority is the execution position of an application inside an extension.
  • One extension can contain multiple ordered applications.
  • Numeric priorities such as 1, 2, and 3 describe the call sequence.
  • The priority values, not the physical order of configuration lines, determine execution.
  • n means the next sequential priority and requires an explicit first priority.
  • same => continues the extension from the preceding declaration.
  • Combining same => and n creates a concise multi-step extension.