VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk PJSIPHangup: return one final SIP response safely

Place one explicit 4xx, 5xx or 6xx final response on the incoming PJSIP transaction before answer, then keep SIP, translated cause and caller outcome separate.

Reviewed 2026-10-14Current Asterisk branch 23 PJSIPHangup and Hangup application documentation, hangup-cause inspection and mapping guidance, and RFC 3261 reviewed October 14, 2026; PJSIPHangup is documented since Asterisk 18.21.0, 20.6.0 and 21.1.0, accepts a numeric 400 through 699 response or supported PJSIP response name, must run on an incoming PJSIP channel before any other final response, terminates dialplan execution and maps the selected SIP response into an Asterisk or ISDN cause, while installed release, loaded channel driver, channel direction, prior provisional or final responses, transaction state, mapping, upstream rewriting and caller behavior remain deployment specific; no PBX, module, dialplan, channel, request, response, cause, packet, endpoint, trunk or call was inspected or testedAdvancedDocumentation based · not lab tested

Confirm version, application and incoming channel ownership

Asterisk documents PJSIPHangup() on maintenance floors 18.21.0, 20.6.0 and 21.1.0. Confirm the installed full release, loaded chan_pjsip support, dialplan source and exact current channel before using it. The application is for an incoming PJSIP channel; a caller channel, callee created by Dial(), Local-channel half and bridge peer are not interchangeable.

Keep generated FreePBX dialplan under its supported owner. A custom context or destination can call the application only after the management boundary and upgrade behavior are explicit.

Select one documented response code or supported name

PJSIPHangup(Cause) accepts a numeric SIP response from 400 through 699 or a supported PJSIP response name. Record the exact policy condition, numeric wire result and caller-facing meaning. A symbolic name from the bundled PJSIP definitions is a software identifier, not a portable carrier contract or an authorization decision by itself.

Use the narrowest response justified by the observed condition and policy. Do not copy a rare example code into production merely because the application accepts it; peer behavior, retry policy, failover and user presentation must be evaluated for the selected response.

Run before anything sends another final response

The application must execute before anything that sends a final non-1xx response. Asterisk explicitly warns that Answer() or Playback() without noanswer sends 200 OK first. Once the INVITE transaction has a final response, a later dialplan request cannot replace it with another final response.

Preserve the call path from INVITE through provisional messages and the first final response. Ringing() or 183 evidence is not the same as a final response, while an application that implicitly answers can cross the boundary without an obvious Answer() line nearby.

Expect dialplan termination and design cleanup separately

Like Hangup(), PJSIPHangup() terminates dialplan execution. Statements after it are not a continuation branch. Put evidence capture and policy selection before the call, and use documented hangup handlers for bounded teardown work when necessary.

A hangup handler has its own channel stack and timing constraints; it is not a safe place to rewrite a final INVITE response after answer. Keep response selection, dialplan termination, teardown actions and downstream reporting as different stages.

Keep the SIP response and translated cause distinct

Asterisk says the selected PJSIP response is translated to a standard cause using its ast_sip_hangup_sip2cause() mapping. The published table shows that several SIP responses can map to one Asterisk or Q.850 cause and that generic 4xx, 5xx and 6xx ranges cover responses not listed individually. Translation is therefore many-to-one evidence, not proof of the exact wire code.

Use the captured SIP response for transaction truth. Use HANGUPCAUSE_KEYS() and HANGUPCAUSE(channel,tech|ast) when per-called-channel cause evidence is required. Do not infer a specific response, responsible leg or human reason from the translated cause alone.

Test policy, wire response and caller behavior independently

For each authorized scenario, preserve the matched dialplan condition, current channel, provisional history, first final response, translated cause, upstream changes and caller behavior. Test retry, failover, announcement and reporting expectations without assuming that every provider or endpoint treats one response identically.

Change only the demonstrated owner: policy condition, channel placement, answer timing, selected response or upstream normalization. Retest the negative path and a permitted-call control. No host, module, dialplan, channel, SIP transaction, packet or caller outcome was tested for this guide.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

Asterisk

Understand the programmable PBX and follow the Asterisk 22 LTS documentation baseline.

Explore topic →
Guide · Asterisk 22 LTS

Asterisk PJSIP: understand the configuration objects

Connect endpoint behavior, authentication, contacts and transport without collapsing them into one account setting.

Read guide →
Guide · Asterisk 22 LTS

Asterisk dialplan: contexts, patterns and loaded-call evidence

Build a restricted Asterisk 22 call path, then prove its context, match, priorities and runtime behavior separately.

Read guide →
Guide · Current Asterisk branch-23-generated HANGUPCAUSE, HANGUPCAUSE_KEYS, HangupCauseClear, Dial and CHANNEL references plus the project mapping table reviewed October 6, 2026; exact behavior still depends on the installed Asterisk branch, channel driver, dialplan and call path

Asterisk hangup causes: preserve each called-channel result

Interpret Dial status, per-channel technology causes, translated Asterisk causes and hangup source without collapsing parallel or sequential call attempts into one reason.

Read guide →
Guide · Asterisk hangup-handler, CHANNEL, AMI event, hangup-cause and Return documentation reviewed October 12, 2026; exact events and channel behavior remain dependent on the installed Asterisk branch, modules, dialplan, channel technology and observer permissions, and no PBX, dialplan, channel, handler stack, event, record, endpoint, call or teardown path was inspected or tested

Asterisk hangup handlers: channel stack, order and teardown evidence

Attach bounded hangup subroutines to the correct channel, preserve LIFO stack order and prove push, pop, run and final hangup separately.

Read guide →
Hub

SIP response codes

Interpret a SIP status in the context of its method, transaction and the system that sent it.

Explore topic →
Guide · Current Asterisk logging, runtime command, logger.conf, debug-collection, call-identifier and console-verbosity documentation reviewed September 30, 2026; no process, logger, trace, storage path or call tested

Asterisk logging without permanent debug overload

Map configured destinations, console levels, call identifiers and a bounded protocol trace without leaving sensitive debug collection active.

Read guide →
Guide · Wireshark 4.x / current upstream tool documentation; inspect installed versions

VoIP packet-capture methodology

Select interfaces, time windows and paired capture points that distinguish network loss from missing evidence.

Read guide →
Diagnostic · Current Asterisk branch 23 PJSIPHangup and Hangup application documentation, hangup-cause inspection and mapping guidance, and RFC 3261 reviewed October 14, 2026; PJSIPHangup is documented since Asterisk 18.21.0, 20.6.0 and 21.1.0, accepts a numeric 400 through 699 response or supported PJSIP response name, must run on an incoming PJSIP channel before any other final response, terminates dialplan execution and maps the selected SIP response into an Asterisk or ISDN cause, while installed release, loaded channel driver, channel direction, prior provisional or final responses, transaction state, mapping, upstream rewriting and caller behavior remain deployment specific; no PBX, module, dialplan, channel, request, response, cause, packet, endpoint, trunk or call was inspected or tested

Asterisk PJSIPHangup returns the wrong response or 200 was already sent

Find the first final SIP response, prove the current channel and application availability, then correct one policy or timing owner without rewriting evidence after answer.

Read guide →