Dial( )
|
Attempts to connect channels
|
Dial(tech/username:password@hostname/extension,ring-timeout,flags)
Allows you to connect together all of the
various channel types. Dial( ) is the
most important application in Asteriskyou'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 callyou 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 itjust 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)
|
Here's something important to note: 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:
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 ${EXITCONTEXT}).
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).
f
-
Forces the Caller ID to be set as the extension
of the line making or redirecting the outgoing call. This is done
because some PSTN providers will not allow the Caller ID to be set
to anything other than that which 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.
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 is the default behavior on Asterisk
versions prior to 1.2.
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.
m[ class]
-
Provides music to the calling party until the
call is answered. You may also optionally indicate the Music on
Hold class.
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:
ABORT
-
Hangs up both legs of the call
CONGESTION
-
Acts as if the line encountered congestion
BUSY
-
Acts as if the line was busy (goes to
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
h
-
Allows the called user to hang up the channel by
pressing *.
H
-
Allows the calling user to hang up the channel
by pressing *.
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.
P[( x)]
-
Sets the privacy mode, optionally specifying
x as the family/key value in the local AstDB.
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( ).
g
-
Goes on in the context if the destination
channel hangs up.
G( context^
extension^ priority)
-
Transfers both parties to the specified
destination, if the call is answered.
A( x)
-
Plays an announcement to the called party;
x is the filename of the sound file to play as the
announcement.
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.
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
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
n
-
Prevents jumping to priority n+101
(where n is the number of the current priority) if all
channels are deemed busy.
A call may also be parked instead of being
transferred (which is done with the t or T
flags). Calls are normally parked by transferring them to extension
700, but that's configurable in the features.conf file.
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.
; dial a seven-digit number on Zap channel 4
exten => 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 dialplan
exten => 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 flags
exten => 125,1,Dial(Zap/4/2317154,,tTm)
; dial extension 500 at a remote host (over the IAX protocol), using
; the specified username and password
exten => 126,1,Dial(IAX/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) into
the call,
; and repeat the warning every 30 seconds (30,000 milliseconds)
exten => 127,1,Dial(Zap/4/2317154,,L[300000:240000:30000])
|