Dial()
Prev  Appendix B. Applications in the dialplan  Next

Dial()

Connects channels.

        
          Dial(technology/resource,timeout,options,URL)
        
      
        
          Dial(technology1/resource1[&tech2/resource2[&...]],timeout,options,URL)
        
      
        
          Dial(technology/user:password@host/extension,timeout,options)

Connects two channels together.[48] Dial() is perhaps the most important application in Asterisk. We recommend you read this section carefully and more than once if necessary.

Dial() accepts every valid channel type (e.g. SIP, IAX2, H.323, MGCP, Local oder Zap) but the allowable parameters are channel-specific; i.e., what parameters a channel requires or will accept depends on the nature of the channel technology. For example, a SIP channel will require an IP address and user information, whereas a ZAP channel requires a telephone number.

When a network-based channel type is specified, the parameters (such as IP address, user name, password and remote extension) can be supplied as options to Dial() or, alternatively, be included in a host configuration section in the appropriate .conf file. If this second approach is used, all the required configuration information must be present.

Here's an example:

exten => s,1,Dial(SIP/richard:secret@widgets.biz)

This extension would accomplish the same thing:

exten => s,1,Dial(SIP/a_SIP_friend)

... as long as "a_SIP_friend" is defined as a channel in sip.conf: 

[a_SIP_friend]
fromuser=richard
password=secret
host=widgets.biz

Sometimes an extension is attached to the address information, as in this example:

exten => s,1,Dial(IAX2/user:secret@widgets.biz/500)

The remote system is asked to connect the call to extension 500 in the incoming channel. This extension is not required because the channel configuration on the remote system is used, or, alternatively, the call is passed to the default s extension in the incoming context.

In the end, the remote host decides how the call will be processed; all you can do is request special call handling.

If no timeout is specified, the channel will ring indefinitely. This behavior is not necessarily undesirable and so it's not automatically necessary to set this parameter. Just be aware that "indefinite" can end up being a very long time.[49] The timeout is specified in seconds. It always follows the device information:

exten => s,1,Dial(IAX2/user:secret@widgets.biz/500,20)

With Dial(), you can ring multiple channels simultaneously. The call is handled on a "first come, first served" basis; the first extension to pick up answers the call, and all the other extensions stop ringing and become available:

exten => s,1,Dial(SIP/2000&SIP/2001&SIP/2303)

A big part of the power in the Dial() application is in the options, which always follow the device and timeout information, like so:

exten => s,1,Dial(IAX2/user:secret@widgets.biz/500,60,options)
[Important]

If you want to provide options, you still need to provide a comma-delimited space for the timeout value even if it is empty:

 
exten => s,1,Dial(IAX2/user:secret@widgets.biz/500,,options)

Here are the valid options to the Dial() application:

d
Allows the caller to dial another single-digit extension while waiting for the current extension to answer (e.g., a caller dials "4" while the phone is ringing and the call is immediately passed to the 4 extension. The extension is in the current context unless ${EXITCONTEXT} is set).
t
Blind transfer initiated by the called party. Allows the called party to transfer the call by pressing the blind transfer key (normally "#"). Reinvites are not possible when this option is selected because Asterisk must monitor the connection to detect when the called party presses the "#" key.
T
Blind transfer initiated by the calling party. Allows the calling party to transfer the call by pressing the blind transfer key (normally "#"). Reinvites are not possible when this option is selected because Asterisk must monitor the connection to detect when the called party presses the "#" key.
w
Allows the called party to start recording the call by pressing the automon key sequence (as defined in features.conf). If the TOUCH_MONITOR variable is set, its value is passed to Monitor() as a parameter when recording starts. If it is not set, WAV,,m is passed to Monitor().
W
Allows the calling party to start recording the call by pressing the automon key sequence (as defined in features.conf).
f
Sets the caller ID as the number of the line making or redirecting the outgoing call. Some PSTNs don't allow IDs from extensions other than those assigned to you. For example, if you have a PRI, you would use f to overwrite the caller ID provided by a SIP extension to that belonging to the outgoing Zap channel on the PRI.
o
Uses the caller ID received on the incoming leg of a call as the caller ID for the outgoing leg. This is useful if a call is accepted and then transferred; in the normal case, the caller ID of the initial recipient is used for the outgoing leg, which can be confusing to the ultimate recipient. For example, say Joe calls Mary; Mary decides that Joe really needs to speak to Don and transfers the call. If option o is set, Don will see Joe's number on his display when Mary transfers him, instead of Mary's number.
r
Generate a ringing tone for the calling party. Normally Asterisk will generate a ringing tone when it is appropriate. Option r forces it to do so no matter the circumstance. Sometimes called devices don't provide useful call progress information (or none at all) and r is needed; however, this can also lead to strange behavior, such as initial ringing interrupted by a busy signal.
m[class]
Plays music to the caller until the call is answered. Optionally you can provide the Music-on-Hold class (as defined in musiconhold.conf).
M(x[^arg])

Runs the macro x when the call is answered, optionally passing ^ (caret) separated arguments. The macro may set the MACRO_RESULT channel variable to one of the following values:

ABORT
Hangs up both ends of the call.
CONGESTION
Indicates congestion on the line.
BUSY
Indicates that the line is busy (and jumps to n+101).
CONTINUE
Hangs the called end up and continues in the dialplan.
GOTO:<context>^<extension>^<priority>
Jumps to the specified point in the dialplan.
h
Allows the called party to hang up by pressing "*".
H
Allows the calling party to hang up by pressing "*".
C
Resets the Call Detail Record (CDR) for this call. Normally, the CDR clock is reset from the moment the call is answered by Asterisk; if CDRs are being used for billing purposes, sometimes it's appropriate to reset the timer when the connection between two parties is actually established.
P[(x)]
Uses the Privacy Manager (sollte verkettet sein) if no caller ID is present, where the optional variable x is a family in the AstDB. The Privacy Manager asks the caller to enter a 10 digit telephone number if no caller ID is provided, providing a simple way to screen for telemarketers and solicitors blocking their caller ID. See also LookupBlacklist().
g
Proceeds in the context when the target channel has been hung up.
G(context^extension^priority)
Drops both channels into the specified context, extension and priority when the call is answered.
A(x)
Plays an announcement to the called party, where x is the sound file prefix. For example, A(confirm) would play the most efficient version of confirm (such as confirm.gsm, or confirm.wav) that can be found in the /var/lib/asterisk/sounds directory.
D([called][:calling])
Sends DTMF digits after the call is answered but before it is bridged. The called digits are transmitted to the called party, the calling digits to the calling party. One or both parameters may be set.
L(x[:y][:z])

Limits call duration to x milliseconds. At y ms before the maximum allowed duration, and thereafter every z ms until the end of the call, a warning is given. The x must be defined, y and z are optional. The behavior can be further controlled with the following variables:

LIMIT_PLAYAUDIO_CALLER=yes|no
Sets whether the calling party should hear announcements.
LIMIT_PLAYAUDIO_CALLEE=yes|no
Sets whether the called party should hear announcements.
LIMIT_TIMEOUT_FILE=filename
Specifies the sound file to be played after the maximum duration is reached and the call is ended.
LIMIT_CONNECT_FILE=filename
Specifies the sound file to be played when the call is connected.
LIMIT_WARNING_FILE=filename
Specifies the sound file to be played for the warning signal when y is set.
j

Turns priority jumping on (i.e., the call jumps to priority n+101 (where n is the current priority) if all the channels respond busy).

A call may be parked instead of transferred Ein Anruf kann auch geparkt werden, statt übermittelt zu werden (was mit t oder T-Flag der Fall ist). Anrufe werden gewöhnlich geparkt, indem man sie der Extension 700 übermittelt, aber dieses Verhalten ist in features.conf konfigurierbar.

n

Privacy Manager setting. Caller introductions are not to be saved in the priv-callerintros directory.

N

Privacy Manager setting. Calls are not screened if caller ID information is provided.

Mit dem Enden der Dial()-Anwendung werden die folgenden Variablen gesetzt:

DIALEDTIME
Die gesamte Zeit, die von der Ausführung der Dial()-Anwendung an bis zu ihrer Beendigung verstrichen ist.
ANSWEREDTIME
Die gesamte Zeit, die während des Anrufs vergangen ist.
DIALSTATUS

Der Status des Anrufs, ausgedrückt durch einen der folgenden Werte:

CHANUNAVAIL
Der Channel ist nicht verfügbar.
CONGESTION
Der Channel hat ein Stau-Signal zurückgeliefert, was gewöhnlich die Unfähigkeit der Fertigstellung der Verbindung kennzeichnet.
NOANSWER
Der Channel hat in der durch die Klingel-Timeout-Option gesetzten Frist nicht geantwortet.
BUSY
Der angerufene Channel ist momentan belegt.
ANSWER
Der Channel hat den Anruf beantwortet.
CANCEL
Der Anruf wurde abgebrochen.

