Search:
     
3CX Phone System for Windows Download the Free Edition

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)

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

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

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

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

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)})})


  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
  


  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 message, 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.



PRI Hangup Codes


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})

Also: When call is hang up that involves a SIP channel, Asterisk sends the extra SIP headers "X-Asterisk-HangupCause" and "X-Asterisk-HangupCauseCode" in in the BYE message. Do note that SIP_HEADER() gives you only access to headers of the initial INVITE request (i.e. not those of the BYE message).

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.inc

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 complete
usage example. Tested and works with SIP and Asterisk-1.4.13.

See also



Created by: oej,Last modification on Wed 13 of Jul, 2011 [14:14 UTC] by JustRumours


Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - support@voip-info.org

Page Changes | Comments

 





Search: