Asterisk variable hangupcause

Hangupcause is the latest PRI hangup return code on an Asterisk ZAP channels channel connected to a PRI interface. Note that this also works on SIP channels, maybe other channels as well.

Tip: The packet isdnutils contains a utility called isdncause that provides a textual explanation of the error number that you feed it with (watch the entry format).

For CVS head releases after 2004-08-12:

Note: This does not work in 0.7.1 (maybe other versions) See: https://issues.asterisk.org/jira/browse/ASTERISK-884

Recommended SIP <-> ISDN Cause codes (from RFC3398)

Note: Asterisk 1.8 will allow to read SIP response codes in the dialplan via

${HASH(SIP_CAUSE,<channel-name>)}

So slave SIP channels now set HASH(SIP_CAUSE,<slave-channel-name>) on each response. This permits the master channel to know how each channel dialed in a multi-channel setup resolved in an individual way.

Asterisk 1.8 also comes with a ‘use_q850_reason’ configuration option for generating and parsing, if available:

Reason: Q.850;cause=<cause code>

It is implemented in some gateways for better passing PRI/SS7 cause codes via SIP.

Tilghman: “The only reason we implemented the passing back of the raw SIP code in the dialplan is that the conversion to cause is lossy. That is, several SIP status codes all map back to a single ISUP cause code, and there are legitimate reasons for wanting to know which status code was received. What SHOULD happen is that if use_q850_reason is set, then the cause sent to the core should simply be the cause code in this new SIP header (“Reason: …”), which you should be able to read in ${HANGUPCAUSE}.”

The destination channel dies right after your Dial statement exits, but you can retrieve the info in the channel that’s still alive :

exten => _XXX,n,Dial(SIP/${EXTEN})
exten => _XXX,n,NoOp(SIP return code : ${HASH(SIP_CAUSE,${CDR(dstchannel)})})

Just as there are certain ISDN cause codes that are ISUP-specific and have no corollary SIP action, so there are SIP status codes that should not simply be translated to ISUP – some SIP-specific action should be attempted first. See the note on the (+) tag below.

Response received Cause value in the REL

400 Bad Request 41 Temporary Failure
401 Unauthorized 21 Call rejected (*)
402 Payment required 21 Call rejected
403 Forbidden 21 Call rejected
404 Not found 1 Unallocated number
405 Method not allowed 63 Service or option unavailable
406 Not acceptable 79 Service/option not implemented (+)
407 Proxy authentication required 21 Call rejected (*)
408 Request timeout 102 Recovery on timer expiry
410 Gone 22 Number changed (w/o diagnostic)
413 Request Entity too long 127 Interworking (+)
414 Request-URI too long 127 Interworking (+)
415 Unsupported media type 79 Service/option not implemented (+)
416 Unsupported URI Scheme 127 Interworking (+)
420 Bad extension 127 Interworking (+)
421 Extension Required 127 Interworking (+)
423 Interval Too Brief 127 Interworking (+)
480 Temporarily unavailable 18 No user responding
481 Call/Transaction Does not Exist 41 Temporary Failure
482 Loop Detected 25 Exchange – routing error
483 Too many hops 25 Exchange – routing error
484 Address incomplete 28 Invalid Number Format (+)
485 Ambiguous 1 Unallocated number
486 Busy here 17 User busy
487 Request Terminated — (no mapping)
488 Not Acceptable here — by Warning header
500 Server internal error 41 Temporary failure
501 Not implemented 79 Not implemented, unspecified
502 Bad gateway 38 Network out of order
503 Service unavailable 41 Temporary failure
504 Server time-out 102 Recovery on timer expiry
504 Version Not Supported 127 Interworking (+)
513 Message Too Large 127 Interworking (+)
600 Busy everywhere 17 User busy
603 Decline 21 Call rejected
604 Does not exist anywhere 1 Unallocated number
606 Not acceptable — by Warning header