When Dial() completes, the following variables are set:

DIALEDTIME

The total elapsed time from the time the Dial() command is executed until its completion.

ANSWEREDTIME

The time elapsed during conversation.

NOANSWER

The channel was not answered before the ring timeout had expired.

BUSY

The called channel is currently busy.

ANSWER

The called channel was answered.

CANCEL

The call was interrupted before it could be completed.

; dial a number on Zap channel 2, let it ring a maximum of 10 seconds:
exten => 123,1,Dial(Zap/2/1234567,10,tTm)
; otherwise proceed in the dialplan:
exten => 123,n,Playback(sorry)
exten => 123,n,Hangup()

; dial extension 500 over IAX on host widgets.biz:
exten => 123,1,Dial(IAX/username:password@widgets.biz/500)
[Note]

Internal help for this application in Asterisk 1.4:  

  -= Info about application 'Dial' =- 

[Synopsis]
Place a call and connect to the current channel

[Description]
  Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|URL
]):
This application will place calls to one or more specified channels. As 
soon
as one of the requested channels answers, the originating channel will b
e
answered, if it has not already been answered. These two channels will t
hen
be active in a bridged call. All other channels that were requested will
 then
be hung up.
  Unless there is a timeout specified, the Dial application will wait
indefinitely until one of the called channels answers, the user hangs up
, or
if all of the called channels are busy or unavailable. Dialplan executin
g will
continue if no requested channels can be called, or if the timeout expir
es.

  This application sets the following channel variables upon completion:
    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 | TORTURE
  For the Privacy and Screening Modes, the DIALSTATUS variable will be s
et to
DONTCALL if the called party chooses to send the calling party to the 'G
o Away'
script. The DIALSTATUS variable will be set to TORTURE if the called par
ty
wants to send the caller to the 'torture' script.
  This application will report normal termination if the originating cha
nnel
hangs up, or if the call is bridged and either of the parties in the bri
dge
ends the call.
  The optional URL will be sent to the called party if the channel suppo
rts it.
  If the OUTBOUND_GROUP variable is set, all peer channels created by th
