Asterisk course

Asterisk Dialplan Priorities

Learn how Asterisk dialplan priorities control application order, including numeric priorities, n, same =>, and practical extensions.conf examples.

In Asterisk, a call follows a dialplan: the call-routing logic commonly stored in extensions.conf or an equivalent configuration source. A dialplan is organized into contexts, and each context contains one or more extensions.

An extension is a dialable destination or matching rule. It can contain several steps, such as playing a prompt, sending a caller to voicemail, and ending the call. A priority is the execution position assigned to one of those steps within the extension.

Every priority invokes an Asterisk application. For example, Playback() plays audio, Voicemail() starts voicemail processing, and Hangup() terminates the channel. Values inside the parentheses are the application's arguments.

For background, see What Is A Dialplan, Contexts, and Extensions.

How priorities control execution

When a call enters an extension, Asterisk starts at the appropriate priority and follows the extension's application sequence. In a simple linear flow, priority 1 runs first, priority 2 runs next, and priority 3 follows.

The priority belongs to one extension. Priority 2 in extension 100 is unrelated to priority 2 in extension 200. The context and extension identify the destination; the priority identifies the step within that destination.

Basic extension line structure

A traditional dialplan line has this general form:

exten => extension,priority,Application(arguments)

Its components are:

  • exten is the extension declaration keyword.
  • Extension number or pattern identifies the destination, such as 100 or a pattern such as _X..
  • Priority specifies the step's execution position.
  • Application is the Asterisk action to invoke.
  • Application arguments provide values that control the action. Some applications have no arguments.

The priority appears after the extension identifier and before the application name:

exten => 100,2,Voicemail(10)

This line means that extension 100 has a step at priority 2. When that step runs, Asterisk invokes Voicemail() with mailbox 10.

Learn more about individual applications in The Playback Application, The Voicemailmain Application, and The Hangup Application.

Execution order versus file order

For ordinary priority execution, the priority values determine the sequence, not the physical order of matching lines in extensions.conf. A dialplan should still be written in logical source order because readable configuration is easier to review and maintain.

For example, these lines are deliberately listed out of numerical order:

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

The runtime sequence remains:

  1. Priority 1 runs Playback(tt-weasels).
  2. Priority 2 runs Voicemail(10).
  3. Priority 3 runs Hangup().

Numeric priorities

An explicit integer is the traditional way to number a step. A three-step extension can be written as follows:

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

The call flow is easy to map:

Extension | Priority | Application | Arguments | Caller-visible result

100 | 1 | Playback | tt-weasels | The prompt plays

100 | 2 | Voicemail | 10 | Voicemail handling begins

100 | 3 | Hangup | None | The call terminates

Explicit numbers can be useful when documenting a fixed sequence, following a legacy convention, or deliberately referring to a particular position. They also make each step's number immediately visible.

The maintenance cost appears when inserting a step. If a new application must run between priorities 1 and 2, later steps may need to be renumbered:

exten => 100,1,Playback(tt-weasels)
exten => 100,2,SomeApplication()
exten => 100,3,Voicemail(10)
exten => 100,4,Hangup()

In a longer extension, changing many hard-coded numbers increases the chance of skipped, duplicated, or incorrectly ordered priorities.

The n priority

n means “the next priority” for the current extension. Asterisk calculates it by incrementing the preceding priority. The first step must still have an explicit starting priority.

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

This produces the same effective sequence as priorities 1, 2, and 3:

  1. The explicit priority 1 plays the prompt.
  2. The first n becomes the next priority, 2, and starts voicemail.
  3. The second n becomes priority 3 and hangs up.

Using n reduces editing when adding or moving ordinary sequential steps. For example, inserting an application between playback and voicemail requires no manual renumbering of the later n-based lines:

exten => 100,1,Playback(tt-weasels)
exten => 100,n,SomeApplication()
exten => 100,n,Voicemail(10)
exten => 100,n,Hangup()

