Asterisk hangup causes: preserve each called-channel result

Start with one call and every attempted channel

A failed business call can create no outbound channel, one called channel, several channels in parallel, or a sequence of separate attempts. Preserve the timestamp, linked identifier, calling channel, every called-channel name and the order in which attempts were created before interpreting one final value. A trunk label, destination number or CDR row is not a substitute for the channel instance that owns a cause.

Asterisk documents HANGUPCAUSE_KEYS() as the list of channels for which hangup-cause information is available after dialing. Iterate that list and retain the original channel name with each value. If the list is empty, first ask whether a called channel was ever created and whether the evidence was read at a point where the cause data still existed; do not convert an empty list into normal clearing or carrier success.

Keep DIALSTATUS at its application-summary level

Dial() sets DIALSTATUS to application outcomes such as CHANUNAVAIL, CONGESTION, NOANSWER, BUSY, ANSWER, CANCEL or INVALIDARGS. That summary is useful for dialplan flow, but it does not retain the exact SIP response, responder, channel or transaction. Several wire outcomes can reach the same status, and a parallel call can include losing branches whose results differ from the final application status.

Capture DIALSTATUS once, immediately after the relevant Dial() returns on the channel where the dialplan continues. Keep it next to—not in place of—the per-channel cause list and protocol trace. A successful answer also causes Asterisk to clear other requested channels, so their termination evidence must not be counted automatically as failed customer calls.

Read technology and Asterisk causes as different views

For each key, HANGUPCAUSE(channel,tech) exposes technology-specific cause information and HANGUPCAUSE(channel,ast) exposes Asterisk's translated cause. The translation deliberately normalizes different technologies, which makes cross-channel dialplan handling possible but loses protocol detail. The published table maps SIP 404, 485 and 604 to unallocated cause 1; 486 and 600 to user-busy cause 17; and 488 and 606 to bearer-capability cause 58.

Those many-to-one mappings mean that cause 1 does not prove 404, cause 17 does not prove 486 and cause 58 does not prove 488. Retain the exact SIP response and responder before mapping it to announcements, failover or reporting. The documentation also notes that a cancelled SIP user agent may return no final response, in which case the function can expose the last known technology code rather than a final wire result.

Separate who ended the channel from why it ended

CHANNEL(hangupsource) identifies the channel recorded as responsible for hangup. That is a different question from the technology cause, translated Asterisk cause, DIALSTATUS, application timeout or business interpretation. A caller can end a call after receiving a remote failure; Asterisk can cancel losing parallel branches when another answers; an application can expire a timer; and a remote endpoint can clear an established bridge.

Correlate the source with channel identifiers, application execution, bridge or CEL events and the signaling exchange. Do not infer caller abandonment, carrier rejection, agent behavior or answer quality from hangupsource alone. If the channel topology changed through Local channels, transfers or forwarding, preserve the surviving and replaced identifiers instead of attaching the source to a different leg.

Control cause lifetime across sequential attempts

Asterisk states that HangupCauseClear() removes all stored channel-specific cause information and that new Dial() calls do not clear it automatically. This is useful when a final handler needs the history of several attempts, but it can also mix an earlier failed trunk with a later attempt if reporting assumes only one key exists.

Choose the desired retention contract explicitly. Clear before a new logical attempt only when the earlier result has already been recorded and should not remain in the final set. Keep it when the policy needs the complete attempt history. Never clear merely to make a dashboard look successful, and never interpret the last item in a comma-separated list as the definitive call result without preserving creation order and dialplan logic.

Use the evidence to correct one owner

For an authorized reproduction, record route selection, called-channel creation, DIALSTATUS, every hangup-cause key, its technology and Asterisk values, hangup source, the original SIP messages, and the final business outcome. Protect credentials and personal identifiers, stop protocol logging after the bounded capture, and keep CDR or CEL records as reporting evidence rather than a reconstruction of every transaction.

Repair the demonstrated owner: digits and route when no correct channel was created, reachability or registration when the target is unavailable, identity or authorization when the peer rejects the call, media policy for a proven session mismatch, or capacity only when the provider or PBX supplies capacity evidence. Repeat the same call and the relevant failover path, then confirm the expected response, answer and media. No Asterisk host, dialplan, channel, endpoint, trunk, cause, protocol exchange, CDR, CEL record, failover, capacity state, price, availability or live call was inspected or tested for this guide.

Keep the handler stack separate from the final cause

Use the hangup-handler guide to prove push, pop, run order and return on the owning channel. The final cause and per-dialed-channel causes remain separate evidence rather than a handler-completion receipt.

Keep an explicit PJSIP response separate from its cause mapping

The PJSIPHangup guide starts with the selected wire response and then records the translated Asterisk or Q.850 cause. Multiple SIP codes can map to the same cause, so the cause cannot reconstruct the original transaction.

Preserve per-leg causes beside the final Dial status

The Dial diagnostic correlates each called channel and wire response instead of assigning one final summary to every attempt.

Apply per-leg causes after dial-list construction

The DIALGROUP diagnostic uses HANGUPCAUSE_KEYS and HANGUPCAUSE only after the exact dynamic Dial input is preserved.