is
application will be put into that group (as in Set(GROUP()=...).

  Options:
    A(x) - Play an announcement to the called party, using 'x' as the fi
le.
    C    - Reset the CDR for this call.
    d    - Allow the calling user to dial a 1 digit extension while wait
ing for
           a call to be answered. Exit to that extension if it exists in
 the
           current context, or the context defined in the EXITCONTEXT va
riable,
           if it exists.
    D([called][:calling]) - Send the specified DTMF strings *after* the 
called
           party has answered, but before the call gets bridged. The 'ca
lled'
           DTMF string is sent to the called party, and the 'calling' DT
MF
           string is sent to the calling party. Both parameters can be u
sed
           alone.
    f    - Force the callerid of the *calling* channel to be set as the
           extension associated with the channel using a dialplan 'hint'
.
           For example, some PSTNs do not allow CallerID to be set to an
ything
           other than the number assigned to the caller.
    g    - Proceed with dialplan execution at the current extension if t
he
           destination channel hangs up.
    G(context^exten^pri) - If the call is answered, transfer the calling
 party to
           the specified priority and the called party to the specified 
priority+1.
           Optionally, an extension, or extension and context may be spe
cified. 
           Otherwise, the current extension is used. You cannot use any 
additional
           action post answer options in conjunction with this option.
    h    - Allow the called party to hang up by sending the '*' DTMF dig
it.
    H    - Allow the calling party to hang up by hitting the '*' DTMF di
git.
    i    - Asterisk will ignore any forwarding requests it may receive o
n this
           dial attempt.
    j    - Jump to priority n+101 if all of the requested channels were 
busy.
    L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms 
are
           left. Repeat the warning every 'z' ms. The following special
           variables can be used with this option:
           * LIMIT_PLAYAUDIO_CALLER   yes|no (default yes)
                                      Play sounds to the caller.
           * LIMIT_PLAYAUDIO_CALLEE   yes|no
                                      Play sounds to the callee.
           * LIMIT_TIMEOUT_FILE       File to play when time is up.
           * LIMIT_CONNECT_FILE       File to play when call begins.
           * LIMIT_WARNING_FILE       File to play as warning if 'y' is 
defined.
                                      The default is to say the time rem
aining.
    m([class]) - Provide hold music to the calling party until a request
ed
           channel answers. A specific MusicOnHold class can be
           specified.
    M(x[^arg]) - Execute the Macro for the *called* channel before conne
cting
           to the calling channel. Arguments can be specified to the Mac
ro
           using '^' as a delimeter. The Macro can set the variable
           MACRO_RESULT to specify the following actions after the Macro
 is
           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. Th
is will also
                          have the application jump to priority n+101 if
 the
                          'j' option is set.
           * CONTINUE     Hangup the called party and allow the calling 
party
                          to continue dialplan execution at the next pri
ority.
           * GOTO:<context>^<xexten>^<priority> - Transfer the call to t
he
                          specified priority. Optionally, an extension, 
or
                          extension and priority can be specified.
           You cannot use any additional action post answer options in c
onjunction
           with this option. Also, pbx services are not run on the peer 
(called) channel,
           so you will not be able to set timeouts via the TIMEOUT() fun
ction in this macro.
    n    - This option is a modifier for the screen/privacy mode. It spe
cifies
           that no introductions are to be saved in the priv-callerintro
s
           directory.
    N    - This option is a modifier for the screen/privacy mode. It spe
cifies
           that if callerID is present, do not screen the call.
    o    - Specify that the CallerID that was present on the *calling* c
hannel
           be set as the CallerID on the *called* channel. This was the
           behavior of Asterisk 1.0 and earlier.
    O([x]) - "Operator Services" mode (Zaptel channel to Zaptel channel
             only, if specified on non-Zaptel interface, it will be igno
red).
             When the destination answers (presumably an operator servic
es
             station), the originator no longer has control of their lin
e.
             They may hang up, but the switch will not release their lin
e
             until the destination party hangs up (the operator). Specif
ied
             without an arg, or with 1 as an arg, the originator hanging
 up
             will cause the phone to ring back immediately. With a 2 spe
cified,
             when the "operator" flashes the trunk, it will ring their p
hone
             back.
    p    - This option enables screening mode. This is basically Privacy
 mode
           without memory.
    P([x]) - Enable privacy mode. Use 'x' as the family/key in the datab
ase if
           it is provided. The current extension is used if a database
           family/key is not specified.
    r    - Indicate ringing to the calling party. Pass no audio to the c
alling
           party until the called channel has answered.
    S(x) - Hang up the call after 'x' seconds *after* the called party h
as
           answered the call.
    t    - Allow the called party to transfer the calling party by sendi
ng the
           DTMF sequence defined in features.conf.
    T    - Allow the calling party to transfer the called party by sendi
ng the
           DTMF sequence defined in features.conf.
    w    - Allow the called party to enable recording of the call by sen
ding
           the DTMF sequence defined for one-touch recording in features
.conf.
    W    - Allow the calling party to enable recording of the call by se
nding
           the DTMF sequence defined for one-touch recording in features
.conf.
    k    - Allow the called party to enable parking of the call by sendi
ng
           the DTMF sequence defined for call parking in features.conf.
    K    - Allow the calling party to enable parking of the call by send
ing
           the DTMF sequence defined for call parking in features.conf.

diff output to internal help in Asterisk 1.2:  

62,63d61
<     i    - Asterisk will ignore any forwarding requests it may receive
 on this
<            dial attempt.
95,96c93
<            with this option. Also, pbx services are not run on the pee
r (called) channel,
<            so you will not be able to set timeouts via the TIMEOUT() f
unction in this macro.
---
>            with this option.
105,114d101
<     O([x]) - "Operator Services" mode (Zaptel channel to Zaptel channe
l
<              only, if specified on non-Zaptel interface, it will be ig
nored).
<              When the destination answers (presumably an operator serv
ices
<              station), the originator no longer has control of their l
ine.
<              They may hang up, but the switch will not release their l
ine
<              until the destination party hangs up (the operator). Spec
ified
<              without an arg, or with 1 as an arg, the originator hangi
ng up
<              will cause the phone to ring back immediately. With a 2 s
pecified,
<              when the "operator" flashes the trunk, it will ring their
 phone
<              back.
132,135d118
<     k    - Allow the called party to enable parking of the call by sen
ding
<            the DTMF sequence defined for call parking in features.conf
.
<     K    - Allow the calling party to enable parking of the call by se
nding
<            the DTMF sequence defined for call parking in features.conf
.

See also.  the section called “RetryDial()”


[48] Generally, channels of any type supported by Asterisk may be connected - for example, IAX, SIP, H.323, Skinny, PRI, FXO, FXS, Local ...

[49] :-)

Prev  Up  Next
DeadAGI()  Home | Inhaltsverzeichnis  Dictate()