CLI> core show application Dial
-= Info about application 'Dial' =-
[Synopsis]
Attempt to connect to another device or endpoint and bridge the call.
[Description]
This application will place calls to one or more specified channels. As soon as
one of the requested channels answers, the originating channel will be
answered, if it has not already been answered. These two channels will then 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 execution will
continue if no requested channels can be called, or if the timeout expires.
This application will report normal termination if the originating channel
hangs up, or if the call is bridged and either of the parties in the bridge
ends the call.
If the ${OUTBOUND_GROUP} variable is set, all peer channels created by this
application will be put into that group (as in 'Set(GROUP()=...'). If the
${OUTBOUND_GROUP_ONCE} variable is set, all peer channels created by this
application will be put into that group (as in 'Set(GROUP()=...'). Unlike
${OUTBOUND_GROUP}, however, the variable will be unset after use.
Example: Dial with 30 second timeout
same => n,Dial(PJSIP/alice,30)
Example: Parallel dial with 45 second timeout
same => n,Dial(PJSIP/alice&PJIP/bob,45)
Example: Dial with 'g' continuation option
same => n,Dial(PJSIP/alice,,g)
same => n,Log(NOTICE, Alice call result: ${DIALSTATUS})
Example: Dial with transfer/recording features for calling party
same => n,Dial(PJSIP/alice,,TX)
Example: Dial with call length limit
same => n,Dial(PJSIP/alice,,L(60000:30000:10000))
Example: Dial alice and bob and send NO_ANSWER to bob instead of
ANSWERED_ELSEWHERE when alice answers
same => n,Dial(PJSIP/alice&PJSIP/bob,,Q(NO_ANSWER))
Example: Dial with pre-dial subroutines
[default]
exten => callee_channel,1,NoOp(ARG1=${ARG1} ARG2=${ARG2})
same => n,Log(NOTICE, I'm called on channel ${CHANNEL} prior to it starting
the dial attempt)
same => n,Return()
exten => called_channel,1,NoOp(ARG1=${ARG1} ARG2=${ARG2})
same => n,Log(NOTICE, I'm called on outbound channel ${CHANNEL} prior to it
being used to dial someone)
same => n,Return()
exten => _X.,1,NoOp()
same => n,Dial(PJSIP/alice,,b(default^called_channel^1(my_gosub_arg1^my_gosub
arg2))B(default^callee_channel^1(my_gosub_arg1^my_gosub_arg2)))
same => n,Hangup()
Example: Dial with post-answer subroutine executed on outbound channel
[my_gosub_routine]
exten => s,1,NoOp(ARG1=${ARG1} ARG2=${ARG2})
same => n,Playback(hello)
same => n,Return()
[default]
exten => _X.,1,NoOp()
same => n,Dial(PJSIP/alice,,U(my_gosub_routine^my_gosub_arg1^my_gosub_arg2))
same => n,Hangup()
Example: Dial into ConfBridge using 'G' option
same => n,Dial(PJSIP/alice,,G(jump_to_here))
same => n(jump_to_here),Goto(confbridge)
same => n,Goto(confbridge)
same => n(confbridge),ConfBridge(${EXTEN})
This application sets the following channel variables:
${DIALEDTIME}: This is the time from dialing a channel until when it is
disconnected.
${DIALEDTIME_MS}: This is the milliseconds version of the DIALEDTIME variable.
${ANSWEREDTIME}: This is the amount of time for actual call.
${ANSWEREDTIME_MS}: This is the milliseconds version of the ANSWEREDTIME
variable.
${RINGTIME}: This is the time from creating the channel to the first RINGING
event received. Empty if there was no ring.
${RINGTIME_MS}: This is the milliseconds version of the RINGTIME variable.
${PROGRESSTIME}: This is the time from creating the channel to the first
PROGRESS event received. Empty if there was no such event.
${PROGRESSTIME_MS}: This is the milliseconds version of the PROGRESSTIME
variable.
${DIALEDPEERNAME}: The name of the outbound channel that answered the call.
${DIALEDPEERNUMBER}: The number that was dialed for the answered outbound
channel.
${FORWARDERNAME}: If a call forward occurred, the name of the forwarded
channel.
${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
[Syntax]
Dial([Technology/Resource[&Technology2/Resource2[&...]]][,timeout[,options[,URL]]])
[Arguments]
Technology/Resource
Specification of the device(s) to dial. These must be in the format of
'Technology/Resource', where <Technology> represents 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 than one enter them as Technology2/Resource2&Technology3/R
source3&.....
timeout
Specifies the number of seconds we attempt to dial the specified devices.
If not specified, this defaults to 136 years.
options
A(x):
x - The file to play to the called party
Play an announcement to the called party, where <x> is the prompt to be played
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([[context^]exten^]priority[(arg1[^...][^argN])]): Before initiating an
outgoing call, 'Gosub' to the specified location using the newly created
channel. The 'Gosub' will be executed for each destination channel.
B([[context^]exten^]priority[(arg1[^...][^argN])]): Before initiating the
outgoing call(s), 'Gosub' to the specified location using the current
channel.
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.
NOTE: Many SIP and ISDN phones cannot send DTMF digits until the call is
connected. If you wish to use this option with these phones, you can use
the 'Answer' application before dialing.
D([called][:calling[:progress]]): 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 to the called party immediately
after receiving a 'PROGRESS' message.
See 'SendDTMF' for valid digits.
e: Execute the 'h' extension for peer after the call ends
f([x]): 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>.
F([[context^]exten^]priority): When the caller hangs up, transfer the
*called* party to the specified destination and *start* execution at that
location.
NOTE: Any channel variables you want the called channel to inherit from the
caller channel must be prefixed with one or two underbars ('_').
F: When the caller hangs up, transfer the *called* party to the next
priority of the current extension and *start* execution at that location.
NOTE: Any channel variables you want the called channel to inherit from the
caller channel must be prefixed with one or two underbars ('_').
NOTE: Using this option from a Macro() or GoSub() might not make sense as
there would be no return points.
g: Proceed with dialplan execution at the next priority in the current
extension if the destination channel hangs up.
G([[context^]exten^]priority): If the call is answered, transfer the
calling party to the specified <priority> and the called party to the
specified <priority> plus one.
NOTE: 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 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".
NOTE: Many SIP and ISDN phones cannot send DTMF digits until the call is
connected. If you wish to allow DTMF disconnect before the dialed party
answers with these phones, you can use the 'Answer' application before
dialing.
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(x[:y[:z]]):
x - Maximum call time, in milliseconds
y - Warning time, in milliseconds
z - Repeat time, in milliseconds
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}:
yes
no
If set, this variable causes Asterisk to play the prompts to the
caller.
${LIMIT_PLAYAUDIO_CALLEE}:
yes
no
If set, this variable causes Asterisk to play the prompts to the
callee.
${LIMIT_TIMEOUT_FILE}:
filename
If specified, <filename> specifies the sound prompt to play when
the timeout is reached. If not set, the time remaining will be
announced.
${LIMIT_CONNECT_FILE}:
filename
If specified, <filename> specifies the sound prompt to play when
the call begins. If not set, the time remaining will be announced.
${LIMIT_WARNING_FILE}:
filename
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.
m([class]): 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.
M(macro[^arg[^...]]):
macro - Name of the macro that should be executed.
arg - Macro arguments
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.
NOTE: You cannot use any additional action post answer options in
conjunction with this option. Also, pbx services are run on the peer
(called) channel, so you will not be able to set timeouts via the
'TIMEOUT()' function in this macro.
WARNING: Be aware of the limitations that macros have, specifically with
regards to use of the 'WaitExten' application. For more information, see
the documentation for 'Macro()'.
NOTE: Macros are deprecated, GoSub should be used instead, see the 'U'
option.
n([delete]):
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.
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 the
"priv-callerintros" directory.
N: This option is a modifier for the call screening/privacy mode. It
specifies that if CallerID is present, do not screen the call.
o([x]): 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.
O([mode]):
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.
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.
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 AstDB
database if it is provided. The current extension is used if a database
family/key is not specified.
Q(cause): Specify the Q.850/Q.931 <cause> to send on unanswered channels
when another channel answers the call. As with 'Hangup()', <cause> can be a
numeric cause code or a name such as 'NO_ANSWER', 'USER_BUSY',
'CALL_REJECTED' or 'ANSWERED_ELSEWHERE' (the default if Q isn't specified).
You can also specify '0' or 'NONE' to send no cause. See the "causes.h"
file for the full list of valid causes and names.
NOTE: chan_sip does not support setting the cause on a CANCEL to anything
other than ANSWERED_ELSEWHERE.
r([tone]): 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 the
"indications.conf" tonezone currently in use.
R: Default: Indicate ringing to the calling party, even if the called party
isn't actually ringing. Allow interruption of the ringback if early media
is received on the channel.
S(x): Hang up the call <x> seconds *after* the called party has answered
the call.
s(x): Force the outgoing CallerID tag parameter to be set to the string
<x>.
Works with the 'f' option.
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(x[^arg[^...]]):
x - Name of the subroutine context to execute via 'Gosub'. The
subroutine execution starts in the named context at the s exten and
priority 1.
arg - Arguments for the 'Gosub' routine
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.
NOTE: You cannot use any additional action post answer options in
conjunction with this option. Also, pbx services are run on the *called*
channel, so you will not be able to set timeouts via the 'TIMEOUT()'
function in this routine.
u(x):
x - Force the outgoing callerid presentation indicator parameter to be
set to one of the values passed in <x>: 'allowed_not_screened'
'allowed_passed_screen' 'allowed_failed_screen' 'allowed'
'prohib_not_screened' 'prohib_passed_screen' 'prohib_failed_screen'
'prohib' 'unavailable'
Works with the 'f' option.
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.
[See Also]
RetryDial(), SendDTMF(), Gosub(), Macro()
