Dial() — Attempts to connect channels
Dial(tech/username:password@hostname/extension[&tech2/peer2...] [,ring-timeout[,flags[,URL]]])
Allows you to connect together all of the various channel
types.[163]Dial() is the most
important application in Asterisk; you’ll want to read through this
section a few times.
Any valid channel type (such as SIP, IAX2, H.323, MGCP, Local, or
Zap) is acceptable to Dial(), but the
parameters that need to be passed to each channel will depend on the
information the channel type needs to do its job. For example, a SIP
channel will need a network address and user to connect to, whereas a
Zap channel is going to want some sort of phone number.
When you specify a channel type that is network-based, you can
pass the destination host (name or IP address), username, password, and
remote extension as part of the options to Dial(), or you can refer to the name of a
channel entry in the appropriate .conf file; all the required information will
then need to be obtained from that file. The username and password can
be replaced with the name contained within square brackets ([]) of the channel configuration file. The
hostname is optional.
This is a valid Dial
statement:
exten => s,1,Dial(SIP/sake:arigato@thathostoverthere.tld)
This is effectively identical:
exten => s,1,Dial(SIP/some_SIP_friend)
but will work only if there is a channel defined in sip.conf as [some_SIP_friend], whose channel definition
contains fromuser=sake, password=arigato, and host=thathostoverthere.tld.
An extension number is often attached after the address information, like this:
exten => s,1,Dial(IAX2/user:pass@otherend.com/500)This asks the far end to connect the call to extension 500 in the
context in which the channel arrived. The extension is not required by
Dial(), as the information in the
remote end’s channel configuration file may be used, or the remote
server will pass the call to the s
extension in the context in which the call came in. Ultimately, the far
end controls what happens to the call; you can only request a specific
treatment.
If no ring-timeout is specified, the
channel will ring indefinitely. This is not always a bad thing, so don’t
feel you need to set it; just be aware that “indefinitely” could mean a
very long time. ring-timeout is specified in
seconds. The ring timeout always follows the addressing information,
like this:
exten => s,1,Dial(IAX2/user:pass@otherend.com/500,ring-timeout)Much of the power of the Dial()
application is in the flags. These are assigned following the addressing
and timeout information, like this:
exten => s,1,Dial(IAX2/user:pass@otherend.com/500,60,flags)If you don’t have a timeout specified, and you want to assign flags, you must still assign a spot for the timeout. You do this by adding an extra comma in the spot where the timeout would normally go, like this:
exten => s,1,Dial(IAX2/user:pass@otherend.com/500,,flags)The valid flags that may be used with the Dial() application are:
A(
x
)
Plays an announcement to the called party;
x is the filename of the sound file to
play as the announcement.
C
Resets the Call Detail Record for the call. Since the CDR
time is set to when you Answer() the call, you may wish to reset
the CDR so the end user is not billed for the time prior to the
Dial() application being
invoked.
d
Allows the user to dial a one-digit extension while waiting
for a call to be answered. The call will then exit to that
extension (either in the current context, if it exists, or in the
context specified by the EXITCONTEXT variable).
D([
called
][:
calling
])
Sends DTMF digits after the call has been answered, but
before the call is bridged. The called
parameter is passed to the called party, and the
calling parameter is passed to the
calling party. Either parameter may be used individually.
f
Forces the Caller ID of the calling
party to be set as the extension associated with the channel using
a dialplan hint. This is often used when a provider doesn’t allow
the Caller ID to be set to anything other than a number that is
assigned to you. For example, if you had a PRI, you would use the
f flag to override any Caller
ID set locally on a SIP phone.
g
Execution of the dialplan goes on in the current context if the destination channel hangs up.
G(
context
^
extension
^
priority
)
When the call is answered, the calling party is transferred to the specified priority and the called party to the specified priority+1. You cannot use any additional action post-answer options in conjunction with this option.
h
Allows the called user to hang up the channel by pressing
the * key.
H
Allows the calling user to hang up the channel by pressing
the * key.
i
Causes Asterisk to ignore any forwarding requests it may receive on this dial attempt.
j
Causes Asterisk to jump to priority n+101 if all the requested channels were
busy (where n is the current
priority).
L(
x
[:
y
][:
z
])
Limits the call to x
milliseconds, warning when y
milliseconds are left and repeating every
z milliseconds until the limit is
reached. The x parameter is required;
the y and z
parameters are optional. The following special variables may also
be set to provide additional control:
LIMIT_PLAYAUDIO_CALLER=yes|no
Specifies whether to play sounds to the caller. Defaults to yes.
LIMIT_PLAYAUDIO_CALLEE=yes|no
Specifies whether to play sounds to the callee.
LIMIT_TIMEOUT_FILE=
filename
Specifies which file to play when time is up.
LIMIT_CONNECT_FILE=
filename
Specifies which file to play when call begins.
LIMIT_WARNING_FILE=
filename
Specifies the file to play if the argument
y is defined. Defaults to saying
the time remaining.
m[class]Provides music to the calling party until the call is
answered. You may also optionally indicate the music-on-hold
class, as defined in musiconhold.conf.
M(
x
[
^arg
])
Executes the macro x upon the
connection of a call, optionally passing arguments delimited by
^. The macro can also set the
MACRO_RESULT channel variable
to one of the following values, to determine what should happen
after the macro has finished:
ABORT
Hangs up both legs of the call.
CONGESTION
Acts as if the line encountered congestion.
BUSY
Acts as if the line was busy. If the
j option is specified, it sends
the call to priority n+101, where n is the current priority.
CONTINUE
Hangs up the called party and continues on in the dialplan.
GOTO:<context>^<extension>^<priority>
Transfers the call to the specified destination.
You cannot use any additional action post-answer options
in conjunction with this option. Also, PBX services are not run
on the called channel, so you will not be able to set timeouts
via the TIMEOUT function in
this macro.
n
This option is a modifier for the screen/privacy mode. It specifies that no introductions are to be saved in the priv-callerintros directory.
N
This option is a modifier for the screen/privacy mode. It tells Asterisk not to screen the call if Caller ID is present.
o
Uses the Caller ID received on the inbound leg of the call for the Caller ID on the outbound leg of the call. This is useful if you are accepting a call and then forwarding it to another destination, but you wish to pass the Caller ID from the inbound leg of the call instead of overwriting it with the local Caller ID settings. This was the default behavior on Asterisk versions prior to 1.0.
O[x]This option turns on Operator Services mode on a Zaptel
channel. If this option is used on a non-Zaptel interface, it will
be ignored. When the destination answers (presumably an operator
services station), the originator no longer has control of her
line. She may hang up, but the switch will not release her line
until the destination party (the operator) hangs up. Specified
without an arg, or with 1 as an
arg, the originator hanging up will cause the phone to ring back
immediately. With a 2 specified
as the argument, when the “operator” flashes the trunk, it will
ring the caller’s phone.
p
This option enables screening mode. This is basically Privacy mode without memory.
P[(x)]Sets the privacy mode, optionally specifying
x as the family/key value in the local
AstDB database. This option is useful for accepting calls based on
a blacklist (explicitly denying calls from listed numbers) or
whitelist (explicitly accepting calls from listed numbers). See
also LookupBlacklist().
r
Indicates ringing to the calling party, without passing any audio until the call is answered. This flag is not normally required to indicate ringing, as Asterisk will signal ringing if a channel is actually being called.
S(x)Hangs up the call x seconds after
the called party has answered the
call.
t
Permits the called party to transfer a call by pressing the
# key. Please note that if this
option is used, reinvites are disabled, as Asterisk needs to
monitor the call to detect when the called party presses the
# key.
T
Permits the caller to transfer a connected call by pressing
the # key. Again, note that if
this option is used, reinvites are disabled, as Asterisk needs to
monitor the call to detect when the caller presses the # key.
w
Permits the called user to start and stop recording the call
audio to disk by pressing the automon sequence (as configured in
features.conf). If the
variable TOUCH_MONITOR is set,
its value will be passed as the arguments to the Monitor() application when recording is
started. If it is not set, the default values of WAV||m are passed to Monitor().
W
Permits the calling user to record the call audio to disk by
pressing the automon sequence
(as configured in features.conf).
k
Permits the called party to park the call by sending the
DTMF sequence defined for call parking in features.conf.
K
Permits the calling party to park the call by sending the
DTMF sequence defined for call parking in features.conf.
If the URL argument is included, that
URL will be sent to the channel (if supported).
If the channel variable named OUTBOUND_GROUP is set before Dial() is called, all peer channels created
by this application will be put in to that call group. In the
following example, all peer channels created by the Dial() application will be part of the
test call group:
; using OUTBOUND_GROUP exten => 123,1,Set(OUTBOUND_GROUP=test) exten => 123,n,Dial(IAX2/anotherbox/12345)
If the OUTBOUND_GROUP_ONCE
variable is set, all peer channels created by this application will be
put in to that group. Unlike OUTBOUND_GROUP, however, the variable will
be unset after use.
The Dial() application sets the
following variables upon exiting:
DIALEDTIME
The total time elapsed from execution of Dial() until completion.
ANSWEREDTIME
The total time elapsed during the call.
DIALSTATUS
The status of the call, set as one of the following values:
CHANUNAVAIL
The channel is unavailable.
CONGESTION
The channel returned a congestion signal, usually indicating that it was unable to complete the connection.
NOANSWER
The channel did not answer in the time indicated by the ring-timeout option.
BUSY
The dialed channel is currently busy.
ANSWER
The channel answered the call.
CANCEL
The call was cancelled.
DONTCALL
The call was set to DONTCALL by the screening or
privacy options.
TORTURE
The call was set to TORTURE by the screening or
privacy options.
INVALIDARGS
Invalid arguments were passed to the Dial() application.
; dial a seven-digit number on Zap channel 4exten => 123,1,Dial(Zap/4/2317154); dial the same number, but this time only have it ring for 10 seconds ; before continuing on with the dialplanexten => 124,1,Dial(Zap/4/2317154,10)exten => 124,2,Playback(im-sorry) exten => 124,3,Hangup() ; dial the same number, but this time with no timeout, and using the ; t, T, and m flagsexten => 125,1,Dial(Zap/4/2317154,,tTm); dial extension 500 at a remote host (over the IAX protocol), using ; the specified username and passwordexten => 126,1,Dial(IAX2/username:password@remotehost/500); dial a number, but limit the call to 5 minutes (300,000 milliseconds) ; start warning the caller 4 minutes (240,000 milliseconds) in to the call, ; and repeat the warning every 30 seconds (30,000 milliseconds)exten => 127,1,Dial(Zap/4/2317154,,L[300000:240000:30000])
[163] The fact that Asterisk will happily connect IAX, SIP, H.323,
Skinny, PRI, FX(O/S), and anything else is amazing, but possibly the
most amazing of all is the Local channel. By allowing a single
Dial() command to connect to
multiple Local channels, one Dial() event can trigger a multitude of
completely independent and unique actions in other parts of the
dialplan. The power of this concept is truly revolutionary and has
to be experienced to be believed.