Asterisk Goto Application: Dialplan Flow Control

Learn how Asterisk Goto() redirects dialplan execution within an extension, across extensions, or between contexts, with examples and troubleshooting.

Goto() is an Asterisk dialplan application that changes the location where dialplan execution continues. It can jump to another priority in the current extension, to another extension in the current context, or to an extension in another context.

Goto() controls call flow; it does not dial a phone, channel, or other endpoint. Applications such as Dial() are used to place calls to endpoints. Goto() simply tells Asterisk which dialplan application should run next.

How Asterisk Identifies a Dialplan Location

A dialplan is Asterisk call-processing logic, commonly written in extensions.conf. A location in that dialplan has three components:

Component	Role	Example value
Context	A named section that groups extensions and helps control which destinations a caller can access.	`local`
Extension	An identifier or matching pattern containing one or more applications.	`555`
Priority	The ordered execution position of an application within an extension.	`1`

Together, these values form a destination such as local,555,1. Asterisk uses the context, extension, and priority to select the next application for the channel.

When a call enters a context and matches an extension, Asterisk normally starts at that extension's first priority and proceeds through the priorities in order. For example:

[local]
exten => 555,1,Answer()
same => n,Playback(welcome)
same => n,Hangup()

A call entering local and matching 555 begins at priority 1, runs Answer(), then continues to the next priority represented by n, and finally runs Hangup(). Goto() changes this normal sequential path.

Goto() Syntax

Goto() accepts one, two, or three comma-separated arguments. The number of arguments determines which parts of the destination are supplied.

Syntax	Argument meaning	Destination scope	Example
`Goto(priority)`	The argument is the destination priority.	Current extension and current context.	`Goto(4)`
`Goto(extension,priority)`	First argument is the extension; second is the priority.	Named extension in the current context.	`Goto(201,1)`
`Goto(context,extension,priority)`	Arguments identify context, extension, and priority in that order.	Explicit destination in another or the current context.	`Goto(NewContext,555,1)`

The comma-separated order is significant. In the three-argument form, the first value is the context, the second is the extension, and the third is the priority. Swapping these values sends Asterisk to a different location or causes the destination lookup to fail.

One Argument: Another Priority in the Current Extension

Goto(priority) keeps both the current context and current extension. It changes only the priority where execution resumes.

[local]
exten => 100,1,Answer()
same => n,Goto(4)
same => n,Playback(this-step-is-skipped)
same => n,Playback(destination-reached)
same => n,Hangup()

After answering, Asterisk jumps to priority 4 in extension 100 in context local. The intermediate Playback() at priority 3 is skipped, and the destination prompt at priority 4 runs.

This is different from normal sequential execution. Without Goto(), Asterisk would continue from one priority to the next. With Goto(4), it deliberately bypasses the priorities between the current location and priority 4.

Two Arguments: Another Extension in the Current Context

Goto(extension,priority) changes the extension and priority but remains in the current context.

[local]
exten => 200,1,Goto(201,1)
exten => 201,1,Playback(you-have-reached-a-test-number)
same => n,Hangup()

A call reaching extension 200 continues at extension 201, priority 1, within local. The call does not move to another context.

Three Arguments: An Explicit Context, Extension, and Priority

Goto(context,extension,priority) fully qualifies the destination. This form is the clearest choice when the target is in another context.

[NewContext]
exten => 555,1,Playback(you-have-reached-a-test-number)
same => n,Hangup()

[local]
exten => 555,1,Goto(NewContext,555,1)

Here, the source and destination extensions both use the number 555. The context distinguishes them: the source is 555@local, while the destination is 555@NewContext.

Cross-Context Example Call Flow

Consider a caller whose call has entered the local context and who dials 555:

Asterisk matches 555 in local.
Execution begins at 555,1 in that context.
The application Goto(NewContext,555,1) runs.
Asterisk looks for extension 555, priority 1, in NewContext.
Execution continues with Playback(you-have-reached-a-test-number).
The next priority runs Hangup(), ending the call.

The destination must exist in the dialplan loaded by Asterisk. Defining the text in a configuration file is not enough if that configuration has not been loaded or if another dialplan source is active.

