D-F
From AstriPedia
- Index D-F of Asterisk Applications
Contents |
DateTime
Synopsis
Says a specified time in a custom format
Description
DateTime([unixtime][|[timezone][|format]])
unixtime: time, in seconds since Jan 1, 1970. May be negative.
defaults to now.
timezone: timezone, see /usr/share/zoneinfo for a list.
defaults to machine default.
format: a format the time is to be said in. See voicemail.conf.
defaults to "ABdY 'digits/at' IMp"
DBdel
Synopsis
Delete a key from the database
Description
DBdel(family/key):
This application will delete a key from the Asterisk database.
DBdeltree
Synopsis
Delete a family or keytree from the database
Description
DBdeltree(family[/keytree]):
This application will delete a family or keytree from the Asterisk database
DBget
Synopsis
Retrieve a value from the database
Description
DBget(varname=family/key[|options]):
This application will retrieve a value from the Asterisk database and store it in the given variable.
Options:
j - Jump to priority n+101 if the requested family/key isn't found.
This application sets the following channel variable upon completion:
DBGETSTATUS - This variable will contain the status of the attempt
FOUND | NOTFOUND
This application has been deprecated in favor of the DB function.
DBput
Synopsis
Store a value in the database
Description
DBput(family/key=value):
This application will store the given value in the specified location in the Asterisk database. This application has been deprecated in favor of the DB function.
DeadAGI
Synopsis
Executes AGI on a hungup channel
Description
[E|Dead]AGI(command|args):
Executes an Asterisk Gateway Interface compliant program on a channel. AGI allows Asterisk to launch external programs written in any language to control a telephony channel, play audio, read DTMF digits, etc. by communicating with the AGI protocol on stdin and stdout.
Returns -1 on hangup (except for DeadAGI) or if application requested hangup, or 0 on non-hangup exit.
Using 'EAGI' provides enhanced AGI, with incoming audio available out of band on file descriptor 3
Use the CLI command 'show agi' to list available agi commands
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 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 executing will continue if no requested channels can be called, or if the timeout expires.
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 | INVALIDARGS
For the Privacy and Screening Modes, the DIALSTATUS variable will be set to DONTCALL if the called party chooses to send the calling party to the 'Go Away' script. The DIALSTATUS variable will be set to TORTURE if the called party wants to send the caller to the 'torture' script. 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.
The optional URL will be sent to the called party if the channel supports it. 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.
Options:
A(x) - Play an announcement to the called party, using 'x' as the file.
C - Reset the CDR for this call.
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.
D([called][:calling]) - 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 parameters can be used
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 anything
other than the number assigned to the caller.
g - Proceed with dialplan execution at the current extension if the
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 specified.
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 digit.
H - Allow the calling party to hang up by hitting the '*' DTMF digit.
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 remaining.
m([class]) - Provide hold music to the calling party until a requested
channel answers. A specific MusicOnHold class can be
specified.
M(x[^arg]) - Execute the Macro for the *called* channel before connecting
to the calling channel. Arguments can be specified to the Macro
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. This 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 priority.
* GOTO:<context>^<exten>^<priority> - Transfer the call to the
specified priority. Optionally, an extension, or
extension and priority can be specified.
You cannot use any additional action post answer options in conjunction
with this option.
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 specifies
that if callerID is present, do not screen the call.
o - Specify that the CallerID that was present on the *calling* channel
be set as the CallerID on the *called* channel. This was the
behavior of Asterisk 1.0 and earlier.
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 database 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 calling
party until the called channel has answered.
S(x) - Hang up the call after 'x' seconds *after* the called party has
answered the call.
t - Allow the called party to transfer the calling party by sending the
DTMF sequence defined in features.conf.
T - Allow the calling party to transfer the called party by sending the
DTMF sequence defined in features.conf.
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.
Dictate
Synopsis
Virtual Dictation Machine
Description
Dictate([<base_dir>]) Start dictation machine using optional base dir for files.
DigitTimeout
Synopsis
Set maximum timeout between digits
Description
DigitTimeout(seconds): Set the maximum amount of time permitted between digits when the user is typing in an extension. When this timeout expires, after the user has started to type in an extension, the extension will be considered complete, and will be interpreted. Note that if an extension typed in is valid, it will not have to timeout to be tested, so typically at the expiry of this timeout, the extension will be considered invalid (and thus control would be passed to the 'i' extension, or if it doesn't exist the call would be terminated). The default timeout is 5 seconds. DigitTimeout has been deprecated in favor of Set(TIMEOUT(digit)=timeout)
Directory
Synopsis
Provide directory of voicemail extensions
Description
Directory(vm-context[|dial-context[|options]]):
This application will present the calling channel with a directory of extensions from which they can search by name. The list of names and corresponding extensions is retrieved from the voicemail configuration file, voicemail.conf. This application will immediately exit if one of the following DTMF digits are received and the extension to jump to exists:
0 - Jump to the 'o' extension, if it exists.
* - Jump to the 'a' extension, if it exists.
Parameters:
vm-context - This is the context within voicemail.conf to use for the
Directory.
dial-context - This is the dialplan context to use when looking for an
extension that the user has selected, or when jumping to the
'o' or 'a' extension.
Options:
f - Allow the caller to enter the first name of a user in the directory
instead of using the last name.
DISA
Synopsis
DISA (Direct Inward System Access)
Description
DISA(<numeric passcode>[|<context>]) or disa(<filename>)
The DISA, Direct Inward System Access, application allows someone from outside the telephone switch (PBX) to obtain an "internal" system dialtone and to place calls from it as if they were placing a call from within the switch. DISA plays a dialtone. The user enters their numeric passcode, followed by the pound sign (#). If the passcode is correct, the user is then given system dialtone on which a call may be placed. Obviously, this type of access has SERIOUS security implications, and GREAT care must be taken NOT to compromise your security.
There is a possibility of accessing DISA without password.
Simply exchange your password with "no-password".
Example: exten => s,1,DISA(no-password|local)
Be aware that using this compromises the security of your PBX.
The arguments to this application (in extensions.conf) allow either specification of a single global passcode (that everyone uses), or individual passcodes contained in a file. It also allow specification of the context on which the user will be dialing. If no context is specified, the DISA application defaults the context to "disa". Presumably a normal system will have a special context set up for DISA use with some or a lot of restrictions.
The file that contains the passcodes (if used) allows specification of either just a passcode (defaulting to the "disa" context, or passcode|context on each line of the file. The file may contain blank lines, or comments starting with "#" or ";".
In addition, the above arguments may have |new-callerid-string appended to them, to specify a new (different) callerid to be used for this call, for
example: numeric-passcode|context|"My Phone" <(234) 123-4567>
or
full-pathname-of-passcode-file|"My Phone" <(234) 123-4567>
Last but not least, |mailbox[@context] may be appended, which will cause a stutter-dialtone (indication "dialrecall") to be used, if the specified mailbox contains any new messages, for example:
numeric-passcode|context||1234 (w/a changing callerid)
Note that in the case of specifying the numeric-passcode, the context must be specified if the callerid is specified also.
If login is successful, the application looks up the dialed number in the specified (or default) context, and executes it if found. If the user enters an invalid extension and extension "i" (invalid) exists in the context, it will be used.
DumpChan
Synopsis
Dump Info About The Calling Channel
Description
DumpChan([<min_verbose_level>])
Displays information on channel and listing of all channel variables. If min_verbose_level is specified, output is only displayed when the verbose level is currently set to that number or greater.
DUNDiLookup
Synopsis
Look up a number with DUNDi
Description
DUNDiLookup(number[|context[|options]])
Looks up a given number in the global context specified or in the reserved 'e164' context if not specified. Returns -1 if the channel is hungup during the lookup or 0 otherwise. On completion, the variable ${DUNDTECH} and ${DUNDDEST} will contain the technology and destination of the appropriate technology and destination to access the number. If no answer was found, and the priority n + 101 exists, execution will continue at that location. Note that this will only occur if the global priority jumping option is enabled in extensions.conf. If the 'b' option is specified, the internal DUNDi cache will by bypassed.
EAGI
Synopsis
Executes an EAGI compliant application
Description
[E|Dead]AGI(command|args):
Executes an Asterisk Gateway Interface compliant program on a channel. AGI allows Asterisk to launch external programs written in any language to control a telephony channel, play audio, read DTMF digits, etc. by communicating with the AGI protocol on stdin and stdout.
Returns -1 on hangup (except for DeadAGI) or if application requested hangup, or 0 on non-hangup exit. Using 'EAGI' provides enhanced AGI, with incoming audio available out of band on file descriptor 3
Use the CLI command 'show agi' to list available agi commands
Echo
Synopsis
Echo audio read back to the user
Description
Echo():
Echo audio read from channel back to the channel. User can exit the application by either pressing the '#' key, or hanging up.
EndWhile
Synopsis
End A While Loop
Description
Usage: EndWhile() Return to the previous called While
EnumLookup
Synopsis
Lookup number in ENUM
Description
EnumLookup(exten[|option]):
Looks up an extension via ENUM and sets the variable 'ENUM'. For VoIP URIs this variable will look like 'TECHNOLOGY/URI' with the appropriate technology. Currently, the enumservices SIP, H323, IAX, IAX2 and TEL are recognized.
Returns status in the ENUMSTATUS channel variable:
ERROR Failed to do a lookup
<tech> Technology of the successful lookup: SIP, H323, IAX, IAX2 or TEL
BADURI Got URI Asterisk does not understand.
The option string may contain zero or the following character:
'j' -- jump to +101 priority if the lookup isn't successful.
and jump to +51 priority on a TEL entry.
Eval
Synopsis
Evaluates a string
Description
Usage: Eval(newvar=somestring)
Normally Asterisk evaluates variables inline. But what if you want to store variable offsets in a database, to be evaluated later? Eval is the answer, by allowing a string to be evaluated twice in the dialplan, the first time as part of the normal dialplan, and the second using Eval.
Exec
Synopsis
Executes internal application
Description
Usage: Exec(appname(arguments))
Allows an arbitrary application to be invoked even when not hardcoded into the dialplan. To invoke external applications see the application System. Returns whatever value the app returns or a non-zero value if the app cannot be found.
ExecIf
Synopsis
Conditional exec
Description
Usage: ExecIF (<expr>|<app>|<data>)
If <expr> is true, execute and return the result of <app>(<data>). If <expr> is true, but <app> is not found, then the application will return a non-zero value.
ExecIfTime
Synopsis
Conditional application execution based on the current time
Description
ExecIfTime(<times>|<weekdays>|<mdays>|<months>?appname[|appargs]):
This application will execute the specified dialplan application, with optional arguments, if the current time matches the given time specification. Further information on the time speicification can be found in examples illustrating how to do time-based context includes in the dialplan.
ExternalIVR
Synopsis
Interfaces with an external IVR application
Description
ExternalIVR(command[|arg[|arg...]]):
Forks an process to run the supplied command, and starts a generator on the channel. The generator's play list is controlled by the external application, which can add and clear entries via simple commands issued over its stdout. The external application will receive all DTMF events received on the channel, and notification if the channel is hung up. The application will not be forcibly terminated when the channel is hung up.
See doc/README.externalivr for a protocol specification.
Festival
Synopsis
Say text to the user
Description
Festival(text[|intkeys]):
Connect to Festival, send the argument, get back the waveform,play it to the user, allowing any given interrupt keys to immediately terminate and return the value, or 'any' to allow any number back (useful in dialplan)
Flash
Synopsis
Flashes a Zap Trunk
Description
Flash():
Sends a flash on a zap trunk. This is only a hack for people who want to perform transfers and such via AGI and is generally quite useless oths application will only work on Zap trunks.
ForkCDR
Synopsis
Forks the Call Data Record
Description
ForkCDR([options]):
Causes the Call Data Record to fork an additional cdr record starting from the time of the fork call If the option 'v' is passed all cdr variables will be passed along also.