(*) In some cases, it may be possible for a SIP gateway to provide credentials to the SIP UAS that is rejecting an INVITE due to authorization failure. If the gateway can authenticate itself, then obviously it SHOULD do so and proceed with the call; only if the gateway cannot authenticate itself should cause code 21 be sent.

(+) If at all possible, a SIP gateway SHOULD respond to these protocol errors by remedying unacceptable behavior and attempting to re-originate the session. Only if this proves impossible should the SIP gateway fail the ISUP half of the call.

When the Warning header is present in a SIP 606 or 488 messages, there may be specific ISDN cause code mappings appropriate to the Warning code. This document recommends that ’31 Normal, unspecified’ SHOULD by default be used for most currently assigned Warning codes. If the Warning code speaks to an unavailable bearer capability, cause code ’65 Bearer Capability Not Implemented’ is a RECOMMENDED mapping.

Set(CDR(userfield)=Hangupcause:${HANGUPCAUSE})

Set(CDR(userfield)=${CDR(userfield)} Hangupcause:${HANGUPCAUSE})

[7-digit-PRI-Machine-2] ; The machine connected to PRI 2 (on its g1)
exten => _9NXXXXXX,1,Dial(Zap/g1/${EXTEN:1})
exten => _9NXXXXXX,2,gotoif,$[${HANGUPCAUSE} = 2]?99999|1
exten => 99999,1,Busy

 [default]
 exten => 91NXXNXXXXXX,1,Dial(${PSTN}/${EXTEN:1}
 exten => 91NXXNXXXXXX,2,Macro(dial-result,${NUFONE}/${EXTEN:1})

 [macro-dial-result]
 ;
 ; Handle Disconnect Cause Codes
 ;
 exten => s,1,NoOp(HANGUPCAUSE is ${HANGUPCAUSE})
 exten => s,2,AbsoluteTimeout(120)
 exten => s,3,Goto(${HANGUPCAUSE},1)
                                                                           
 exten => 0,1,NoOp(AST_CAUSE_NOTDEFINED)
 exten => 0,2,GoToIf($["${SAVED_EXTEN}" != ""]?0,4)
 exten => 0,3,SetVar(SAVED_EXTEN=${MACRO_EXTEN})
 exten => 0,4,GoToIf($["${SAVED_ARG1}" != ""]?0,6)
 exten => 0,5,SetVar(SAVED_ARG1=${ARG1})
 exten => 0,6,GoToIf($["${ARG1}" = ""]?0,11)
 exten => 0,7,System(/bin/echo AST_CAUSE_NOTDEFINED received when dialing ${SAVED_EXTEN}.  Trying again using ${SAVED_ARG1}.  | /usr/bin/mutt -s "COLISEUM PBX ERROR" pbxadmin-pager@)
 exten => 0,8,SetVar(ARG1=)
 exten => 0,9,Dial(${SAVED_ARG1})
 exten => 0,10,Macro(dial-result)
 exten => 0,11,System(/bin/echo AST_CAUSE_NOTDEFINED received when dialing ${SAVED_ARG1}.  Giving up. | /usr/bin/mutt -s "COLISEUM PBX ERROR" pbxadmin-pager)
 exten => 0,12,Zapateller(answer)
 exten => 0,13,Playback(an-error-has-occured)
 exten => 0,14,Playback(pls-try-call-later)
 exten => 0,15,Wait(3)
 exten => 0,16,Zapateller(answer)
 exten => 0,17,Playback(an-error-has-occured)
 exten => 0,18,Playback(pls-try-call-later)
 exten => 0,19,Wait(3)
 exten => 0,20,Congestion

 [handling of other cause codes removed for brevity]

Example 3: Macro for handling hangupcause

[macro-dial-result]
; Handles Disconnect Cause Codes
; @param ${ARG1} - cause code (optional - will try to use DIALSTATUS or HANGUPCAUSE if not set)
; @usage exten => s,1,Macro(dial-result| __CAUSECODE__ )

exten => s,1,Wait(1)
exten => s,2,ResetCDR(w)
exten => s,3,NoCDR()
exten => s,4,GotoIf($[${ISNULL(${ARG1})}]?7:5)
exten => s,5,Set(RC=${ARG1})
exten => s,6,Goto(s|9)
exten => s,7,GotoIf($[${ISNULL(${DIALSTATUS})}]?8:rc-${DIALSTATUS}|1)
exten => s,8,Set(RC=${IF($[${ISNULL(${HANGUPCAUSE})}]?0:${HANGUPCAUSE})})
exten => s,9,Goto(rc-${RC}|1)
exten => s,10,Hangup(${RC})
exten => i,1,Set(RC=0)
exten => i,2,Goto(s|9)

;; remap DIALSTATUS to HANGUPCAUSE
exten => rc-ANSWER,1,Set(RC=16)
exten => rc-ANSWER,2,Goto(s|9)

exten => rc-BUSY,1,Set(RC=17)
exten => rc-BUSY,2,Goto(s|9)

exten => rc-CANCEL,1,Set(RC=16)
exten => rc-CANCEL,2,Goto(s|9)

exten => rc-CHANUNAVAIL,1,Set(RC=44)
exten => rc-CHANUNAVAIL,2,Goto(s|9)

exten => rc-CONGESTION,1,Set(RC=34)
exten => rc-CONGESTION,2,Goto(s|9)

exten => rc-NOANSWER,1,Set(RC=19)
exten => rc-NOANSWER,2,Goto(s|9)

;; HANGUPCAUSE mapping
exten => rc-0,1,NoOp(NOTDEFINED)
exten => rc-0,n,Goto(s|10)

exten => rc-1,1,NoOp(UNALLOCATED)
exten => rc-1,n,Goto(s|10)

exten => rc-2,1,NoOp(NO_ROUTE_TRANSIT_NET)
exten => rc-2,n,Goto(s|10)

exten => rc-3,1,NoOp(NO_ROUTE_DESTINATION)
exten => rc-3,n,Goto(s|10)

exten => rc-6,1,NoOp(CHANNEL_UNACCEPTABLE)
exten => rc-6,n,Goto(s|10)

exten => rc-7,1,NoOp(CALL_AWARDED_DELIVERED)
exten => rc-7,n,Goto(s|10)

exten => rc-16,1,NoOp(NORMAL_CLEARING)
exten => rc-16,n,Goto(s|10)

exten => rc-17,1,NoOp(USER_BUSY)
exten => rc-17,n,Busy() ; we need this for bristuff, because bristuff seems not to support Hangup(17)
exten => rc-17,n,Goto(s|10)

exten => rc-18,1,NoOp(NO_USER_RESPONSE)
exten => rc-18,n,Goto(s|10)

exten => rc-19,1,NoOp(NO_ANSWER)
exten => rc-19,n,Goto(s|10)

exten => rc-21,1,NoOp(CALL_REJECTED)
exten => rc-21,n,Goto(s|10)

exten => rc-22,1,NoOp(NUMBER_CHANGED)
exten => rc-22,n,Goto(s|10)

exten => rc-27,1,NoOp(DESTINATION_OUT_OF_ORDER)
exten => rc-27,n,Goto(s|10)

exten => rc-28,1,NoOp(INVALID_NUMBER_FORMAT)
exten => rc-28,n,Goto(s|10)

exten => rc-29,1,NoOp(FACILITY_REJECTED)
exten => rc-29,n,Goto(s|10)

exten => rc-30,1,NoOp(RESPONSE_TO_STATUS_ENQUIRY)
exten => rc-30,n,Goto(s|10)

exten => rc-31,1,NoOp(NORMAL_UNSPECIFIED)
exten => rc-31,n,Goto(s|10)

exten => rc-34,1,NoOp(NORMAL_CIRCUIT_CONGESTION)
exten => rc-34,n,Congestion() ; we need this for bristuff, because bristuff seems not to support Hangup(34)
exten => rc-34,n,Goto(s|10)

exten => rc-38,1,NoOp(NETWORK_OUT_OF_ORDER)
exten => rc-38,n,Goto(s|10)

exten => rc-41,1,NoOp(NORMAL_TEMPORARY_FAILURE)
exten => rc-41,n,Goto(s|10)

exten => rc-42,1,NoOp(SWITCH_CONGESTION)
exten => rc-42,n,Goto(s|10)

exten => rc-43,1,NoOp(ACCESS_INFO_DISCARDED)
exten => rc-43,n,Goto(s|10)

exten => rc-44,1,NoOp(REQUESTED_CHAN_UNAVAIL)
exten => rc-44,n,Goto(s|10)

exten => rc-45,1,NoOp(PRE_EMPTED)
exten => rc-45,n,Goto(s|10)

exten => rc-50,1,NoOp(FACILITY_NOT_SUBSCRIBED)
exten => rc-50,n,Goto(s|10)

exten => rc-52,1,NoOp(OUTGOING_CALL_BARRED)
exten => rc-52,n,Goto(s|10)

exten => rc-54,1,NoOp(INCOMING_CALL_BARRED)
exten => rc-54,n,Goto(s|10)

exten => rc-57,1,NoOp(BEARERCAPABILITY_NOTAUTH)
exten => rc-57,n,Goto(s|10)

exten => rc-58,1,NoOp(BEARERCAPABILITY_NOTAVAIL)
exten => rc-58,n,Goto(s|10)

exten => rc-65,1,NoOp(BEARERCAPABILITY_NOTIMPL)
exten => rc-65,n,Goto(s|10)

exten => rc-66,1,NoOp(CHAN_NOT_IMPLEMENTED)
exten => rc-66,n,Goto(s|10)

exten => rc-69,1,NoOp(FACILITY_NOT_IMPLEMENTED)
exten => rc-69,n,Goto(s|10)

exten => rc-81,1,NoOp(INVALID_CALL_REFERENCE)
exten => rc-81,n,Goto(s|10)

exten => rc-88,1,NoOp(INCOMPATIBLE_DESTINATION)
exten => rc-88,n,Goto(s|10)

exten => rc-95,1,NoOp(INVALID_MSG_UNSPECIFIED)
exten => rc-95,n,Goto(s|10)

exten => rc-96,1,NoOp(MANDATORY_IE_MISSING)
exten => rc-96,n,Goto(s|10)

exten => rc-97,1,NoOp(MESSAGE_TYPE_NONEXIST)
exten => rc-97,n,Goto(s|10)

exten => rc-98,1,NoOp(WRONG_MESSAGE)
exten => rc-98,n,Goto(s|10)

exten => rc-99,1,NoOp(IE_NONEXIST)
exten => rc-99,n,Goto(s|10)

exten => rc-100,1,NoOp(INVALID_IE_CONTENTS)
exten => rc-100,n,Goto(s|10)

exten => rc-101,1,NoOp(WRONG_CALL_STATE)
exten => rc-101,n,Goto(s|10)

exten => rc-102,1,NoOp(RECOVERY_ON_TIMER_EXPIRE)
exten => rc-102,n,Goto(s|10)

exten => rc-103,1,NoOp(MANDATORY_IE_LENGTH_ERROR)
exten => rc-103,n,Goto(s|10)

exten => rc-111,1,NoOp(PROTOCOL_ERROR)
exten => rc-111,n,Goto(s|10)

exten => rc-127,1,NoOp(INTERWORKING)
exten => rc-127,n,Goto(s|10)
^

See also

• How to set the variable PRI_CAUSE
• Asterisk variable DIALSTATUS
• Asterisk variables: Variables overview
• Asterisk cmd Dial
• Asterisk cmd Hangup
• Asterisk ZAP channels
• Asterisk Alternatives