Adding a Visible Destination Marker

Use NoOp() to place a diagnostic message in the Asterisk console. It does not normally produce audio for the caller, but it makes the execution path easier to confirm.

[NewContext]
exten => 555,1,NoOp(Entered NewContext extension 555)
same => n,Playback(you-have-reached-a-test-number)
same => n,Hangup()

You can also use Playback() as an audible marker. For more information, see the Playback application.

Priority Behavior

A priority identifies the execution order of an application inside an extension. Numeric notation such as 1 explicitly names the first priority. The shorthand n means the next sequential priority after the preceding line.

exten => 300,1,NoOp(Start)
same => n,Playback(first-step)
same => n,Playback(second-step)

The three applications execute in order. If an application executes Goto(1), Asterisk jumps to priority 1 in the current extension and context; it does not continue with the next sequential priority.

A jump to a priority that does not exist cannot continue normal execution at the requested location. Likewise, a target extension or context must be present. Always check that the destination priority contains an application and that the target is loaded.

Safe Dialplan Editing and Validation

Check the spelling and capitalization of the target context.
Confirm the target extension exists in that context.
Confirm the requested priority exists within that extension.
Check that the Goto() arguments are in the correct positional order.
Add a NoOp() or Playback() marker to the destination while testing.
Reload the dialplan after editing.
Inspect the loaded dialplan rather than relying only on the contents of the configuration file.

asterisk -rvvv

dialplan reload
dialplan show NewContext
dialplan show 555@NewContext

dialplan reload applies modified dialplan configuration. dialplan show NewContext displays the loaded entries in the target context. dialplan show 555@NewContext checks the specific destination extension and its priorities.

Common Goto() Failures

Symptom	Likely cause	How to verify	Correction
Target context missing	The context is not defined or is not loaded.	Run `dialplan show NewContext` and inspect the active configuration.	Create or correct the context, then run `dialplan reload`.
Target extension missing	The extension is absent from the target context.	Run `dialplan show 555@NewContext`.	Add the extension to the intended context and reload.
Target priority missing	The requested priority has no application.	Inspect all priorities for the target extension.	Use an existing priority or add the required application.
Arguments supplied in the wrong order	Context, extension, and priority were not supplied positionally.	Compare the argument count and order with the intended destination.	Use `Goto(target_context,target_extension,target_priority)` for an unambiguous cross-context jump.
Dialplan changes not reloaded	The file was edited, but Asterisk is still using the previous loaded dialplan.	Run `dialplan show` and compare its output with the intended change.	Run `dialplan reload`, then verify again.

Troubleshooting Unexpected Call Flow

Goto() Does Not Reach the Intended Destination

First compare the form of Goto() with the intended scope. A two-argument call searches for an extension in the current context; it cannot select an extension that exists only in another context. For a cross-context jump, use the explicit three-argument form:

Goto(target_context,target_extension,target_priority)

Then inspect the target with dialplan show. This confirms whether Asterisk has loaded the context, extension, and priority you expect.

Asterisk Cannot Find the Destination

Check whether the target context has been defined, whether the extension is present in that context, and whether the requested priority exists. Check context spelling and capitalization as well. Correct the destination, reload the dialplan, and verify it again before placing another test call.

Recent Edits Have No Effect

Run dialplan reload. If the change still does not appear, use dialplan show to inspect the active dialplan. The active configuration may be generated from a different source than the file you edited.

The Call Skips Applications

This may be the intended result: Goto() transfers execution away from the sequential next priority. Map the priorities in both the source and destination extensions. Add NoOp() markers to show which path the call actually takes, and adjust the target priority or reorganize the dialplan if the jump begins too late.

Exam-Relevant Notes

Goto() redirects dialplan execution; it does not dial an endpoint.
The one-argument form is Goto(priority) and stays in the current context and extension.
The two-argument form is Goto(extension,priority) and stays in the current context.
The three-argument form is Goto(context,extension,priority) and explicitly identifies the destination.
Argument order is positional: context, extension, priority.
A destination must be present in the loaded dialplan.
Jumping to priority 1 is not the same as continuing to the next sequential priority.
Use dialplan reload and dialplan show to apply and verify changes.