Asterisk variable hangupcause
Page Contents
Asterisk variable Hangupcause
Hangupcause is the latest PRI hangup return code on a zap 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).
Previous to CVS 2004-08-12:
From causes.h:
#define AST_CAUSE_NOTDEFINED 0
#define AST_CAUSE_NORMAL 1
#define AST_CAUSE_BUSY 2
#define AST_CAUSE_FAILURE 3
#define AST_CAUSE_CONGESTION 4
#define AST_CAUSE_UNALLOCATED 5
For CVS head releases after 2004-08-12:
/* Causes for disconnection (from Q.931) */
#define AST_CAUSE_UNALLOCATED 1
#define AST_CAUSE_NO_ROUTE_TRANSIT_NET 2
#define AST_CAUSE_NO_ROUTE_DESTINATION 3
#define AST_CAUSE_CHANNEL_UNACCEPTABLE 6
#define AST_CAUSE_CALL_AWARDED_DELIVERED 7
#define AST_CAUSE_NORMAL_CLEARING 16
#define AST_CAUSE_USER_BUSY 17
#define AST_CAUSE_NO_USER_RESPONSE 18
#define AST_CAUSE_NO_ANSWER 19
#define AST_CAUSE_CALL_REJECTED 21
#define AST_CAUSE_NUMBER_CHANGED 22
#define AST_CAUSE_DESTINATION_OUT_OF_ORDER 27
#define AST_CAUSE_INVALID_NUMBER_FORMAT 28
#define AST_CAUSE_FACILITY_REJECTED 29
#define AST_CAUSE_RESPONSE_TO_STATUS_ENQUIRY 30
#define AST_CAUSE_NORMAL_UNSPECIFIED 31
#define AST_CAUSE_NORMAL_CIRCUIT_CONGESTION 34
#define AST_CAUSE_NETWORK_OUT_OF_ORDER 38
#define AST_CAUSE_NORMAL_TEMPORARY_FAILURE 41
#define AST_CAUSE_SWITCH_CONGESTION 42
#define AST_CAUSE_ACCESS_INFO_DISCARDED 43
#define AST_CAUSE_REQUESTED_CHAN_UNAVAIL 44
#define AST_CAUSE_PRE_EMPTED 45
#define AST_CAUSE_FACILITY_NOT_SUBSCRIBED 50
#define AST_CAUSE_OUTGOING_CALL_BARRED 52
#define AST_CAUSE_INCOMING_CALL_BARRED 54
#define AST_CAUSE_BEARERCAPABILITY_NOTAUTH 57
#define AST_CAUSE_BEARERCAPABILITY_NOTAVAIL 58
#define AST_CAUSE_BEARERCAPABILITY_NOTIMPL 65
#define AST_CAUSE_CHAN_NOT_IMPLEMENTED 66
#define AST_CAUSE_FACILITY_NOT_IMPLEMENTED 69
#define AST_CAUSE_INVALID_CALL_REFERENCE 81
#define AST_CAUSE_INCOMPATIBLE_DESTINATION 88
#define AST_CAUSE_INVALID_MSG_UNSPECIFIED 95
#define AST_CAUSE_MANDATORY_IE_MISSING 96
#define AST_CAUSE_MESSAGE_TYPE_NONEXIST 97
#define AST_CAUSE_WRONG_MESSAGE 98
#define AST_CAUSE_IE_NONEXIST 99
#define AST_CAUSE_INVALID_IE_CONTENTS 100
#define AST_CAUSE_WRONG_CALL_STATE 101
#define AST_CAUSE_RECOVERY_ON_TIMER_EXPIRE 102
#define AST_CAUSE_MANDATORY_IE_LENGTH_ERROR 103
#define AST_CAUSE_PROTOCOL_ERROR 111
#define AST_CAUSE_INTERWORKING 127
/* Special Asterisk aliases */
#define AST_CAUSE_BUSY AST_CAUSE_USER_BUSY
#define AST_CAUSE_FAILURE AST_CAUSE_NETWORK_OUT_OF_ORDER
#define AST_CAUSE_NORMAL AST_CAUSE_NORMAL_CLEARING
#define AST_CAUSE_NOANSWER AST_CAUSE_NO_ANSWER
#define AST_CAUSE_CONGESTION AST_CAUSE_NORMAL_CIRCUIT_CONGESTION
#define AST_CAUSE_NOTDEFINED 0
Note: This does not work in 0.7.1 (maybe other versions) See: http://bugs.digium.com/bug_view_page.php?bug_id=0000890
Recommended SIP <-> ISDN Cause codes (from RFC3398):
ISUP Cause value SIP response
---------------- ------------
1 unallocated number 404 Not Found
2 no route to network 404 Not found
3 no route to destination 404 Not found
16 normal call clearing --- (*)
17 user busy 486 Busy here
18 no user responding 408 Request Timeout
19 no answer from the user 480 Temporarily unavailable
20 subscriber absent 480 Temporarily unavailable
21 call rejected 403 Forbidden (+)
22 number changed (w/o diagnostic) 410 Gone
22 number changed (w/ diagnostic) 301 Moved Permanently
23 redirection to new destination 410 Gone
26 non-selected user clearing 404 Not Found (=)
27 destination out of order 502 Bad Gateway
28 address incomplete 484 Address incomplete
29 facility rejected 501 Not implemented
31 normal unspecified 480 Temporarily unavailable
(*) ISDN Cause 16 will usually result in a BYE or CANCEL
(+) If the cause location is 'user' than the 6xx code could be given
rather than the 4xx code (i.e., 403 becomes 603)
(=) ANSI procedure - in ANSI networks, 26 is overloaded to signify
'misrouted ported number'. Presumably, a number portability dip
should have been performed by a prior network. Otherwise cause 26 is
usually not used in ISUP procedures.
A REL with ISDN cause 22 (number changed) might contain information
about a new number where the callee might be reachable in the
diagnostic field. If the MGC is able to process this information it
SHOULD be added to the SIP response (301) in a Contact header.
Resource unavailable
This kind of cause value indicates a temporary failure. A 'Retry-
After' header MAY be added to the response if appropriate.
ISUP Cause value SIP response
---------------- ------------
34 no circuit available 503 Service unavailable
38 network out of order 503 Service unavailable
41 temporary failure 503 Service unavailable
42 switching equipment congestion 503 Service unavailable
47 resource unavailable 503 Service unavailable
Service or option not available
This kind of cause value indicates that there is a problem with the
request, rather than something that will resolve itself over time.
ISUP Cause value SIP response
---------------- ------------
55 incoming calls barred within CUG 403 Forbidden
57 bearer capability not authorized 403 Forbidden
58 bearer capability not presently 503 Service unavailable
available
Service or option not available
ISUP Cause value SIP response
---------------- ------------
65 bearer capability not implemented 488 Not Acceptable Here
70 only restricted digital avail 488 Not Acceptable Here
79 service or option not implemented 501 Not implemented
Invalid message
ISUP Cause value SIP response
---------------- ------------
87 user not member of CUG 403 Forbidden
88 incompatible destination 503 Service unavailable
Protocol error
ISUP Cause value SIP response
---------------- ------------
102 recovery of timer expiry 504 Gateway timeout
111 protocol error 500 Server internal error
Interworking
ISUP Cause value SIP response
---------------- ------------
127 interworking unspecified 500 Server internal error
PRI Hangup Codes
- See ISDN Cause Codes or ISDN Switch Types, Codes, and Values
- For a translation table from ISDN codes to SIP, see RFC 3398
Version notes
- The new version code list that follows Q.931 was implemented in Asterisk CVS head 2004-08-12
Tip
It is good practice to write the cause code into the CDR:Set(CDR(userfield)=Hangupcause:${HANGUPCAUSE})
or
Set(CDR(userfield)=${CDR(userfield)} Hangupcause:${HANGUPCAUSE})
Examples
Example 1
[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
Example 2
[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
Previously posted to the web by 'eric', since withdrawn. However, courtesy of Archive.org, macros.incNote: The above link is broken!
A more complete example from ACaMI's source
[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)
Example 4: Set the hangup cause text to a variable
Please see http://pastebin.ca/794600 for a completeusage example. Tested and works with SIP and Asterisk-1.4.13.
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

Comments
333hangupcause macro?
there should be a link to the "hangupcause" macro that someone made.