Dial

Synopsis
One of the basic functions of any Public Branch eXchange (PBX) system is to connect telephone calls from one (phone) extension to another.  In the Asterisk PBX system, this is accomplished by the “Dial” command (or application – in Asterisk parlance).  This “Dial” command is used to create phone calls either to or from Asterisk controlled phone extensions.

How To Use
The Dial command is commonly used with an extension definition line to tie extension numbers to physical phones. These extension definition lines are typically located in the file /etc/asterisk/extensions.conf.  

Syntax
The Dial command is formed as follows:
Dial,{technology}/{phone_id}[|timeout][|options][|URL]

With any dial command, at a minimum you need to identify where you want to dial to.  Thus, the technology and phone_id must always be given in the command.  Technology would be the channel technology that you want the call to use.  Different channel technologies include: 
•IAX – InterAsterisk eXchange – open VoIP protocol developed by Digium
•ZAP - Zapata - used for communicating with Channel Banks and/or ISDN PRI's.
•SIP – Session Initiation Protocol – open VoIP protocol used by Cisco, etc...
•MGCP – Media Gatway Control Protocol
•OH323 – H-323 protocol, used by Microsoft NetMeeting, CuSeeMe, etc..
•DSP – Console driver for on-board sound cards.

The phone_id is the circuit identifier within the given channel technology.  This ID is typically defined in the respective channel technology's .conf file such as /etc/asterisk/iax.conf or /etc/asterisk/sip.conf.  

In a special case, the phone_id can be specified as BYEXTENSION.  When this is specified, the number dialed is the number that Asterisk tries to connect to.  This is particularily useful when using Asterisk to connect to an outside line and dial a number.  This option is often used with the stripmsd command as shown in the examples below.

Another special case is the use of wildcard characters in the phone_id.  This is used for pattern matching as opposed to exact extension matching.  Again, this is often used for dialing an external line and phone number from within Asterisk.  The wildcard characters that Asterisk recognizes are:
•“_” - Puts Asterisk into pattern matching mode for number pattern immediately following.
•“N” - Any digit (0-9)
•“X” - Any character or digit

Optionally, you can specify a timeout value, a host of dialing options, and even a URL to send to the receiver of the call.

The timeout value is how long to allow the extension to ring before the dial command is considered to have failed.  By default (no timeout specified), the dialed extension will ring forever until either the caller hangs up,  the called extension answers the call, or the world comes to an end.  When a timeout is specified, the value given is the number of seconds that the extension is allowed to ring before the call is considered a failure.

Different options allow you to modify the way a call is handled by Asterisk. (For more information see Option Details.)

The URL option allows you to pass a URL to the called extension.  Please note that not all channels and/or devices will support this option.  This is typically used to send a web page to a called extension.

Option Details
t – allows the called extension to transfer the call to another extension.  
With this option enabled, the extension receiving the call is allowed to send the call to another Asterisk extension, such as call parking, voice mail, or any other Asterisk extension.  To utilize this option, the called extension must press the [#] key on the phone and wait for the Asterisk system to respond with the voice prompt “Transfer”.  Once this voice prompt is given, you key in the extension you want to transfer the call to.  Once the transfer is complete, the caller is disconnected from the previous extension.

T – allows the calling extension to transfer the call to another extension.
With this option enabled, the caller is allowed to transfer their call to another Asterisk extension, such as call parking, voice mail, or any other Asterisk extension. To utilize this option, the caller must press the [#] key on the phone and wait for the Asterisk system to respond with the voice prompt “Transfer”. Once the voice prompt is given, you key in the extension you want to transfer the call to. When the transfer is complete, the caller is disconnected from the previous extension.

r – indicate call ringing to the calling extension
This option is used when your phone set doesn't recognize the traditional call progress indications.  The best example of this is when you don't hear the “ringing” on the phone when you call another extension.  With the 'r' option turned on, ring tone is passed as actual audio on the phone line, allowing you to hear the call progress.  

m – provide music to the calling extension until the call is answered.
This option is a variation on the “music on hold” idea.  Instead of hearing ring tones, the caller will hear the music you provide.  This music can be anything from random MP3 based music to an “advertising stream”.  

d – allow data calls (force minimum delay on the channel)
This option allows the extension to connect a modem for call-out purposes.  It optimizes the line processing to give the best data throughput.  Using this option is recommended for any line that may have a modem or a fax machine plugged into it.

H – allow the calling extension to terminate the call with the [*] key.
This option is useful mostly for Interactive Voice Response (IVR) systems in that it gives the caller another way to exit out of the system (besides the obvious “hang up”).

P[x] – privacy mode utilizing database 'x'
Privacy mode is a way to define how the call is handled before it is answered.  This mode in general relies on caller-ID data to determine how to deal with the call.  The use of a database allows the rules to be defined per extension.

The privacy database consists of basically 3 sections.  The first is the blacklist.  This is the list of callers who you never take phone calls from.  The second is the whitelist.  This is the list of callers who you always will take calls from.  Last, there is the undefined callers.  Undefined callers aren't so much a list of numbers, but a set of rules for handling calls that didn't match any entries on the blacklist or the whitelist.

Examples for using the 'Dial' application

exten => 7100,1,Dial,Zap/1|24
Defines PBX extension 7100. Dials Zapata defined extension '1' with no options and a 24 second timeout.  If the call is not answered within 24 seconds, the call fails and the next “step” in the extension defination will be executed.

exten => 7100,1,Dial,IAX/24
Defines PBX extension 7100.  Dials IAX defined extension named '24' with no options.  Call will ring indefinately.

exten => 7101,1,Dial,SIP/32|20
Defines PBX extension 7101.  Dials SIP defined extension named '32' with no options and a 20 second timeout.  If the call is not answered within 20 seconds, the call fails and the next “step” in the extension defination will be executed.

exten => s,1,Dial,IAX/10&IAX/11&IAX/12&IAX/13
This is an example of ringing multiple extensions.  This is typically done in response to an incoming call from outside the PBX (i.e. A customer).  The first extension that answers the call gets it.

Ignorepat => 9
exten => _9911,1,Dial,ZAP/g2/911
exten => _911,2,Dial,ZAP/g2/911
exten => _9NXXNXXX,3,StripMSD,1
exten => _NXXNXXX,4,Dial,ZAP/g2/BYEXTENSION
This example shows the Ignorepat option which is used to instruct the channel driver to keep the dialtone alive if this “pattern” is seen.  This example also shows the StripMSD command which is used to remove the first digit (Most Significant Digit in computer parlance) in this example (see the StripMSD command section of this manual for more information on the use of this command).  Finally, we use a pattern match to make sure we have a valid phone number.  Once this is verified, the number as dialed is passed out the ZAP channel on group “g2” as a dial command.  This above example as illustrated implements a standard “dial 9 for an outside line” setup often seen in other PBX systems (but doesn't implement long distance dialing).

Also illustrated in the above example is the implementation of a “911” emergency services number (the US standard for reaching emergency Fire, Police and Ambulance services).  If any caller dials 9911 or 911, the caller is immediately connected to the emergency services number.