h1. Dial

{{>toc}}

!dial3.gif!

This is the mostly used application.
It allows to dial out and bridge caller with any other peer.

h2. _Arguments_

h3. Resources.

!dial4.gif!

*technology* - technology for outbound call.
In case if you set "auto", system will choose the most suitable technology from the list of configured on a peer.
The most suitable will be a technology, which allows to generate a call without signalling protocols conversion.
*peer* - is a peer name. You can set here a name of a user, gateway or terminator.
*called ID* - B-number, which will be used to generate outbound call. To replace А-number use instruction: [[Caller ID replacement]]
*dial string* - description of a dialed peer using single string, for example _SIP/Ann/101_. 
This field by default contains variable _${DIALSTRING}_. 
This variable is set by [[Softswitch]] application before performing outbound call.

*Attention!* When supplying simultaneously fields *dial string* and specifying peer list application will be highlighted with red, which signalizes about ambiguity in configuration.
System won't know which of the settings to take to perform outbound call.
Therefore system won't let to save this configuration.

h3. Options

!dial5.gif!

*timedout (sec)* - after which time to cancel outgoing call, if there was no answer during this time
*PDD timeout (ms)* - after which time to cancel outbound call, if no messages have been received from a peer in response to outgoing call attempt.
*announcement file for callee* - before bridging the named audio file is played to callee (specify file name without extension)
*music on hold class* - music on hold class, which is used in scenarios, where there is a holding, for example, [[VAS]] [[Call transfer]]

*allow jump to extension while waiting for answer* - caller can dial 1-digit extension while system places outbound call.
After this, in case if matching [[Pattern extension]] exists in current [[Call handler]] - system will cancel call generation and will switch to a specified branch.
Pay attention, many of SIP phones doesn't allow to send DTMF, if there was no answer.
To support such phones use application [[Answer]] before invoking [[Dial]].
However be prepared to billing issues, because in this case inbound call will be billed even if outbound call hasn't been answered.

*DTMF string for caller* - after bridging system sends specified string as DTMF to caller.
*DTMF string for callee* - after bridging system sends specified string as DTMF to callee.
This could be used for automatic PIN code dialing when terminating a call through IVR system (in case if supplier with [[Calling cards]] platform is used as terminator).

*allow caller to hangup with ** - while connected, caller can hangup by pressing DTMF '*'
*allow callee to hangup with ** - while connected, callee can hangup by pressing DTMF '*'

*ignore forwarding requests* - callee may attempt to perform forwarding (for example, using method SIP Moved Temporary).
This option ignores this message.

*indicate ringing to caller* - for terminators with issues, which incorrectly generate ring-back tones (or doesn't generate at all), this option launches mode of ring-back tones generation by a system.
*allow caller to transfer* - caller can activate [[VAS]] [[Call transfer]] by DTMF combination.
*allow callee to transfer* - callee can activate [[VAS]] [[Call transfer]] by DTMF combination.
*allow caller to trigger recording* - caller can activate [[VAS]] [[Call recording]] by DTMF combination.
*allow callee to trigger recording* - callee can activate [[VAS]] [[Call recording]] by DTMF combination.

h3. Call limits

!dial7.gif!

h3. Debug

!dial8.gif!

*signaling capture* - perform [[Call capturing]] for signaling
*media capture* - perform [[Call capturing]] for media streams

h2. _Call forking_

You can configure dialing of more than one peer.
In this case all of them will be dialed simultaneously in parallel.
The first who answers will be bridged with caller.
All other will be hanged up immediately.

!dial6.gif!

h2. _Status variables_

On exit, this application sets variable *DIALSTATUS* to one of the following values:

*CHANUNAVAIL* - can't create outbound channel. This happens, if:
 - for VoIP [[Technologies]] IP address of terminating peer is not specified
 - SIP peer has unregistered or hasn't registered
 - channel driver has returned code AST_CAUSE_NO_ROUTE_DESTINATION
 - in case if none of the conditions specified below hasn't activated
*CONGESTION* - happens, if channel driver returns code AST_CAUSE_CONGESTION
*NOANSWER* - happens, if channel driver returns code AST_CAUSE_NO_ANSWER
*BUSY* - happens, if channel driver returns code AST_CAUSE_BUSY
*ANSWER* - happens, if callee has answered
*CANCEL* - happens, if caller has cancelled a call
*DONTCALL* - for modes [[Privacy]] и [[Screening]]. It's set on corresponding decision and action of callee.
*TORTURE* - for modes [[Privacy]] и [[Screening]]. It's set on corresponding decision and action of callee.
*INVALIDARGS* - wrong arguments have been passed to application

h2. Conversion of return codes between various protocols

See section [[Correspondence of return codes SIP_Asterisk_Q.931|Correspondence of return codes SIP/Asterisk/Q.931]] to get actual return codes for VoIP protocols that correspond to AST_CAUSE_XXX.

[[Набрать|Русский перевод]]