There must be an explicit initial priority, normally 1. This is not a valid way to establish the beginning of an extension:

exten => 100,n,Playback(tt-weasels)

Without a preceding starting priority for extension 100, Asterisk has no prior position from which to calculate n. The n syntax is supported by Asterisk versions beginning with Asterisk 1.2.

The same => shorthand

same => continues the most recently declared extension in the same context. It avoids repeating the extension number on each subsequent line.

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

In this example, both same => lines continue extension 100. Combined with n, the shorthand expresses a concise linear flow: start extension 100 at priority 1, then automatically advance to voicemail and hangup.

Use same => only while continuing the same extension. When beginning a different extension, use a new explicit declaration:

exten => 100,1,Playback(tt-weasels)
same => n,Voicemail(10)

exten => 200,1,Playback(other-prompt)

The first line for extension 200 must use exten =>; otherwise, a continuation line could be associated with the wrong extension.

Priority syntax comparison

Syntax | Meaning | Typical use | Key limitation

Explicit integer priority | Assigns a specific position such as 1, 2, or 3 | Fixed numbering, legacy conventions, or deliberate position references | Inserting a middle step can require renumbering later steps

n | Selects the next sequential priority after the preceding step | Ordinary linear call flows that start with an explicit number | Cannot establish the first step by itself

same => | Continues the most recently declared extension | Avoids repeating the extension identifier on following lines | Must continue the intended preceding extension and context

Equivalent representations of one call flow

Each example below describes extension 100. The intended runtime flow is prompt playback, voicemail for mailbox 10, and then call termination.

Verbose numeric representation

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

Out-of-order source representation

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

Although the source lines are arranged as 3, 1, 2, the priority sequence is still 1, 2, 3: playback, voicemail, then hangup.

n-based representation

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

same => and n representation

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

The shorthand changes how the dialplan is written, not the intended call flow. In all four versions, the operations map to priorities 1, 2, and 3.

Choosing a readable authoring style

  • Keep source lines in logical execution order even though priority values control normal sequencing.
  • For a straightforward linear flow, use an explicit first priority followed by n.
  • Use same => when several consecutive lines continue the same extension.
  • Use explicit numeric priorities when fixed positions improve clarity, when maintaining an established dialplan convention, or when a deliberate control-flow reference depends on a specific priority.
  • Begin every extension sequence with an explicit priority. Do not assume n can create the starting position.
  • Use an explicit exten => declaration whenever you begin a different extension.

Troubleshooting priority problems

A step executes in an unexpected position

The priority may not match the intended sequence, or the source-line order may have been mistaken for execution order. Inspect all priority values belonging to the extension and arrange the intended sequence by priority.

An extension begins with n

Cause: There is no explicit first priority from which n can derive its value.

Fix: Set the initial step to an explicit number, normally 1, and use n only for following steps.

A continued line attaches to the wrong extension

Cause: same => was used after another extension declaration or across an unintended boundary.

Fix: Start each extension with exten => and restrict same => lines to the immediately preceding extension's continuation.

Adding a step requires many changes

Cause: The extension uses consecutive hard-coded priorities.

Fix: For an ordinary sequential flow, keep the first priority explicit and use n for later steps.

The caller reaches voicemail or hangup before hearing the prompt

Cause: Playback, voicemail, and hangup have been assigned in the wrong priority order.

Fix: Verify that Playback() has the earliest priority, Voicemail() follows it, and Hangup() is the final ordinary step.

Key points

  • An extension can contain multiple dialplan steps.
  • A priority is the execution position of an application step within one extension.
  • The priority follows the extension identifier and precedes the application name.
  • Priority values, rather than ordinary source-line placement, determine normal execution order.
  • Numeric priorities are explicit but may require renumbering when steps are inserted.
  • n selects the next priority and requires an explicit initial priority.
  • same => continues the most recently declared extension in the same context.
  • same => n is a concise style for a readable linear extension.