diff --git a/doc/ast_appdocs.tex b/doc/ast_appdocs.tex index ee2692658..bf01af48a 100644 --- a/doc/ast_appdocs.tex +++ b/doc/ast_appdocs.tex @@ -34,23 +34,6 @@ script. If nothing is specified, the default script (asterisk.adsi) is used. \end{verbatim} -\section{AgentCallbackLogin} -\subsection{Synopsis} -\begin{verbatim} -Call agent callback login -\end{verbatim} -\subsection{Description} -\begin{verbatim} - AgentCallbackLogin([AgentNo][|[options][|[exten]@context]]): -Asks the agent to login to the system with callback. -The agent's callback extension is called (optionally with the specified -context). -The option string may contain zero or more of the following characters: - 's' -- silent login - do not announce the login ok segment agent logged in/off - -\end{verbatim} - - \section{AgentLogin} \subsection{Synopsis} \begin{verbatim} @@ -206,29 +189,6 @@ the dialplan after answering the call. \end{verbatim} -\section{AppendCDRUserField} -\subsection{Synopsis} -\begin{verbatim} -Append to the CDR user field -\end{verbatim} -\subsection{Description} -\begin{verbatim} -[Synopsis] -AppendCDRUserField(value) - -[Description] -AppendCDRUserField(value): Append value to the CDR user field - The Call Data Record (CDR) user field is an extra field you - can use for data not stored anywhere else in the record. - CDR records can be used for billing or storing other arbitrary data - (I.E. telephone survey responses) - Also see SetCDRUserField(). - -This application is deprecated in favor of Set(CDR(userfield)=...) - -\end{verbatim} - - \section{Authenticate} \subsection{Synopsis} \begin{verbatim} @@ -285,6 +245,9 @@ terminated. n - Don't answer the channel before playing the files. m - Only break if a digit hit matches a one digit extension in the destination context. +This application sets the following channel variable upon completion: + BACKGROUNDSTATUS The status of the background attempt as a text string, one of + SUCCESS | FAILED \end{verbatim} @@ -309,6 +272,23 @@ infinity respectively. \end{verbatim} +\section{Bridge} +\subsection{Synopsis} +\begin{verbatim} +Bridge two channels +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: Bridge(channel[|options]) + Allows the ability to bridge two channels via the dialplan. +The current channel is bridged to the specified 'channel'. +The following options are supported: + p - Play a courtesy tone to 'channel'. +BRIDGERESULT dial plan variable will contain SUCCESS, FAILURE, LOOP, NONEXISTENT or INCOMPATIBLE. + +\end{verbatim} + + \section{Busy} \subsection{Synopsis} \begin{verbatim} @@ -353,6 +333,8 @@ available. The following variables will be set by this application: ${AVAILSTATUS} - the status code for the available channel Options: s - Consider the channel unavailable if the channel is in use at all + t - Simply checks if specified channels exist in the channel list + (implies option s) j - Support jumping to priority n+101 if no channel is available \end{verbatim} @@ -389,6 +371,10 @@ only channels beginning with this string will be spied upon. to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing the digits '1234#' while spying will begin spying on the channel 'Agent/1234'. + Note: The X option supersedes the three features above in that if a valid + single digit extension exists in the correct context ChanSpy will + exit to it. This also disables choosing a channel based on 'chanprefix' + and a digit sequence. Options: b - Only spy on channels involved in a bridged call. g(grp) - Match only channels where their ${SPYGROUP} variable is set to @@ -405,6 +391,25 @@ only channels beginning with this string will be spied upon. W - Enable 'private whisper' mode, so the spying channel can talk to the spied-on channel but cannot listen to that channel. + o - Only listen to audio coming from this channel. + X - Allow the user to exit ChanSpy to a valid single digit + numeric extension in the current context or the context + specified by the SPY_EXIT_CONTEXT channel variable. The + name of the last channel that was spied on will be stored + in the SPY_CHANNEL variable. + +\end{verbatim} + + +\section{ClearHash} +\subsection{Synopsis} +\begin{verbatim} +Clear the keys from a specified hashname +\end{verbatim} +\subsection{Description} +\begin{verbatim} +ClearHash() + Clears all keys out of the specified hashname \end{verbatim} @@ -573,6 +578,9 @@ 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. @@ -926,6 +934,9 @@ supplied, the current channel's context will be used. While spying, the following actions may be performed: - Dialing # cycles the volume level. - Dialing * will stop spying and look for another channel to spy on. + Note: The X option superseeds the two features above in that if a valid + single digit extension exists in the correct context it ChanSpy will + exit to it. Options: b - Only spy on channels involved in a bridged call. g(grp) - Match only channels where their ${SPYGROUP} variable is set to @@ -942,6 +953,12 @@ supplied, the current channel's context will be used. W - Enable 'private whisper' mode, so the spying channel can talk to the spied-on channel but cannot listen to that channel. + o - Only listen to audio coming from this channel. + X - Allow the user to exit ChanSpy to a valid single digit + numeric extension in the current context or the context + specified by the SPY_EXIT_CONTEXT channel variable. The + name of the last channel that was spied on will be stored + in the SPY_CHANNEL variable. \end{verbatim} @@ -1050,7 +1067,7 @@ Jump to label, saving return address \end{verbatim} \subsection{Description} \begin{verbatim} -Gosub([[context|]exten|]priority) +Gosub([[context|]exten|]priority[(arg1[|...][|argN])]) Jumps to the label specified, saving the return address. \end{verbatim} @@ -1063,7 +1080,7 @@ Conditionally jump to label, saving return address \end{verbatim} \subsection{Description} \begin{verbatim} -GosubIf(condition?labeliftrue[:labeliffalse]) +GosubIf(condition?labeliftrue[(arg1[|...])][:labeliffalse[(arg1[|...])]]) If the condition is true, then jump to labeliftrue. If false, jumps to labeliffalse, if specified. In either case, a jump saves the return point in the dialplan, to be returned to with a Return. @@ -1156,47 +1173,6 @@ value. \end{verbatim} -\section{HasNewVoicemail} -\subsection{Synopsis} -\begin{verbatim} -Conditionally branches to priority + 101 with the right options set -\end{verbatim} -\subsection{Description} -\begin{verbatim} -HasNewVoicemail(vmbox[/folder][@context][|varname[|options]]) -Assumes folder 'INBOX' if folder is not specified. Optionally sets to the number of messages -in that folder. - The option string may contain zero of the following character: - 'j' -- jump to priority n+101, if there is new voicemail in folder 'folder' or INBOX - This application sets the following channel variable upon completion: - HASVMSTATUS The result of the new voicemail check returned as a text string as follows - <# of messages in the folder, 0 for NONE> - -This application has been deprecated in favor of the VMCOUNT() function - -\end{verbatim} - - -\section{HasVoicemail} -\subsection{Synopsis} -\begin{verbatim} -Conditionally branches to priority + 101 with the right options set -\end{verbatim} -\subsection{Description} -\begin{verbatim} -HasVoicemail(vmbox[/folder][@context][|varname[|options]]) - Optionally sets to the number of messages in that folder. Assumes folder of INBOX if not specified. - The option string may contain zero or the following character: - 'j' -- jump to priority n+101, if there is voicemail in the folder indicated. - This application sets the following channel variable upon completion: - HASVMSTATUS The result of the voicemail check returned as a text string as follows - <# of messages in the folder, 0 for NONE> - -This application has been deprecated in favor of the VMCOUNT() function - -\end{verbatim} - - \section{IAX2Provision} \subsection{Synopsis} \begin{verbatim} @@ -1242,19 +1218,6 @@ Set for more information. \end{verbatim} -\section{IVRDemo} -\subsection{Synopsis} -\begin{verbatim} -IVR Demo Application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - This is a skeleton application that shows you the basic structure to create your -own asterisk applications and demonstrates the IVR demo. - -\end{verbatim} - - \section{JabberSend} \subsection{Synopsis} \begin{verbatim} @@ -1300,48 +1263,6 @@ Log(|) \end{verbatim} -\section{LookupBlacklist} -\subsection{Synopsis} -\begin{verbatim} -Look up Caller*ID name/number from blacklist database -\end{verbatim} -\subsection{Description} -\begin{verbatim} - LookupBlacklist(options): Looks up the Caller*ID number on the active -channel in the Asterisk database (family 'blacklist'). -The option string may contain the following character: - 'j' -- jump to n+101 priority if the number/name is found in the blacklist -This application sets the following channel variable upon completion: - LOOKUPBLSTATUS The status of the Blacklist lookup as a text string, one of - FOUND | NOTFOUND -Example: exten => 1234,1,LookupBlacklist() - -This application is deprecated and may be removed from a future release. -Please use the dialplan function BLACKLIST() instead. - -\end{verbatim} - - -\section{LookupCIDName} -\subsection{Synopsis} -\begin{verbatim} -Look up CallerID Name from local database -\end{verbatim} -\subsection{Description} -\begin{verbatim} - LookupCIDName: Looks up the Caller*ID number on the active -channel in the Asterisk database (family 'cidname') and sets the -Caller*ID name. Does nothing if no Caller*ID was received on the -channel. This is useful if you do not subscribe to Caller*ID -name delivery, or if you want to change the names on some incoming -calls. - -LookupCIDName is deprecated. Please use ${DB(cidname/${CALLERID(num)})} -instead. - -\end{verbatim} - - \section{Macro} \subsection{Synopsis} \begin{verbatim} @@ -1359,12 +1280,19 @@ If you Goto out of the Macro context, the Macro will terminate and control will be returned at the location of the Goto. If ${MACRO_OFFSET} is set at termination, Macro will attempt to continue at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise. +Extensions: While a macro is being executed, it becomes the current context. + This means that if a hangup occurs, for instance, that the macro + will be searched for an 'h' extension, NOT the context from which + the macro was called. So, make sure to define all appropriate + extensions in your macro! (Note: AEL does not use macros) WARNING: Because of the way Macro is implemented (it executes the priorities contained within it via sub-engine), and a fixed per-thread memory stack allowance, macros are limited to 7 levels of nesting (macro calling macro calling macro, etc.); It may be possible that stack-intensive applications in deeply nested macros - could cause asterisk to crash earlier than this limit. + could cause asterisk to crash earlier than this limit. It is advised that + if you need to deeply nest macro calls, that you use the Gosub application + (now allows arguments like a Macro) with explict Return() calls instead. \end{verbatim} @@ -1459,6 +1387,7 @@ The option string may contain zero or more of the following characters: Default: conf-background.agi (Note: This does not work with non-Zap channels in the same conference) 'c' -- announce user(s) count on joining a conference + 'C' -- continue in dialplan when kicked out of conference 'd' -- dynamically add conference 'D' -- dynamically add conference, prompting for a PIN 'e' -- select an empty conference @@ -1555,6 +1484,139 @@ Milliwatt(): Generate a Constant 1000Hz tone at 0dbm (mu-law) \end{verbatim} +\section{MinivmAccMess} +\subsection{Synopsis} +\begin{verbatim} +Record account specific messages +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmAccmess(username@domain,option) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +Use this application to record account specific audio/video messages for +busy, unavailable and temporary messages. +Account specific directories will be created if they do not exist. + +The option selects message to be recorded: + u Unavailable + b Busy + t Temporary (overrides busy and unavailable) + n Account name + +Result is given in channel variable MINIVM_ACCMESS_STATUS + The possible values are: SUCCESS | FAILED + FAILED is set if the file can't be created. + + +\end{verbatim} + + +\section{MinivmDelete} +\subsection{Synopsis} +\begin{verbatim} +Delete Mini-Voicemail voicemail messages +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmDelete(filename) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +It deletes voicemail file set in MVM_FILENAME or given filename. + +Result is given in channel variable MINIVM_DELETE_STATUS + The possible values are: SUCCESS | FAILED + FAILED is set if the file does not exist or can't be deleted. + + +\end{verbatim} + + +\section{MinivmGreet} +\subsection{Synopsis} +\begin{verbatim} +Play Mini-Voicemail prompts +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmGreet(username@domain[,options]) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +MinivmGreet() plays default prompts or user specific prompts for an account. +Busy and unavailable messages can be choosen, but will be overridden if a temporary +message exists for the account. + +Result is given in channel variable MINIVM_GREET_STATUS + The possible values are: SUCCESS | USEREXIT | FAILED + + Options: + b - Play the 'busy' greeting to the calling party. + s - Skip the playback of instructions for leaving a message to the + calling party. + u - Play the 'unavailable greeting. + + +\end{verbatim} + + +\section{MinivmNotify} +\subsection{Synopsis} +\begin{verbatim} +Notify voicemail owner about new messages. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmNotify(username@domain[,template]) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +MiniVMnotify forwards messages about new voicemail to e-mail and pager. +If there's no user account for that address, a temporary account will +be used with default options (set in minivm.conf). +The recorded file name and path will be read from MVM_FILENAME and the +duration of the message will be accessed from MVM_DURATION (set by MinivmRecord() ) +If the channel variable MVM_COUNTER is set, this will be used in the +message file name and available in the template for the message. +If not template is given, the default email template will be used to send email and +default pager template to send paging message (if the user account is configured with +a paging address. + +Result is given in channel variable MINIVM_NOTIFY_STATUS + The possible values are: SUCCESS | FAILED + + +\end{verbatim} + + +\section{MinivmRecord} +\subsection{Synopsis} +\begin{verbatim} +Receive Mini-Voicemail and forward via e-mail +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmRecord(username@domain[,options]) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +MiniVM records audio file in configured format and forwards message to e-mail and pager. +If there's no user account for that address, a temporary account will +be used with default options. +The recorded file name and path will be stored in MINIVM_FILENAME and the +duration of the message will be stored in MINIVM_DURATION + +Note: If the caller hangs up after the recording, the only way to send +the message and clean up is to execute in the "h" extension. + +The application will exit if any of the following DTMF digits are +received and the requested extension exist in the current context. + 0 - Jump to the 'o' extension in the current dialplan context. + * - Jump to the 'a' extension in the current dialplan context. + +Result is given in channel variable MINIVM_RECORD_STATUS + The possible values are: SUCCESS | USEREXIT | FAILED + + Options: + g(#) - Use the specified amount of gain when recording the voicemail + message. The units are whole-number decibels (dB). + + +\end{verbatim} + + \section{MixMonitor} \subsection{Synopsis} \begin{verbatim} @@ -1721,6 +1783,7 @@ destroyed when the original caller leaves. Valid options are: d - full duplex audio q - quiet, do not play beep to caller r - record the page into a file (see 'r' for app_meetme) + s - only dial channel if devicestate says it is not in use \end{verbatim} @@ -1936,28 +1999,30 @@ Queue a call for a call queue \end{verbatim} \subsection{Description} \begin{verbatim} - Queue(queuename[|options[|URL][|announceoverride][|timeout][|AGI]): + Queue(queuename[|options[|URL][|announceoverride][|timeout][|AGI][|macro]): Queues an incoming call in a particular call queue as defined in queues.conf. This application will return to the dialplan if the queue does not exist, or any of the join options cause the caller to not enter the queue. The option string may contain zero or more of the following characters: 'd' -- data-quality (modem) call (minimum delay). - 'h' -- allow callee to hang up by hitting *. - 'H' -- allow caller to hang up by hitting *. + 'h' -- allow callee to hang up by pressing *. + 'H' -- allow caller to hang up by pressing *. 'n' -- no retries on the timeout; will exit this application and go to the next step. 'i' -- ignore call forward requests from queue members and do nothing when they are requested. - 'r' -- ring instead of playing MOH - 't' -- allow the called user transfer the calling user - 'T' -- to allow the calling user to transfer the call. - 'w' -- allow the called user to write the conversation to disk via Monitor - 'W' -- allow the calling user to write the conversation to disk via Monitor + 'r' -- ring instead of playing MOH. + 't' -- allow the called user to transfer the calling user. + 'T' -- allow the calling user to transfer the call. + 'w' -- allow the called user to write the conversation to disk via Monitor. + 'W' -- allow the calling user to write the conversation to disk via Monitor. In addition to transferring the call, a call may be parked and then picked up by another user. The optional URL will be sent to the called party if the channel supports it. The optional AGI parameter will setup an AGI script to be executed on the +calling party's channel once they are connected to a queue member. + The optional macro parameter will run a macro on the calling party's channel once they are connected to a queue member. The timeout will cause the queue to fail out after a specified number of seconds, checked between each queues.conf 'timeout' and 'retry' cycle. @@ -1982,20 +2047,6 @@ Example: QueueLog(101|${UNIQUEID}|${AGENT}|WENTONBREAK|600) \end{verbatim} -\section{Random} -\subsection{Synopsis} -\begin{verbatim} -Conditionally branches, based upon a probability -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Random([probability]:[[context|]extension|]priority) - probability := INTEGER in the range 1 to 100 -DEPRECATED: Use GotoIf($[${RAND(1,100)} > ]?