Asterisk course

Asterisk Hangup Application: Ending Calls in the Dialplan

Learn how to use Asterisk Hangup() to terminate an active call, finish dialplan branches, and prevent unintended call-flow continuation.

Hangup() is an Asterisk dialplan application that disconnects the active call or channel being processed. It is commonly the final application in a call-flow path: after Asterisk has completed an announcement, menu branch, or other service, Hangup() makes the end of processing explicit.

This lesson assumes you understand the basic structure of an Asterisk dialplan, including contexts, extensions, and priorities.

What Hangup() Does

When Asterisk reaches Hangup(), it terminates the active channel or call leg being handled by that dialplan path. The current call is disconnected, and execution of that call's current dialplan path ends.

Hangup() is useful when the intended call processing is complete. For example, a short service extension might answer, play an informational recording, and then disconnect. A menu branch might complete its final action and use Hangup() so the caller does not continue into unrelated priorities or fallback logic.

Basic Hangup() Syntax

The basic form requires no arguments:

Hangup()

In a modern dialplan, place it as a priority in an extension using same => n. The n means “next priority,” so Asterisk assigns the next sequential priority automatically.

[service-notice]
exten => 999,1,Answer()
same => n,Playback(service-unavailable)
same => n,Hangup()

The context is service-notice, the extension is 999, and the applications run in the order shown. Hangup() is the final priority in this path.

Explicit priority numbering

The same sequence can use explicit priority numbers:

[service-notice]
exten => 999,1,Answer()
exten => 999,2,Playback(service-unavailable)
exten => 999,3,Hangup()

Both styles describe the same execution order. Automatic numbering with same => n reduces errors when you insert or remove steps.

Complete Example: Answer, Play a Notice, and Disconnect

Put the following in extensions.conf, or in the dialplan configuration source used by your installation:

[service-notice]
exten => 999,1,Answer()
same => n,Playback(service-unavailable)
same => n,Hangup()

A caller who reaches extension 999 in the service-notice context follows this sequence:

1. Answer() answers the inbound call.
2. Playback(service-unavailable) plays the named audio prompt.
3. Hangup() disconnects the caller.

Hangup() is the concluding application. Once the prompt has finished, the call does not need another dialplan operation, so the explicit termination makes the intended endpoint clear.

Applications in the Basic Call Flow

Execution Order in the Example

Why Explicit Call Termination Matters

A dialplan is made of ordered applications. If a completed branch does not have a deliberate endpoint, later priorities, pattern matches, transfers, or fallback logic may be reached depending on the rest of the configuration and how control entered the branch.

Adding Hangup() at a deliberate endpoint provides predictable behavior:

• A short announcement ends immediately after the final recording.
• A completed menu branch does not fall through into unrelated processing.
• A service extension clearly communicates that its work is finished.
• Operators can identify the intended end of a call path while reading or troubleshooting the dialplan.

Compare an incomplete branch:

exten => 999,1,Answer()
same => n,Playback(service-unavailable)

With an explicit endpoint:

exten => 999,1,Answer()
same => n,Playback(service-unavailable)
same => n,Hangup()

The second version makes it clear that the call should end after the prompt. If the call is transferred or sent to another location before Hangup(), then that other destination controls the next part of the call flow; Hangup() must be placed at the endpoint that is actually intended to disconnect the caller.

Relationship to Answer()

Answer() answers an inbound call. Answering is important when the call flow needs to establish the call before delivering media or performing subsequent handling. In a basic example, Answer() also takes no arguments.

The common beginner pattern is:

1. Answer the call.
2. Deliver the announcement or other media.
3. Hang up after the interaction is complete.

Whether Answer() is required depends on the call flow and channel behavior, but the pattern is clear and useful for a simple inbound announcement. See The Answer Application for more detail.

Relationship to Playback() and Other Media Applications

Playback() plays an audio file or prompt. It should occur before Hangup() when the caller must hear a final message. Hangup() does not play an announcement, wait for input, or provide audio; it only performs call termination.

exten => 999,1,Answer()
same => n,Playback(service-unavailable)
same => n,Hangup()

In this sequence, Playback() is the final media operation and Hangup() is the final call-control operation. Review The Playback Application for prompt behavior and media configuration. For interactive announcements that collect input, related applications such as Background() may be part of a larger flow, with Hangup() still placed at branches that should terminate.

Contexts, Extensions, and Priorities

Hangup() is written wherever the relevant dialplan path is defined, usually in extensions.conf or an equivalent included configuration file.

• Context: A named dialplan section that groups extensions and controls which routes are available.
• Extension: A number or matching pattern that selects a sequence of call-processing steps.
• Priority: The ordered position of an application within that extension's sequence.
• Channel: Asterisk's representation of an active communications path, such as an inbound or outbound call leg.

For example:

[service-notice]                 ; context
exten => 999,1,Answer()          ; extension 999, priority 1
same => n,Playback(service-unavailable) ; next priority
same => n,Hangup()               ; final priority

When a call reaches extension 999 in service-notice, Asterisk processes the priorities in order. The incoming endpoint must actually use or reach this context for the example to run.

Call-Flow Scope

Hangup() affects the active call or channel being processed. In the simple inbound example, that means the caller's current call is disconnected and the current dialplan execution path ends.

More advanced applications can create or control multiple channels, such as an outbound call leg connected to an inbound caller. In those designs, administrators must deliberately determine which channel a call-control operation affects. That complexity does not change the basic lesson: place termination at the endpoint of the channel and branch you intend to end.

End-of-Branch Cleanup

Hangup() is especially useful after a branch has completed its intended action:

[service-menu]
exten => 1,1,Answer()
same => n,Playback(option-one-complete)
same => n,Hangup()

dialplan reload

dialplan show 999@service-notice

core set verbose 4