Asterisk variable hangupcause

Business PBX Solutions
Provider Solution Details
Intuitive Technology
  • Simple and powerful
  • Integrated Multisite Administration
  • Complete System for $1299
Details
3CX Software PBX for Windows
  • Windows Software Solution
  • Easy to Install and Manage
  • Auto Configures Phones & Trunks
  • Android, iOS, Windows & Mac clients
Details
Bicom VoIP Become an ITSP Now!
  • Become a serious competitor in VoIP Immediately
  • FULL Consultancy, Installation, Training & Support
  • Sell Hosted IP PBXs, Biz Lines, Call Centre
  • Turnkey Provisioning at your data center
Details
4PSA's VoipNow Cloud Communications Platform
  • 30 Day Free Trial - Pay-As-You-Grow!
  • Your fastest go-to-market solution - from deployment to billing.
  • Professional support, training and knowledge base to help you grow your business
  • On your infrastructure or cloud-based, it's up to you.
Details

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:
  1. define AST_CAUSE_NOTDEFINED 0
  2. define AST_CAUSE_NORMAL 1
  3. define AST_CAUSE_BUSY 2
  4. define AST_CAUSE_FAILURE 3
  5. define AST_CAUSE_CONGESTION 4
  6. define AST_CAUSE_UNALLOCATED 5


For CVS head releases after 2004-08-12:

/* Causes for disconnection (from Q.931) */
  1. define AST_CAUSE_UNALLOCATED 1
  2. define AST_CAUSE_NO_ROUTE_TRANSIT_NET 2
  3. define AST_CAUSE_NO_ROUTE_DESTINATION 3
  4. define AST_CAUSE_CHANNEL_UNACCEPTABLE 6
  5. define AST_CAUSE_CALL_AWARDED_DELIVERED 7
  6. define AST_CAUSE_NORMAL_CLEARING 16
  7. define AST_CAUSE_USER_BUSY 17
  8. define AST_CAUSE_NO_USER_RESPONSE 18
  9. define AST_CAUSE_NO_ANSWER 19
  10. define AST_CAUSE_CALL_REJECTED 21
  11. define AST_CAUSE_NUMBER_CHANGED 22
  12. define AST_CAUSE_DESTINATION_OUT_OF_ORDER 27
  13. define AST_CAUSE_INVALID_NUMBER_FORMAT 28
  14. define AST_CAUSE_FACILITY_REJECTED 29
  15. define AST_CAUSE_RESPONSE_TO_STATUS_ENQUIRY 30
  16. define AST_CAUSE_NORMAL_UNSPECIFIED 31
  17. define AST_CAUSE_NORMAL_CIRCUIT_CONGESTION 34
  18. define AST_CAUSE_NETWORK_OUT_OF_ORDER 38
  19. define AST_CAUSE_NORMAL_TEMPORARY_FAILURE 41
  20. define AST_CAUSE_SWITCH_CONGESTION 42
  21. define AST_CAUSE_ACCESS_INFO_DISCARDED 43
  22. define AST_CAUSE_REQUESTED_CHAN_UNAVAIL 44
  23. define AST_CAUSE_PRE_EMPTED 45
  24. define AST_CAUSE_FACILITY_NOT_SUBSCRIBED 50
  25. define AST_CAUSE_OUTGOING_CALL_BARRED 52
  26. define AST_CAUSE_INCOMING_CALL_BARRED 54
  27. define AST_CAUSE_BEARERCAPABILITY_NOTAUTH 57
  28. define AST_CAUSE_BEARERCAPABILITY_NOTAVAIL 58
  29. define AST_CAUSE_BEARERCAPABILITY_NOTIMPL 65
  30. define AST_CAUSE_CHAN_NOT_IMPLEMENTED 66
  31. define AST_CAUSE_FACILITY_NOT_IMPLEMENTED 69
  32. define AST_CAUSE_INVALID_CALL_REFERENCE 81
  33. define AST_CAUSE_INCOMPATIBLE_DESTINATION 88
  34. define AST_CAUSE_INVALID_MSG_UNSPECIFIED 95
  35. define AST_CAUSE_MANDATORY_IE_MISSING 96
  36. define AST_CAUSE_MESSAGE_TYPE_NONEXIST 97
  37. define AST_CAUSE_WRONG_MESSAGE 98
  38. define AST_CAUSE_IE_NONEXIST 99
  39. define AST_CAUSE_INVALID_IE_CONTENTS 100
  40. define AST_CAUSE_WRONG_CALL_STATE 101
  41. define AST_CAUSE_RECOVERY_ON_TIMER_EXPIRE 102
  42. define AST_CAUSE_MANDATORY_IE_LENGTH_ERROR 103
  43. define AST_CAUSE_PROTOCOL_ERROR 111
  44. define AST_CAUSE_INTERWORKING 127
/* Special Asterisk aliases */
  1. define AST_CAUSE_BUSY AST_CAUSE_USER_BUSY
  2. define AST_CAUSE_FAILURE AST_CAUSE_NETWORK_OUT_OF_ORDER
  3. define AST_CAUSE_NORMAL AST_CAUSE_NORMAL_CLEARING
  4. define AST_CAUSE_NOANSWER AST_CAUSE_NO_ANSWER
  5. define AST_CAUSE_CONGESTION AST_CAUSE_NORMAL_CIRCUIT_CONGESTION
  6. 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>)}

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


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: Sun 24 of Jun, 2012 (20:36 UTC) by admin


Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+

Page Changes | Comments

 

Featured -

Search: