Asterisk Dial () command

What is command and how it works?

One of Asterisk’s most valuable features is its ability to connect different callers to each
other. This is especially useful when callers are using different methods of communication.
For example, caller A might be communicating over the traditional analog
telephone network, while user B might be sitting in a café halfway around the world
and speaking on an IP telephone. Luckily, Asterisk takes most of the hard work out of
connecting and translating between disparate networks. All you have to do is learn how
to use the Dial() application.

The syntax of the Dial() application is a little more complex than that of the other
applications.Dial() takes up to four arguments. The first is the destination you’re attempting to call, which (in its simplest form) is made up of a technology (or transport) across which to make the call, a forward slash, and the remote endpoint or resource. Common technology types include Zap (for analog and T1/E1/J1 channels), SIP, and IAX2. For example, let’s assume that we want to call a Zap endpoint identified by Zap/1, which is an FXS channel with an analog phone plugged into it. The technology is Zap, and the resource is 1. Similarly, a call to a SIP device (as defined in sip.conf) might have a destination of SIP/Jane, and a call to an IAX device (defined in iax.conf) might have a destination of IAX2/Fred. If we wanted Asterisk to ring the Zap/1 channel when extension 123 is reached in the dialplan, we’d add the following extension:

exten => 123,1,Dial(Zap/1)\

We can also dial multiple channels at the same time, by concatenating the destinations
with an ampersand (&), like this:
exten => 123,1,Dial(Zap/1&Zap/2&SIP/Jane)

The Dial() application will ring the specified destinations simultaneously, and bridge
the inbound call with whichever destination channel answers the call first. If the Dial
() application can’t contact any of the destinations, Asterisk will set a variable called
DIALSTATUS with the reason that it couldn’t dial the destinations, and continue on with
the next priority in the extension.

This application sets the following channel variables:

• DIALEDTIME – This is the time from dialing a channel until when it is disconnected.
• ANSWEREDTIME – This is the amount of time for actual call.
• DIALSTATUS – This is the status of the call
  • CHANUNAVAIL
  • CONGESTION
  • NOANSWER
  • BUSY
  • ANSWER
  • CANCEL
  • DONTCALL – For the Privacy and Screening Modes. Will be set if the called party chooses to send the calling party to the ‘Go Away’ script.
  • TORTURE – For the Privacy and Screening Modes. Will be set if the called party chooses to send the calling party to the ‘torture’ script.
  • INVALIDARGS

The Dial() application also allows you to connect to a remote VoIP endpoint not previously
defined in one of the channel configuration files. The full syntax for this type
of connection is:

Dial(technology/user[:password]@remote_host[:port][/remote_extension])

Or

Dial(Technology/Resource&[Technology2/Resource2[&…]],[timeout,[options,[URL]]])

Arguments

• Technology/Resource
  • Technology/Resource – Specification of the device(s) to dial. These must be in the format of Technology/Resource, where Technologyrepresents a particular channel driver, and Resource represents a resource available to that particular channel driver.
  • Technology2/Resource2 – Optional extra devices to dial in parallel
    If you need more then one enter them as Technology2/Resource2&Technology3/Resourse3&…..
• timeout – Specifies the number of seconds we attempt to dial the specified devices
  If not specified, this defaults to 136 years.
• options
  • A – Play an announcement to the called party, where x is the prompt to be played
    • x – The file to play to the called party
  • a – Immediately answer the calling channel when the called channel answers in all cases. Normally, the calling channel is answered when the called channel answers, but when options such as A() and M() are used, the calling channel is not answered until all actions on the called channel (such as playing an announcement) are completed. This option can be used to answer the calling channel before doing anything on the called channel. You will rarely need to use this option, the default behavior is adequate in most cases.
  • b – Before initiating an outgoing call, Gosub to the specified location using the newly created channel. The Gosub will be executed for each destination channel.
    • context
    • exten
    • priority
      • arg1
      • argN
  • B – Before initiating the outgoing call(s), Gosub to the specified location using the current channel.
    • context
    • exten
    • priority
      • arg1
      • argN
  • C – Reset the call detail record (CDR) for this call.
  • c – If the Dial() application cancels this call, always set HANGUPCAUSE to ‘answered elsewhere’
  • d – Allow the calling user to dial a 1 digit extension while waiting for a call to be answered. Exit to that extension if it exists in the current context, or the context defined in the EXITCONTEXT variable, if it exists.
  • D – Send the specified DTMF strings after the called party has answered, but before the call gets bridged. The called DTMF string is sent to the called party, and the calling DTMF string is sent to the calling party. Both arguments can be used alone. If progress is specified, its DTMF is sent immediately after receiving a PROGRESS message.
    • called
    • calling
    • progress
  • e – Execute the h extension for peer after the call ends
  • f – If x is not provided, force the CallerID sent on a call-forward or deflection to the dialplan extension of this Dial() using a dialplan hint. For example, some PSTNs do not allow CallerID to be set to anything other than the numbers assigned to you. If x is provided, force the CallerID sent to x.
    • x
  • F – When the caller hangs up, transfer the called party to the specified destination and start execution at that location.
    • context
    • exten
    • priority
  • F – When the caller hangs up, transfer the called party to the next priority of the current extension and start execution at that location.
  • g – Proceed with dialplan execution at the next priority in the current extension if the destination channel hangs up.
  • G – If the call is answered, transfer the calling party to the specified priority and the called party to the specified priority plus one.
    • context
    • exten
    • priority
  • h – Allow the called party to hang up by sending the DTMF sequence defined for disconnect in features.conf.
  • H – Allow the calling party to hang up by sending the DTMF sequence defined for disconnect in features.conf.
  • i – Asterisk will ignore any forwarding requests it may receive on this dial attempt.
  • I – Asterisk will ignore any connected line update requests or any redirecting party update requests it may receive on this dial attempt.
  • k – Allow the called party to enable parking of the call by sending the DTMF sequence defined for call parking in features.conf.
  • K – Allow the calling party to enable parking of the call by sending the DTMF sequence defined for call parking in features.conf.
  • L – Limit the call to x milliseconds. Play a warning when y milliseconds are left. Repeat the warning every z milliseconds until time expires.
    This option is affected by the following variables:
    • LIMIT_PLAYAUDIO_CALLER – If set, this variable causes Asterisk to play the prompts to the caller.
      • YES default: (true)
      • NO
    • LIMIT_PLAYAUDIO_CALLEE – If set, this variable causes Asterisk to play the prompts to the callee.
      • YES
      • NO default: (true)
    • LIMIT_TIMEOUT_FILE – If specified, filename specifies the sound prompt to play when the timeout is reached. If not set, the time remaining will be announced.
      • FILENAME
    • LIMIT_CONNECT_FILE – If specified, filename specifies the sound prompt to play when the call begins. If not set, the time remaining will be announced.
      • FILENAME
    • LIMIT_WARNING_FILE – If specified, filename specifies the sound prompt to play as a warning when time x is reached. If not set, the time remaining will be announced.
      • FILENAME
    • x – Maximum call time, in milliseconds
    • y – Warning time, in milliseconds
    • z – Repeat time, in milliseconds
  • m – Provide hold music to the calling party until a requested channel answers. A specific music on hold class (as defined in musiconhold.conf) can be specified.
    • class
  • M – Execute the specified macro for the called channel before connecting to the calling channel. Arguments can be specified to the Macro using ^as a delimiter. The macro can set the variable MACRO_RESULT to specify the following actions after the macro is finished executing:
    • MACRO_RESULT – If set, this action will be taken after the macro finished executing.
      • ABORT – Hangup both legs of the call
      • CONGESTION – Behave as if line congestion was encountered
      • BUSY – Behave as if a busy signal was encountered
      • CONTINUE – Hangup the called party and allow the calling party to continue dialplan execution at the next priority
      • GOTO:[[<CONTEXT>^]<EXTEN>^]<PRIORITY> – Transfer the call to the specified destination.
    • macro – Name of the macro that should be executed.
    • arg – Macro arguments
  • n – This option is a modifier for the call screening/privacy mode. (See the p and P options.) It specifies that no introductions are to be saved in thepriv-callerintros directory.
    • delete – With delete either not specified or set to 0, the recorded introduction will not be deleted if the caller hangs up while the remote party has not yet answered.
      With delete set to 1, the introduction will always be deleted.
  • N – This option is a modifier for the call screening/privacy mode. It specifies that if Caller*ID is present, do not screen the call.
  • o – If x is not provided, specify that the CallerID that was present on the calling channel be stored as the CallerID on the called channel. This was the behavior of Asterisk 1.0 and earlier. If x is provided, specify the CallerID stored on the called channel. Note that o(${CALLERID(all)}) is similar to option o without the parameter.
    • x
  • O – Enables operator services mode. This option only works when bridging a DAHDI channel to another DAHDI channel only. if specified on non-DAHDI interfaces, it will be ignored. When the destination answers (presumably an operator services station), the originator no longer has control of their line. They may hang up, but the switch will not release their line until the destination party (the operator) hangs up.
    • mode – With mode either not specified or set to 1, the originator hanging up will cause the phone to ring back immediately.
      With mode set to 2, when the operator flashes the trunk, it will ring their phone back.
  • p – This option enables screening mode. This is basically Privacy mode without memory.
  • P – Enable privacy mode. Use x as the family/key in the AstDB database if it is provided. The current extension is used if a database family/key is not specified.
    • x
  • r – Default: Indicate ringing to the calling party, even if the called party isn’t actually ringing. Pass no audio to the calling party until the called channel has answered.
    • tone – Indicate progress to calling party. Send audio ‘tone’ from indications.conf
  • S – Hang up the call x seconds after the called party has answered the call.
    • x
  • s – Force the outgoing callerid tag parameter to be set to the string x.
    Works with the f option.
    • x
  • t – Allow the called party to transfer the calling party by sending the DTMF sequence defined in features.conf. This setting does not perform policy enforcement on transfers initiated by other methods.
  • T – Allow the calling party to transfer the called party by sending the DTMF sequence defined in features.conf. This setting does not perform policy enforcement on transfers initiated by other methods.
  • U – Execute via Gosub the routine x for the called channel before connecting to the calling channel. Arguments can be specified to the Gosub using ^ as a delimiter. The Gosub routine can set the variable GOSUB_RESULT to specify the following actions after the Gosub returns.
    • GOSUB_RESULT
      • ABORT – Hangup both legs of the call.
      • CONGESTION – Behave as if line congestion was encountered.
      • BUSY – Behave as if a busy signal was encountered.
      • CONTINUE – Hangup the called party and allow the calling party to continue dialplan execution at the next priority.
      • GOTO:[[<CONTEXT>^]<EXTEN>^]<PRIORITY> – Transfer the call to the specified destination.
    • x – Name of the subroutine to execute via Gosub
    • arg – Arguments for the Gosub routine
  • u – Works with the f option.
    • x – Force the outgoing callerid presentation indicator parameter to be set to one of the values passed in x: allowed_not_screenedallowed_passed_screen allowed_failed_screen allowed prohib_not_screened prohib_passed_screen prohib_failed_screenprohib unavailable
  • w – Allow the called party to enable recording of the call by sending the DTMF sequence defined for one-touch recording in features.conf.
  • W – Allow the calling party to enable recording of the call by sending the DTMF sequence defined for one-touch recording in features.conf.
  • x – Allow the called party to enable recording of the call by sending the DTMF sequence defined for one-touch automixmonitor in features.conf.
  • X – Allow the calling party to enable recording of the call by sending the DTMF sequence defined for one-touch automixmonitor in features.conf.
  • z – On a call forward, cancel any dial timeout which has been set for this call.
• URL – The optional URL will be sent to the called party if the channel driver supports it.

As an example, you can dial into a demonstration server at Digium using the IAX2
protocol by using the following extension:

exten => 500,1,Dial(IAX2/guest@misery.digium.com/s)

The full syntax for the Dial() application is slightly different when dealing with Zap
channels, as shown:

Dial(Zap/[gGrR]channel_or_group[/remote_extension])

For example, here is how you would dial 1-800-555-1212 on Zap channel number 4.

exten => 501,1,Dial(Zap/4/18005551212)

The second argument to the Dial() application is a timeout, specified in seconds. If a
timeout is given, Dial() will attempt to call the destination(s) for that number of seconds
before giving up and moving on to the next priority in the extension. If no timeout
is specified, Dial() will continue to dial the called channel(s) until someone answers
or the caller hangs up. Let’s add a timeout of 10 seconds to our extension:

exten => 123,1,Dial(Zap/1,10)

When the two channels are connected together (“bridged”) allowing a conversation to take place between them. When the channel that triggered the Dial command hangs up, the Dial command exits.

If the call is answered before the timeout, the channels are bridged and the dialplan is
done. If the destination simply does not answer, is busy, or is otherwise unavailable,
Asterisk will set a variable called DIALSTATUS and then continue on with the next priority
in the extension.

Example:

exten => 1265,1,Dial(Phone/phone0,15)
exten => s,3,Dial(SIP/1234,20)
exten => _908.,1,Dial(Modem/ttyI0:${EXTEN:1})
exten => 233,1,Dial(SIP/4029&SIP/4027&Zap/4&IAX/jaz,15,tTr)
exten => 500,1,Dial(Zap/2r2,20,crh)
exten => 20,1,Dial(Zap/3/5551234)

Note that on a successful connection, in the absence of the g and G modifiers (below), the Dial command does not return to allow execution of further commands for that extension in that context. On a failure to connect, it doesreturn to allow executing further commands, either at the following command or at a priority jump, depending on the j and priorityjumping options.

Posts to Review:

astrerisk dialplan configuration file – extensions.conf vicidial / extras / MySQL_AST_CREATE_tables.sql Asterisk : queues.conf Dial : Asterisk Command Dial