Asterisk channel variable DIALSTATUS

Contains a text string signifying result of the last Asterisk cmd Dial attempt:

• ANSWER: Call is answered. A successful dial. The caller reached the callee.
• BUSY: Busy signal. The dial command reached its number but the number is busy.
• NOANSWER: No answer. The dial command reached its number, the number rang for too long, then the dial timed out.
• CANCEL: Call is cancelled. The dial command reached its number but the caller hung up before the callee picked up.
• CONGESTION: Congestion. This status is usually a sign that the dialled number is not recognised.
• CHANUNAVAIL: Channel unavailable. On SIP, peer may not be registered.
• DONTCALL: Privacy mode, callee rejected the call
• TORTURE: Privacy mode, callee chose to send caller to torture menu
• INVALIDARGS: Error parsing Dial command arguments (added for Asterisk 1.4.1, SVN r53135-53136)

The dial status may be used in the dialplan to control program flow, see example in Asterisk cmd Goto documentation.

Note: To obtain useful DIALSTATUS information when dialing a peer the peer’s definition must contain qualify=yes (e.g., in sip.conf or iax.conf).

• CONGESTION “Congestion” is somewhat misleading. Unfortunately at this time (2007-05-17), Dial() returns DIALSTATUS=CONGESTION for pretty much every call setup problem. The reason for this is that Dial() is used for multiple protocols (Zap,SIP,IAX etc.) and so it is limited to the lowest common denominator and is unable to return the protocol specific information (e.g., SIP 404 response) .

There is also currently no way to obtain the SIP response in the dialplan, even though it is reported on the debug console (if debug level >3). Even though one can see every other SIP header with ${SIP_HEADER(<header_name>) it is not possible to see the actual response code. However, Asterisk 1.8 allows to read SIP response codes in the dialplan with ${HASH(SIP_CAUSE,<channel-name>)}. Additionally make sure you are using the destination channel, not the source channel. Asterisk 1.8 also comes with a ‘use_q850_reason’ configuration option for generating and parsing, if available, “Reason: Q.850;cause=<cause code>” for better passing PRI/SS7 cause codes via SIP.

There should really be a FAIL result so that it is possible to distinguish between “CONGESTION” and a genuine call setup failure.

Consider the following situations:-

• You have a number of SIP <-> ISDN gateways or service providers which have a finite number of channels. You want the ability to detect genuine congestion so that you can fail over to another channel on another gateway. Asterisk returns CONGESTION for every type of call failure including Congestion, so this is impossible to implement with ${DIALSTATUS}
• Your handset/clients are not capable of displaying the SIP error response to the user, so you need to return inband a tone. For example, Cisco 7960 SIP image unhelpfully displays “Reorder” with the reorder tone “boop, boop, boop, boop” for every SIP call setup problem (not found, congestion etc.) The US “Reorder” tone is not customisable on this handset and it sounds too much like the UK “engaged” (busy) tone. Therefore the user has no way of telling what went wrong.
• You want to provide a more consistent experience rather than relying on the handset to do the right thing with the SIP error code. Answer() before calling Dial() to get asterisk to go in-band and then use Playtones() Wait() to play country specific call progress tones.

${HANGUPCAUSE}

• It may be possible to get a more detailed response by checking the variable ${HANGUPCAUSE}.
• See Asterisk variable hangupcause
• Note: Asterisk 1.8 will allow to read SIP response codes in the dialplan via ${HASH(SIP_CAUSE,<channel-name>)}. Additionally make sure you’re using the destination channel, not the source channel.

Example

This macro is an example of how failover for two or more outgoing trunks can be managed

[macro-safedial]
exten => s,1,Set(DIALSTART=${EPOCH})
;exten => s,n,Dial(${ARG1},${ARG2},g,${ARG4})
exten => s,n,Dial(${ARG1},${ARG2},${ARG3},${ARG4})
exten => s,n,Goto(s-${DIALSTATUS},1)

exten => s-CANCEL,1,Hangup
exten => s-NOANSWER,1,Set(DTIME=$[${EPOCH} - ${DIALSTART}])

watch out

DIALEDTIME can also be empty, next line is not perfect!

;exten => s-NOANSWER,n,GotoIf($["${DIALEDTIME}" = "0"]?here)
exten => s-NOANSWER,n,GotoIf($["${DTIME}" = "0"]?here)
exten => s-NOANSWER,n,Hangup
exten => s-NOANSWER,n(here),Verbose(1,Need failover for "${ARG1}")
exten => s-BUSY,1,Busy
exten => s-CHANUNAVAIL,1,Verbose(1,Need failover for "${ARG1}")
exten => s-CONGESTION,1,Congestion
exten => _s-.,1,Congestion
exten => s-,1,Congestion

The following is an example of a local Zap channel callout with SIP failover (ex. Zap channel is in use)

[macro-localcallout]
exten => s,1,Dial(${ZAP/1/${ARG1},,T)
exten => s,n,NoOp( Dial Status: ${DIALSTATUS})
exten => s,n,Goto(s-${DIALSTATUS},1)

exten => s-NOANSWER,1,Hangup
exten => s-CONGESTION,1,Congestion
exten => s-CANCEL,1,Hangup
exten => s-BUSY,1,Busy
exten => s-CHANUNAVAIL,1,SetCallerId(${CALLERIDNUM})
exten => s-CHANUNAVAIL,2,Dial(SIP/sippeer/${LOCALAREACODE}${ARG1},,T)

See also

• Asterisk cmd Dial
• Asterisk cmd RetryDial
• Asterisk variable hangupcause
• Asterisk variables
• Asterisk cmd Goto
• Asterisk Alternatives

• Asterisk: Home page