VMware ESXi and vSphere Cluster Management

Asterisk Hangup Application: Ending Calls in a Dialplan

Learn how Asterisk Hangup() ends the active channel, stops dialplan execution, and fits with Answer(), Playback(), Background(), and call-routing flows.

Hangup() is the Asterisk dialplan application used to end the active call channel. It provides an explicit endpoint for a call flow: once Asterisk reaches Hangup(), the channel is terminated and later dialplan priorities are not processed for that call.

This is different from completing an audio application. Playback() can finish playing a prompt while the call remains active. If the extension is intended to disconnect after that prompt, the dialplan should include Hangup() as the final action.

Key dialplan terms

  • Dialplan: Asterisk call-routing logic organized into contexts, extensions, and priorities.
  • Context: A named dialplan section that groups related call-processing rules.
  • Extension: A dialplan match or destination containing one or more ordered actions.
  • Priority: The execution order of applications within an extension.
  • Channel: Asterisk's representation of a call leg or communications path being processed.

Hangup() syntax

In its basic form, Hangup() takes no arguments:

Hangup()

An extension can use standard priority numbers:

[example-announcement]
exten => 999,1,Answer()
exten => 999,2,Playback(this-call-may-be-monitored-or-recorded)
exten => 999,3,Hangup()

Modern dialplans commonly use same => n to continue the preceding extension and assign the next priority automatically:

[example-announcement]
exten => 999,1,Answer()
 same => n,Playback(this-call-may-be-monitored-or-recorded)
 same => n,Hangup()

The same => n notation means “continue the preceding extension at the next priority.” It does not create a new extension.

Basic announcement-then-disconnect flow

A simple informational extension often answers the incoming channel, plays an announcement, and deliberately disconnects:

[example-announcement]
exten => 999,1,Answer()
 same => n,Playback(this-call-may-be-monitored-or-recorded)
 same => n,Hangup()
  1. A caller reaches extension 999 in the example-announcement context.
  2. Answer() accepts the incoming call.
  3. Playback() delivers the named audio prompt.
  4. Hangup() ends the active channel after the prompt completes.

For a short terminal extension, placing Hangup() after the final intended call-handling action makes the design clear. It prevents the call from being treated as though more interaction or routing is expected.

How Hangup() affects dialplan execution

Asterisk normally processes an extension's priorities sequentially while the call remains active. Each application runs at its assigned priority, and execution can continue to a later priority when the application and call state allow it.

Hangup() is different: it terminates the channel handling the active call. It should be treated as a terminal action, not as an application that returns control to the next priority.

Without a clearly designed terminal behavior, a call flow can produce unintended results. For example, a prompt may finish and the dialplan may continue into later priorities or another routing path when the author intended the informational extension to end. Review the complete priority sequence and decide explicitly whether the call should disconnect, collect input, transfer, or bridge to another party.

Answer() versus Hangup()

Answer() and Hangup() perform opposite lifecycle roles in a common call flow. Answer() accepts an incoming channel before media is delivered in many ordinary flows. Its basic form also takes no arguments:

Answer()

Answer() is call setup or media acceptance. Hangup() is call teardown:

Answer() — Accepts the call; no arguments in the basic form; commonly near the beginning; makes the channel ready for the intended answered-call media flow.

Playback() — Plays a specified audio prompt; the basic example supplies a prompt name; commonly after Answer(); normally does not by itself express that the call must end.

Background() — Plays audio while allowing digit collection; commonly used for an interactive menu; should be followed by input and routing logic rather than an unconditional immediate hangup.

Hangup() — Ends the active call; takes no arguments in its basic form; normally the final action in a terminal extension; terminates the channel and prevents later call-flow processing.

Playback(), Background(), and caller interaction

Playback() is appropriate for a non-interactive announcement. It plays the specified prompt, but completing that prompt does not necessarily terminate the call. If the caller should be disconnected after the announcement, follow Playback() with Hangup().

same => n,Answer()
same => n,Playback(service-is-currently-unavailable)
same => n,Hangup()

Background() is relevant when the caller should be able to enter digits while audio is playing. A menu that expects a choice should use an input-capable flow and route the selected digit. Do not place an unconditional Hangup() immediately after the menu prompt unless every possible path is intentionally terminal.

[main-menu]
exten => 700,1,Answer()
 same => n,Background(please-enter-your-choice)
 ; Route received digits here.
 ; Hangup only on a branch that is truly finished.

Choosing the right endpoint

Use Hangup() immediately after an announcement when the destination is a terminal informational extension. Examples include a closed department message, a service-unavailable notice, or a recording that gives the caller all required information.

Do not use Hangup() yet when the flow must:

  • Collect digits from the caller.
  • Present an interactive menu.
  • Transfer or route the caller elsewhere.
  • Bridge the caller to an agent, queue, or other channel.
  • Return to another intentional dialplan path.

The rule is simple: use Hangup() only after no additional caller interaction or routing is intended.

Informational announcement — Playback() followed by Hangup(); yes, when the message is complete; the destination is a terminal notice.

Digit-collection menu — Background() and digit-routing logic; no, not before the caller can choose; input must be accepted and routed first.

Call transfer or routing — A transfer or routing application; no, unless the selected branch has completed; the call still has a destination decision to execute.

Call bridging — A dialing or bridging flow; no, while the caller should remain connected; the bridge or connected parties own the active conversation.

Final disconnect — Hangup(); not applicable; the action itself is the deliberate endpoint.

Annotated minimal example

[example-announcement]                         ; Context
exten => 999,1,Answer()                        ; Extension 999, priority 1
 same => n,Playback(service-is-unavailable)    ; Play the final message
 same => n,Hangup()                             ; Terminal action

The context groups the rule, the extension identifies the destination, and the priorities define the order. The last line is not another step in a continuing conversation; it ends the channel.

Troubleshooting

The call remains connected after an announcement finishes

  • Likely cause: The media application was not followed by an intended terminal action.
  • Likely cause: The dialplan continues to another priority or routing path.
  • Resolution: Review the extension's priority sequence and add Hangup() after the final intended action when the call should end.

The caller is disconnected before choosing a menu option

  • Likely cause: Hangup() was placed directly after the menu prompt.
  • Likely cause: A non-interactive announcement pattern was used for an interactive requirement.
  • Resolution: Move Hangup() to a true terminal branch and use an input-capable menu and digit-routing flow first.

Expected later dialplan steps do not run

  • Likely cause: Hangup() was inserted before those steps.
  • Likely cause: The flow was designed as though Hangup() returns to the next priority.
  • Resolution: Treat Hangup() as terminal and reorder all required actions so they execute before it.

Summary

  • Hangup() terminates the channel handling the active call.
  • Its basic syntax is Hangup(), with no arguments.
  • Place it after the final intended action in a terminal extension.
  • Answer() accepts the call; Playback() delivers audio; Background() supports audio with digit input; Hangup() ends the call.
  • Do not hang up immediately when the caller still needs to select, transfer, bridge, or otherwise continue through the dialplan.

For related call-flow concepts, see Asterisk call termination with Hangup().