Asterisk AMI PJSIPHangup: response code and channel-lifecycle evidence

Version-gate the action before building a control

PJSIPHangup is documented since Asterisk 18.21.0, 20.6.0 and 21.1.0. Confirm the installed maintenance release, loaded chan_pjsip capability and manager action inventory before assuming the action exists. A page from the current branch does not make the action available on an older package.

The AMI form is specialized: it hangs up an incoming PJSIP channel while asking Asterisk to send a selected final SIP response. It is not a generic replacement for every Hangup action, outbound-leg control or established-call teardown.

Select one exact live channel leg

Capture node, manager identity, timestamp, exact Channel, Uniqueid, Linkedid, channel state and bridge membership before acting. Channel names are lifetime handles on one Asterisk system; a linked identifier groups related legs but does not make those legs interchangeable.

Prefer one exact incoming PJSIP channel. Although the action reference documents regular-expression channel syntax, a broad pattern can match more channels than the operator intended. Re-list immediately before a destructive control and authorize the narrowest target.

Preserve the before-final-response timing boundary

Asterisk warns that PJSIPHangup must run before anything has sent another final non-1xx response. Answer() or Playback() without noanswer can already send 200, after which the desired rejection response cannot replace it.

Record the channel state and signaling sequence, not only the dialplan location. Provisional responses, one final response, answered state and later in-dialog teardown are different protocol situations.

Treat the requested SIP response and channel cause separately

The action accepts a numeric SIP response from 400 through 699 or a documented PJSIP response-code name. Asterisk then translates the channel cause through ast_sip_hangup_sip2cause() to a standard ISDN cause.

The requested SIP code, the translated Asterisk cause, Cause-txt and off-nominal TechCause are related but not identical fields. The published mapping groups some response families, so a terminal event cannot always reconstruct the exact response placed on the wire.

Separate action acceptance, request events and terminal disposal

An AMI response confirms that Asterisk accepted or rejected the manager action; it does not by itself prove which final response the peer received. HangupRequest or SoftHangupRequest records a requested transition, while the terminal Hangup event records disposal of one channel and exposes its identifiers and causes.

AMI v2 guarantees that no later events for that Uniqueid follow its Hangup event. If the channel was bridged, BridgeLeave must precede Hangup. Missing events can instead reflect manager read permissions, event filters, a dropped session or observation that began too late.

Verify the network result without broadening the action

For an authorized test, correlate one action ID with the exact pre-action snapshot, response, request event, bridge departure, terminal event and SIP transaction. Confirm the final response at the intended peer separately from the channel cause and application outcome.

Redact caller identity, destination, account codes, channel variables and network addresses before sharing evidence. No PBX, manager action, channel, SIP response, packet, endpoint, media stream or live call was inspected or tested.

Do not substitute a final SIP response for a channel timer

The AMI AbsoluteTimeout guide separates generic channel-lifetime control from PJSIP response selection and final disposal.

Keep generic Hangup distinct from PJSIPHangup

The AMI Hangup guide separates numeric Asterisk causes from the incoming-PJSIP final-response action.