Appendix B. Applications in the dialplan

This section is a comprehensive description of the applications available for use in the dialplan (/etc/asterisk/extensions.conf). To use an application, the module to which it belongs must be loaded; this is configured in the [modules] section of /etc/asterisk/modules.conf with autoload=yes or explicitly with load => app_applicationname.so. You can see which modules and applications are available in Asterisk with by entering show applications or show application application_name (Asterisk 1.2) and core show applications oder core show application application_name (Asterisk 1.4).
Take care not to confuse applications or commands with functions. When required, functions are called within commands in the dialplan. "Application" is perhaps too expansive a term but it is the convention in Asterisk when referring to dialplan commands.
It is often possible to omit parameters entirely. In those cases, it is still necessary to include the comma delimiter to establish that a parameter is empty or not provided (i.e. that the default value should be used). For example:
exten => s,1,Dial(IAX2/User:password@example.com/123,,tT)
In general, if an application exits with an error it will return -1, if successful it returns a 0. A return value of -1 means that Asterisk will hang up the channel without passing it along the dialplan.

Important

Be sure to separate parameters with the "," (comma) or "|" (pipe) depending on the version of Asterisk. In this book we use the "," primarily.
Anyone who has used Asterisk for some time already might wonder why one or another application is not included here. The missing applications have been deprecated in Asterisk 1.2 and have ceased to exist altogether in Asterisk 1.4. The corresponding functions which replace them can be found in Appendix C, Functions in the dialplan. The diff output of the built-in help files provided is always shown from the newer 1.4 to the older 1.2.
In the examples the arbitrarily chosen extension 123 and priority 1 are used, just for the purposes of illustration.
Before Asterisk 1.2, many applications jumped to priority n+101, if present, in case of an error (where n is the current priority). This old behavior (called "priority jumping") can be re-enabled with the option j (jump) for some commands or globally via the parameter priorityjumping=yes in the [general] section of extensions.conf. This method, however, is now deprecated. The objectives once met by priority jumping are now achieved by calling defined channel variables, which are considerably more powerful.
To enhance the utility of this book as a reference, the applications are listed in alphabetical order. They also can be arranged into logical categories, shown here:
Call handling (pick-up, transfer, hang-up, ...)
Section B.9, “Answer() - Answer
Section B.14, “Busy() - Signal busy to caller
Section B.17, “ChanIsAvail() - Check to see if a channel is available
Section B.18, “ChannelRedirect() - Redirect a channel to another extension and/or priority
Section B.20, “Congestion() - Signal congestion to caller
Section B.27, “Dial() - Initiate a call to a channel / connect to a channel
Section B.30, “DISA() - DISA (Direct Inward System Access)
Section B.44, “FollowMe() - "follow me" function
Section B.52, “Hangup() - Hang up
Section B.75, “Page() - Page multiple devices
Section B.76, “Park() - Park call
Section B.83, “Pickup() - Call pickup
Section B.98, “RetryDial() - Dial() with auto-redial
Section B.100, “Ringing() - Signal ringing to caller
Flow control and timeouts
Section B.21, “ContinueWhile() - Jump to the beginning of a While() loop
Section B.34, “EndWhile() - End a While() loop
Section B.35, “Exec() - Launch an application
Section B.36, “ExecIf() - Conditional launch of an application
Section B.37, “ExecIfTime() - Time conditional launch of an application
Section B.38, “ExitWhile() - Break a While() loop
Section B.47, “Gosub() - Go to a subroutine
Section B.48, “GosubIf() - Conditional Gosub()
Section B.49, “Goto() - Go to another priority, and/or extension and/or context
Section B.50, “GotoIf() - Conditional Goto()
Section B.51, “GotoIfTime() - Time conditional Gosub()
Section B.90, “Random() - Go to a random entry in the dialplan
Section B.99, “Return() - Return to priority from which Gosub() and GosubIf() was called
Section B.125, “TryExec() - Attempt to launch an application and get the return code
Section B.139, “While() - Start a while loop
Macros
Section B.58, “Macro() - Call a macro
Section B.59, “MacroExclusive() - Call a macro only once at a time
Section B.60, “MacroExit() - Exit from the macro
Section B.61, “MacroIf() - Conditional call of a macro
Caller detection, presentation and handling
Section B.15, “CallingPres() - Change the caller presentation on PRI circuits
Section B.56, “LookupBlacklist() - Look up the caller ID in the blacklist
Section B.57, “LookupCIDName() - Look up the caller ID name in the database
Section B.86, “PrivacyManager() - Request that the caller enter the originating number if no caller ID is available
Section B.112, “SetCallerPres() - Set the caller ID independently of the calling channel
Section B.120, “SoftHangup() - Request a hangup
Section B.140, “Zapateller() - Block telephone solicitations
Call detail records (CDRs)
Section B.10, “AppendCDRUserField() - Append a value to the CDR 'user' field
Section B.45, “ForkCDR() - Creates an additional CDR for the current call
Section B.73, “NoCDR() - Disable CDR for this call
Section B.97, “ResetCDR() - Resets the current CDR
Section B.111, “SetAMAFlags() - Set AMA flags
Section B.113, “SetCDRUserField() - Sets the CDR 'user' field
Voicemail
Section B.29, “Directory() - Provide the "Dial-by-Name" directory
Section B.62, “mailboxExists() - Checks if the mailbox exists
Section B.132, “VoiceMail() - Voicemail engine
Section B.133, “VoiceMailMain() - Voicemail retrieval engine
Section B.131, “VMAuthenticate() - Authenticates the user using user information contained in voicemail.conf
Conferences
Section B.63, “MeetMe() - MeetMe conference
Section B.64, “MeetMeAdmin() - Administer a MeetMe conference
Section B.65, “MeetMeCount() - Provides a count of the participants in a MeetMe conference
Variable handling
Section B.54, “ImportVar() - Import a variable from a channel
Section B.91, “Read() - Read digits from a user into a variable
Section B.92, “ReadFile() - Read a file into a variable
Section B.93, “RealTime() - Read a value from the realtime system into a variable
Section B.94, “RealTimeUpdate() - Change a variable in the realtime system
Section B.110, “Set() - Set a channel variable
Section B.114, “SetGlobalVar() - Set a global variable
Sound files & Music-on-Hold
Section B.12, “Background() - Play a sound file while proceeding to the next priority
Section B.13, “BackgroundDetect() - Background() with sound detection
Section B.22, “ControlPlayback() - Playback() with user playback controls
Section B.23, “DateTime() - Say the date and time
Section B.33, “Echo() - Echo received sound to the user
Section B.42, “Festival() - Read text as speech using the Festival Text-To-Speech engine
Section B.66, “Milliwatt() - Provide a constant 1004 Hz tone at 0 db
Section B.70, “MP3Player() - Play an mp3 file or stream
Section B.71, “MusicOnHold() - Play music-on-hold
Section B.72, “NBScat() - Play an NBS stream
Section B.84, “Playback() - Play a sound file
Section B.85, “Playtones() - Play a tone
Section B.87, “Progress() - Provide the calling channel with in-band progress sounds
Section B.101, “SayAlpha() - Spell out an alphanumeric string
Section B.102, “SayDigits() - Say digits
Section B.103, “SayNumber() - Say a number
Section B.104, “SayPhonetic() - Spell out a string using the phonetic alphabet
Section B.105, “SayUnixTime() - Say the Unix time
Section B.115, “SetMusicOnHold() - Set the Music-on-Hold class
Section B.122, “StopPlaytones() - Stops Playtones()
Recording and Monitoring
Section B.5, “AgentMonitorOutgoing() - Record the outgoing calls of a call agent
Section B.16, “ChangeMonitor() - Changes the filename prefix of a specific channel for Monitor()
Section B.19, “ChanSpy() - Eavesdrop on an active channel
Section B.27, “Dial() - Record a conversation (when used with option w or W)
Section B.28, “Dictate() - A virtual dictation machine
Section B.39, “ExtenSpy() - Eavesdrop on an active channel, and whisper to the originating caller
Section B.67, “MixMonitor() - Like Monitor() but mixes both legs into a single file
Section B.68, “Monitor() - Records each leg (incoming and outgoing) of a call in separate files
Section B.79, “PauseMonitor() - Pauses recording
Section B.95, “Record() - Records only incoming audio
Section B.121, “StopMonitor() - Stop recording with Monitor()
Section B.127, “UnpauseMonitor() - Resumes recording
Section B.141, “ZapBarge() - Eavesdrop on a ZAP channel
Section B.143, “ZapScan() - Eavesdrop on Zap channels and switch easily between them
Database operations
Section B.24, “DBdel() - Erase a record from the database
Section B.25, “DBdeltree() - Erase a branch from the database
General
Section B.11, “Authenticate() - Authenticate a user
Section B.106, “SendDTMF() - Send DTMF tones
Section B.107, “SendImage() - Send an image
Section B.108, “SendText() - Send text
Section B.109, “SendURL() - Send a URL
Section B.124, “Transfer() - Transfer a call
Section B.131, “VMAuthenticate() - Authenticate a user configured in voicemail.conf
Section B.134, “Wait() - Wait for a specified time
Section B.135, “WaitExten() - Wait for the user to dial an extension for specified time
Section B.136, “WaitForRing() - Wait for ring
Section B.137, “WaitForSilence() - Wait for silence
Section B.138, “WaitMusicOnHold() - Wait while providing music-on-hold to caller
External applications
Section B.6, “AGI() - Execute an AGI script
Section B.26, “DeadAGI() - AGI() on an inactive channel
Section B.31, “DumpChan() - Dump information about a channel to the CLI
Section B.32, “EAGI() - See AGI()
Section B.40, “ExternalIVR() - Call an external IVR generator
Section B.41, “FastAGI() - AGI() on another server
Section B.55, “Log() - Log a message at the specified verbosity level
Section B.58, “Macro() - Execute a macro
Section B.74, “NoOp() - No operation; write debugging information to the CLI
Section B.81, “Perl() - res_perl is like mod_perl for Apache, only for Asterisk
Section B.82, “PHP() - res_php is like mod_php for Apache, only for Asterisk
Section B.91, “Read() - Read digits from a user into a variable
Section B.123, “System() - Execute a shell command
Section B.126, “TrySystem() - Like System(), but always returns 0
Section B.129, “UserEvent() - Send an event to the Manager interface
Section B.130, “Verbose() - Send a message to the CLI at the specified verbosity level
SIP
Section B.118, “SIPdtmfMode() - Change the SIP DTMF mode for a SIP originated call
Section B.117, “SIPAddHeader() - Add a SIP header for an outgoing call
ZAP
Section B.43, “Flash() - Send a flash-hook on a ZAP trunk
Section B.141, “ZapBarge() - Eavesdrop on a ZAP channel
Section B.142, “ZapRAS() - Enable RAS (Remote Access Server) on a ZAP ISDN channel
Section B.143, “ZapScan() - Eavesdrop on Zap channels and switch easily between them
Queues and call center functions
Section B.1, “AddQueueMember() - Dynamically add an interface to a queue
Section B.3, “AgentCallbackLogin() - Log-in a queue agent (with call back)
Section B.4, “AgentLogin() - Log-in a queue agent
Section B.5, “AgentMonitorOutgoing() - Record outgoing call of an agent
Section B.77, “ParkAndAnnounce() - Park a call and announce it
Section B.78, “ParkedCall() - Pick up a parked call
Section B.80, “PauseQueueMember() - Pause a queue member
Section B.88, “Queue() - Send a call to the queue
Section B.89, “QueueLog() - Write a message to the queue log
Section B.96, “RemoveQueueMember() - Remove an interface from the queue
Section B.128, “UnpauseQueueMember() - Resume a paused queue member
ADSI
Section B.2, “ADSIProg() - Load an ADSI script into an ADSI telephone device
Section B.46, “GetCPEID() - Request the ADSI-CPE-ID from an ADSI telephone device
Miscellaneous
Section B.8, “AMD() - Answering machine detection
Section B.7, “AlarmReceiver() - Receive and process alarm system events in Contact-ID format from an Ademco alarm panel
Section B.53, “IAX2Provision() - Provision an IAXy device
Section B.69, “Morsecode() - Send text as Morse code
Section B.116, “SetTransferCapability() - Set ISDN transfer capability
Section B.119, “SMS() - Send or receive SMS messages