This finishes the changes for making Macro args LOCAL to the call, and allowing users...
[asterisk/asterisk.git] / doc / ast_appdocs.tex
1 % This file is automatically generated.  Any manual edits will be lost.
2 \section{AddQueueMember}
3 \subsection{Synopsis}
4 \begin{verbatim}
5 Dynamically adds queue members
6 \end{verbatim}
7 \subsection{Description}
8 \begin{verbatim}
9    AddQueueMember(queuename[|interface[|penalty[|options[|membername]]]]):
10 Dynamically adds interface to an existing queue.
11 If the interface is already in the queue it will return an error.
12   This application sets the following channel variable upon completion:
13      AQMSTATUS    The status of the attempt to add a queue member as a 
14                      text string, one of
15            ADDED | MEMBERALREADY | NOSUCHQUEUE 
16 Example: AddQueueMember(techsupport|SIP/3000)
17
18 \end{verbatim}
19
20
21 \section{ADSIProg}
22 \subsection{Synopsis}
23 \begin{verbatim}
24 Load Asterisk ADSI Scripts into phone
25 \end{verbatim}
26 \subsection{Description}
27 \begin{verbatim}
28   ADSIProg(script): This application programs an ADSI Phone with the given
29 script. If nothing is specified, the default script (asterisk.adsi) is used.
30
31 \end{verbatim}
32
33
34 \section{AgentLogin}
35 \subsection{Synopsis}
36 \begin{verbatim}
37 Call agent login
38 \end{verbatim}
39 \subsection{Description}
40 \begin{verbatim}
41   AgentLogin([AgentNo][|options]):
42 Asks the agent to login to the system.  Always returns -1.  While
43 logged in, the agent can receive calls and will hear a 'beep'
44 when a new call comes in. The agent can dump the call by pressing
45 the star key.
46 The option string may contain zero or more of the following characters:
47       's' -- silent login - do not announce the login ok segment after agent logged in/off
48
49 \end{verbatim}
50
51
52 \section{AgentMonitorOutgoing}
53 \subsection{Synopsis}
54 \begin{verbatim}
55 Record agent's outgoing call
56 \end{verbatim}
57 \subsection{Description}
58 \begin{verbatim}
59   AgentMonitorOutgoing([options]):
60 Tries to figure out the id of the agent who is placing outgoing call based on
61 comparison of the callerid of the current interface and the global variable 
62 placed by the AgentCallbackLogin application. That's why it should be used only
63 with the AgentCallbackLogin app. Uses the monitoring functions in chan_agent 
64 instead of Monitor application. That have to be configured in the agents.conf file.
65
66 Return value:
67 Normally the app returns 0 unless the options are passed.
68
69 Options:
70         'd' - make the app return -1 if there is an error condition     'c' - change the CDR so that the source of the call is 'Agent/agent_id'
71         'n' - don't generate the warnings when there is no callerid or the
72               agentid is not known.
73              It's handy if you want to have one context for agent and non-agent calls.
74
75 \end{verbatim}
76
77
78 \section{AGI}
79 \subsection{Synopsis}
80 \begin{verbatim}
81 Executes an AGI compliant application
82 \end{verbatim}
83 \subsection{Description}
84 \begin{verbatim}
85   [E|Dead]AGI(command|args): Executes an Asterisk Gateway Interface compliant
86 program on a channel. AGI allows Asterisk to launch external programs
87 written in any language to control a telephony channel, play audio,
88 read DTMF digits, etc. by communicating with the AGI protocol on stdin
89 and stdout.
90   This channel will stop dialplan execution on hangup inside of this
91 application, except when using DeadAGI.  Otherwise, dialplan execution
92 will continue normally.
93   A locally executed AGI script will receive SIGHUP on hangup from the channel
94 except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel
95 variable to "no" before executing the AGI application.
96   Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
97 on file descriptor 3
98
99   Use the CLI command 'agi show' to list available agi commands
100   This application sets the following channel variable upon completion:
101      AGISTATUS      The status of the attempt to the run the AGI script
102                     text string, one of SUCCESS | FAILED | HANGUP
103
104 \end{verbatim}
105
106
107 \section{AlarmReceiver}
108 \subsection{Synopsis}
109 \begin{verbatim}
110 Provide support for receiving alarm reports from a burglar or fire alarm panel
111 \end{verbatim}
112 \subsection{Description}
113 \begin{verbatim}
114   AlarmReceiver(): Only 1 signalling format is supported at this time: Ademco
115 Contact ID. This application should be called whenever there is an alarm
116 panel calling in to dump its events. The application will handshake with the
117 alarm panel, and receive events, validate them, handshake them, and store them
118 until the panel hangs up. Once the panel hangs up, the application will run the
119 system command specified by the eventcmd setting in alarmreceiver.conf and pipe
120 the events to the standard input of the application. The configuration file also
121 contains settings for DTMF timing, and for the loudness of the acknowledgement
122 tones.
123
124 \end{verbatim}
125
126
127 \section{AMD}
128 \subsection{Synopsis}
129 \begin{verbatim}
130 Attempts to detect answering machines
131 \end{verbatim}
132 \subsection{Description}
133 \begin{verbatim}
134   AMD([initialSilence][|greeting][|afterGreetingSilence][|totalAnalysisTime]
135       [|minimumWordLength][|betweenWordsSilence][|maximumNumberOfWords]
136       [|silenceThreshold])
137   This application attempts to detect answering machines at the beginning
138   of outbound calls.  Simply call this application after the call
139   has been answered (outbound only, of course).
140   When loaded, AMD reads amd.conf and uses the parameters specified as
141   default values. Those default values get overwritten when calling AMD
142   with parameters.
143 - 'initialSilence' is the maximum silence duration before the greeting. If
144    exceeded then MACHINE.
145 - 'greeting' is the maximum length of a greeting. If exceeded then MACHINE.
146 - 'afterGreetingSilence' is the silence after detecting a greeting.
147    If exceeded then HUMAN.
148 - 'totalAnalysisTime' is the maximum time allowed for the algorithm to decide
149    on a HUMAN or MACHINE.
150 - 'minimumWordLength'is the minimum duration of Voice to considered as a word.
151 - 'betweenWordsSilence' is the minimum duration of silence after a word to 
152    consider the audio that follows as a new word.
153 - 'maximumNumberOfWords'is the maximum number of words in the greeting. 
154    If exceeded then MACHINE.
155 - 'silenceThreshold' is the silence threshold.
156 This application sets the following channel variable upon completion:
157     AMDSTATUS - This is the status of the answering machine detection.
158                 Possible values are:
159                 MACHINE | HUMAN | NOTSURE | HANGUP
160     AMDCAUSE - Indicates the cause that led to the conclusion.
161                Possible values are:
162                TOOLONG-<%d total_time>
163                INITIALSILENCE-<%d silenceDuration>-<%d initialSilence>
164                HUMAN-<%d silenceDuration>-<%d afterGreetingSilence>
165                MAXWORDS-<%d wordsCount>-<%d maximumNumberOfWords>
166                LONGGREETING-<%d voiceDuration>-<%d greeting>
167
168 \end{verbatim}
169
170
171 \section{Answer}
172 \subsection{Synopsis}
173 \begin{verbatim}
174 Answer a channel if ringing
175 \end{verbatim}
176 \subsection{Description}
177 \begin{verbatim}
178   Answer([delay]): If the call has not been answered, this application will
179 answer it. Otherwise, it has no effect on the call. If a delay is specified,
180 Asterisk will wait this number of milliseconds before returning to
181 the dialplan after answering the call.
182
183 \end{verbatim}
184
185
186 \section{Authenticate}
187 \subsection{Synopsis}
188 \begin{verbatim}
189 Authenticate a user
190 \end{verbatim}
191 \subsection{Description}
192 \begin{verbatim}
193   Authenticate(password[|options[|maxdigits]]): This application asks the caller
194 to enter a given password in order to continue dialplan execution. If the password
195 begins with the '/' character, it is interpreted as a file which contains a list of
196 valid passwords, listed 1 password per line in the file.
197   When using a database key, the value associated with the key can be anything.
198 Users have three attempts to authenticate before the channel is hung up.
199   Options:
200      a - Set the channels' account code to the password that is entered
201      d - Interpret the given path as database key, not a literal file
202      m - Interpret the given path as a file which contains a list of account
203          codes and password hashes delimited with ':', listed one per line in
204          the file. When one of the passwords is matched, the channel will have
205          its account code set to the corresponding account code in the file.
206      r - Remove the database key upon successful entry (valid with 'd' only)
207      maxdigits  - maximum acceptable number of digits. Stops reading after
208          maxdigits have been entered (without requiring the user to
209          press the '#' key).
210          Defaults to 0 - no limit - wait for the user press the '#' key.
211
212 \end{verbatim}
213
214
215 \section{BackGround}
216 \subsection{Synopsis}
217 \begin{verbatim}
218 Play an audio file while waiting for digits of an extension to go to.
219 \end{verbatim}
220 \subsection{Description}
221 \begin{verbatim}
222   Background(filename1[&filename2...][|options[|langoverride][|context]]):
223 This application will play the given list of files while waiting for an
224 extension to be dialed by the calling channel. To continue waiting for digits
225 after this application has finished playing files, the WaitExten application
226 should be used. The 'langoverride' option explicitly specifies which language
227 to attempt to use for the requested sound files. If a 'context' is specified,
228 this is the dialplan context that this application will use when exiting to a
229 dialed extension.  If one of the requested sound files does not exist, call processing will be
230 terminated.
231   Options:
232     s - Causes the playback of the message to be skipped
233           if the channel is not in the 'up' state (i.e. it
234           hasn't been answered yet). If this happens, the
235           application will return immediately.
236     n - Don't answer the channel before playing the files.
237     m - Only break if a digit hit matches a one digit
238           extension in the destination context.
239 This application sets the following channel variable upon completion:
240  BACKGROUNDSTATUS    The status of the background attempt as a text string, one of
241                SUCCESS | FAILED
242
243 \end{verbatim}
244
245
246 \section{BackgroundDetect}
247 \subsection{Synopsis}
248 \begin{verbatim}
249 Background a file with talk detect
250 \end{verbatim}
251 \subsection{Description}
252 \begin{verbatim}
253   BackgroundDetect(filename[|sil[|min|[max]]]):  Plays  back  a  given
254 filename, waiting for interruption from a given digit (the digit must
255 start the beginning of a valid extension, or it will be ignored).
256 During the playback of the file, audio is monitored in the receive
257 direction, and if a period of non-silence which is greater than 'min' ms
258 yet less than 'max' ms is followed by silence for at least 'sil' ms then
259 the audio playback is aborted and processing jumps to the 'talk' extension
260 if available.  If unspecified, sil, min, and max default to 1000, 100, and
261 infinity respectively.
262
263 \end{verbatim}
264
265
266 \section{Bridge}
267 \subsection{Synopsis}
268 \begin{verbatim}
269 Bridge two channels
270 \end{verbatim}
271 \subsection{Description}
272 \begin{verbatim}
273 Usage: Bridge(channel[|options])
274         Allows the ability to bridge two channels via the dialplan.
275 The current channel is bridged to the specified 'channel'.
276 The following options are supported:
277    p - Play a courtesy tone to 'channel'.
278 BRIDGERESULT dial plan variable will contain SUCCESS, FAILURE, LOOP, NONEXISTENT or INCOMPATIBLE.
279
280 \end{verbatim}
281
282
283 \section{Busy}
284 \subsection{Synopsis}
285 \begin{verbatim}
286 Indicate the Busy condition
287 \end{verbatim}
288 \subsection{Description}
289 \begin{verbatim}
290   Busy([timeout]): This application will indicate the busy condition to
291 the calling channel. If the optional timeout is specified, the calling channel
292 will be hung up after the specified number of seconds. Otherwise, this
293 application will wait until the calling channel hangs up.
294
295 \end{verbatim}
296
297
298 \section{ChangeMonitor}
299 \subsection{Synopsis}
300 \begin{verbatim}
301 Change monitoring filename of a channel
302 \end{verbatim}
303 \subsection{Description}
304 \begin{verbatim}
305 ChangeMonitor(filename_base)
306 Changes monitoring filename of a channel. Has no effect if the channel is not monitored
307 The argument is the new filename base to use for monitoring this channel.
308
309 \end{verbatim}
310
311
312 \section{ChanIsAvail}
313 \subsection{Synopsis}
314 \begin{verbatim}
315 Check channel availability
316 \end{verbatim}
317 \subsection{Description}
318 \begin{verbatim}
319   ChanIsAvail(Technology/resource[&Technology2/resource2...][|options]): 
320 This application will check to see if any of the specified channels are
321 available. The following variables will be set by this application:
322   ${AVAILCHAN}     - the name of the available channel, if one exists
323   ${AVAILORIGCHAN} - the canonical channel name that was used to create the channel
324   ${AVAILSTATUS}   - the status code for the available channel
325   Options:
326     s - Consider the channel unavailable if the channel is in use at all
327     t - Simply checks if specified channels exist in the channel list
328         (implies option s) 
329
330 \end{verbatim}
331
332
333 \section{ChannelRedirect}
334 \subsection{Synopsis}
335 \begin{verbatim}
336 Redirects given channel to a dialplan target.
337 \end{verbatim}
338 \subsection{Description}
339 \begin{verbatim}
340 ChannelRedirect(channel|[[context|]extension|]priority):
341   Sends the specified channel to the specified extension priority
342
343 \end{verbatim}
344
345
346 \section{ChanSpy}
347 \subsection{Synopsis}
348 \begin{verbatim}
349 Listen to a channel, and optionally whisper into it
350 \end{verbatim}
351 \subsection{Description}
352 \begin{verbatim}
353   ChanSpy([chanprefix][|options]): This application is used to listen to the
354 audio from an Asterisk channel. This includes the audio coming in and
355 out of the channel being spied on. If the 'chanprefix' parameter is specified,
356 only channels beginning with this string will be spied upon.
357   While spying, the following actions may be performed:
358     - Dialing # cycles the volume level.
359     - Dialing * will stop spying and look for another channel to spy on.
360     - Dialing a series of digits followed by # builds a channel name to append
361       to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing
362       the digits '1234#' while spying will begin spying on the channel
363       'Agent/1234'.
364   Note: The X option supersedes the three features above in that if a valid
365         single digit extension exists in the correct context ChanSpy will
366         exit to it. This also disables choosing a channel based on 'chanprefix'
367         and a digit sequence.
368   Options:
369     b             - Only spy on channels involved in a bridged call.
370     g(grp)        - Match only channels where their ${SPYGROUP} variable is set to
371                     contain 'grp' in an optional : delimited list.
372     q             - Don't play a beep when beginning to spy on a channel, or speak the
373                     selected channel name.
374     r[(basename)] - Record the session to the monitor spool directory. An
375                     optional base for the filename may be specified. The
376                     default is 'chanspy'.
377     v([value])    - Adjust the initial volume in the range from -4 to 4. A
378                     negative value refers to a quieter setting.
379     w             - Enable 'whisper' mode, so the spying channel can talk to
380                     the spied-on channel.
381     W             - Enable 'private whisper' mode, so the spying channel can
382                     talk to the spied-on channel but cannot listen to that
383                     channel.
384     o             - Only listen to audio coming from this channel.
385     X             - Allow the user to exit ChanSpy to a valid single digit
386                     numeric extension in the current context or the context
387                     specified by the SPY_EXIT_CONTEXT channel variable. The
388                     name of the last channel that was spied on will be stored
389                     in the SPY_CHANNEL variable.
390
391 \end{verbatim}
392
393
394 \section{ClearHash}
395 \subsection{Synopsis}
396 \begin{verbatim}
397 Clear the keys from a specified hashname
398 \end{verbatim}
399 \subsection{Description}
400 \begin{verbatim}
401 ClearHash(<hashname>)
402   Clears all keys out of the specified hashname
403
404 \end{verbatim}
405
406
407 \section{Congestion}
408 \subsection{Synopsis}
409 \begin{verbatim}
410 Indicate the Congestion condition
411 \end{verbatim}
412 \subsection{Description}
413 \begin{verbatim}
414   Congestion([timeout]): This application will indicate the congestion
415 condition to the calling channel. If the optional timeout is specified, the
416 calling channel will be hung up after the specified number of seconds.
417 Otherwise, this application will wait until the calling channel hangs up.
418
419 \end{verbatim}
420
421
422 \section{ContinueWhile}
423 \subsection{Synopsis}
424 \begin{verbatim}
425 Restart a While loop
426 \end{verbatim}
427 \subsection{Description}
428 \begin{verbatim}
429 Usage:  ContinueWhile()
430 Returns to the top of the while loop and re-evaluates the conditional.
431
432 \end{verbatim}
433
434
435 \section{ControlPlayback}
436 \subsection{Synopsis}
437 \begin{verbatim}
438 Play a file with fast forward and rewind
439 \end{verbatim}
440 \subsection{Description}
441 \begin{verbatim}
442   ControlPlayback(file[|skipms[|ff[|rew[|stop[|pause[|restart|options]]]]]]]):
443 This application will play back the given filename. By default, the '*' key
444 can be used to rewind, and the '#' key can be used to fast-forward.
445 Parameters:
446   skipms  - This is number of milliseconds to skip when rewinding or
447             fast-forwarding.
448   ff      - Fast-forward when this DTMF digit is received.
449   rew     - Rewind when this DTMF digit is received.
450   stop    - Stop playback when this DTMF digit is received.
451   pause   - Pause playback when this DTMF digit is received.
452   restart - Restart playback when this DTMF digit is received.
453 Options:
454   o(#) - Start at # ms from the beginning of the file.
455 This application sets the following channel variables upon completion:
456   CPLAYBACKSTATUS -  This variable contains the status of the attempt as a text
457                      string, one of: SUCCESS | USERSTOPPED | ERROR
458   CPLAYBACKOFFSET -  This contains the offset in ms into the file where
459                      playback was at when it stopped.  -1 is end of file.
460
461 \end{verbatim}
462
463
464 \section{DateTime}
465 \subsection{Synopsis}
466 \begin{verbatim}
467 Says a specified time in a custom format
468 \end{verbatim}
469 \subsection{Description}
470 \begin{verbatim}
471 DateTime([unixtime][|[timezone][|format]])
472   unixtime: time, in seconds since Jan 1, 1970.  May be negative.
473               defaults to now.
474   timezone: timezone, see /usr/share/zoneinfo for a list.
475               defaults to machine default.
476   format:   a format the time is to be said in.  See voicemail.conf.
477               defaults to "ABdY 'digits/at' IMp"
478
479 \end{verbatim}
480
481
482 \section{DBdel}
483 \subsection{Synopsis}
484 \begin{verbatim}
485 Delete a key from the database
486 \end{verbatim}
487 \subsection{Description}
488 \begin{verbatim}
489   DBdel(family/key): This application will delete a key from the Asterisk
490 database.
491   This application has been DEPRECATED in favor of the DB_DELETE function.
492
493 \end{verbatim}
494
495
496 \section{DBdeltree}
497 \subsection{Synopsis}
498 \begin{verbatim}
499 Delete a family or keytree from the database
500 \end{verbatim}
501 \subsection{Description}
502 \begin{verbatim}
503   DBdeltree(family[/keytree]): This application will delete a family or keytree
504 from the Asterisk database
505
506 \end{verbatim}
507
508
509 \section{DeadAGI}
510 \subsection{Synopsis}
511 \begin{verbatim}
512 Executes AGI on a hungup channel
513 \end{verbatim}
514 \subsection{Description}
515 \begin{verbatim}
516   [E|Dead]AGI(command|args): Executes an Asterisk Gateway Interface compliant
517 program on a channel. AGI allows Asterisk to launch external programs
518 written in any language to control a telephony channel, play audio,
519 read DTMF digits, etc. by communicating with the AGI protocol on stdin
520 and stdout.
521   This channel will stop dialplan execution on hangup inside of this
522 application, except when using DeadAGI.  Otherwise, dialplan execution
523 will continue normally.
524   A locally executed AGI script will receive SIGHUP on hangup from the channel
525 except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel
526 variable to "no" before executing the AGI application.
527   Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
528 on file descriptor 3
529
530   Use the CLI command 'agi show' to list available agi commands
531   This application sets the following channel variable upon completion:
532      AGISTATUS      The status of the attempt to the run the AGI script
533                     text string, one of SUCCESS | FAILED | HANGUP
534
535 \end{verbatim}
536
537
538 \section{Dial}
539 \subsection{Synopsis}
540 \begin{verbatim}
541 Place a call and connect to the current channel
542 \end{verbatim}
543 \subsection{Description}
544 \begin{verbatim}
545   Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|URL]):
546 This application will place calls to one or more specified channels. As soon
547 as one of the requested channels answers, the originating channel will be
548 answered, if it has not already been answered. These two channels will then
549 be active in a bridged call. All other channels that were requested will then
550 be hung up.
551   Unless there is a timeout specified, the Dial application will wait
552 indefinitely until one of the called channels answers, the user hangs up, or
553 if all of the called channels are busy or unavailable. Dialplan executing will
554 continue if no requested channels can be called, or if the timeout expires.
555
556   This application sets the following channel variables upon completion:
557     DIALEDTIME   - This is the time from dialing a channel until when it
558                    is disconnected.
559     ANSWEREDTIME - This is the amount of time for actual call.
560     DIALSTATUS   - This is the status of the call:
561                    CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL
562                    DONTCALL | TORTURE | INVALIDARGS
563   For the Privacy and Screening Modes, the DIALSTATUS variable will be set to
564 DONTCALL if the called party chooses to send the calling party to the 'Go Away'
565 script. The DIALSTATUS variable will be set to TORTURE if the called party
566 wants to send the caller to the 'torture' script.
567   This application will report normal termination if the originating channel
568 hangs up, or if the call is bridged and either of the parties in the bridge
569 ends the call.
570   The optional URL will be sent to the called party if the channel supports it.
571   If the OUTBOUND_GROUP variable is set, all peer channels created by this
572 application will be put into that group (as in Set(GROUP()=...).
573   If the OUTBOUND_GROUP_ONCE variable is set, all peer channels created by this
574 application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP,
575 however, the variable will be unset after use.
576
577   Options:
578     A(x) - Play an announcement to the called party, using 'x' as the file.
579     C    - Reset the CDR for this call.
580     d    - Allow the calling user to dial a 1 digit extension while waiting for
581            a call to be answered. Exit to that extension if it exists in the
582            current context, or the context defined in the EXITCONTEXT variable,
583            if it exists.
584     D([called][:calling]) - Send the specified DTMF strings *after* the called
585            party has answered, but before the call gets bridged. The 'called'
586            DTMF string is sent to the called party, and the 'calling' DTMF
587            string is sent to the calling party. Both parameters can be used
588            alone.
589     f    - Force the callerid of the *calling* channel to be set as the
590            extension associated with the channel using a dialplan 'hint'.
591            For example, some PSTNs do not allow CallerID to be set to anything
592            other than the number assigned to the caller.
593     g    - Proceed with dialplan execution at the current extension if the
594            destination channel hangs up.
595     G(context^exten^pri) - If the call is answered, transfer the calling party to
596            the specified priority and the called party to the specified priority+1.
597            Optionally, an extension, or extension and context may be specified. 
598            Otherwise, the current extension is used. You cannot use any additional
599            action post answer options in conjunction with this option.
600     h    - Allow the called party to hang up by sending the '*' DTMF digit.
601     H    - Allow the calling party to hang up by hitting the '*' DTMF digit.
602     i    - Asterisk will ignore any forwarding requests it may receive on this
603            dial attempt.
604     L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms are
605            left. Repeat the warning every 'z' ms. The following special
606            variables can be used with this option:
607            * LIMIT_PLAYAUDIO_CALLER   yes|no (default yes)
608                                       Play sounds to the caller.
609            * LIMIT_PLAYAUDIO_CALLEE   yes|no
610                                       Play sounds to the callee.
611            * LIMIT_TIMEOUT_FILE       File to play when time is up.
612            * LIMIT_CONNECT_FILE       File to play when call begins.
613            * LIMIT_WARNING_FILE       File to play as warning if 'y' is defined.
614                                       The default is to say the time remaining.
615     m([class]) - Provide hold music to the calling party until a requested
616            channel answers. A specific MusicOnHold class can be
617            specified.
618     M(x[^arg]) - Execute the Macro for the *called* channel before connecting
619            to the calling channel. Arguments can be specified to the Macro
620            using '^' as a delimeter. The Macro can set the variable
621            MACRO_RESULT to specify the following actions after the Macro is
622            finished executing.
623            * ABORT        Hangup both legs of the call.
624            * CONGESTION   Behave as if line congestion was encountered.
625            * BUSY         Behave as if a busy signal was encountered.
626            * CONTINUE     Hangup the called party and allow the calling party
627                           to continue dialplan execution at the next priority.
628            * GOTO:<context>^<exten>^<priority> - Transfer the call to the
629                           specified priority. Optionally, an extension, or
630                           extension and priority can be specified.
631            You cannot use any additional action post answer options in conjunction
632            with this option. Also, pbx services are not run on the peer (called) channel,
633            so you will not be able to set timeouts via the TIMEOUT() function in this macro.
634     n    - This option is a modifier for the screen/privacy mode. It specifies
635            that no introductions are to be saved in the priv-callerintros
636            directory.
637     N    - This option is a modifier for the screen/privacy mode. It specifies
638            that if callerID is present, do not screen the call.
639     o    - Specify that the CallerID that was present on the *calling* channel
640            be set as the CallerID on the *called* channel. This was the
641            behavior of Asterisk 1.0 and earlier.
642     O([x]) - "Operator Services" mode (Zaptel channel to Zaptel channel
643              only, if specified on non-Zaptel interface, it will be ignored).
644              When the destination answers (presumably an operator services
645              station), the originator no longer has control of their line.
646              They may hang up, but the switch will not release their line
647              until the destination party hangs up (the operator). Specified
648              without an arg, or with 1 as an arg, the originator hanging up
649              will cause the phone to ring back immediately. With a 2 specified,
650              when the "operator" flashes the trunk, it will ring their phone
651              back.
652     p    - This option enables screening mode. This is basically Privacy mode
653            without memory.
654     P([x]) - Enable privacy mode. Use 'x' as the family/key in the database if
655            it is provided. The current extension is used if a database
656            family/key is not specified.
657     r    - Indicate ringing to the calling party. Pass no audio to the calling
658            party until the called channel has answered.
659     S(x) - Hang up the call after 'x' seconds *after* the called party has
660            answered the call.
661     t    - Allow the called party to transfer the calling party by sending the
662            DTMF sequence defined in features.conf.
663     T    - Allow the calling party to transfer the called party by sending the
664            DTMF sequence defined in features.conf.
665     w    - Allow the called party to enable recording of the call by sending
666            the DTMF sequence defined for one-touch recording in features.conf.
667     W    - Allow the calling party to enable recording of the call by sending
668            the DTMF sequence defined for one-touch recording in features.conf.
669     k    - Allow the called party to enable parking of the call by sending
670            the DTMF sequence defined for call parking in features.conf.
671     K    - Allow the calling party to enable parking of the call by sending
672            the DTMF sequence defined for call parking in features.conf.
673
674 \end{verbatim}
675
676
677 \section{Dictate}
678 \subsection{Synopsis}
679 \begin{verbatim}
680 Virtual Dictation Machine
681 \end{verbatim}
682 \subsection{Description}
683 \begin{verbatim}
684   Dictate([<base_dir>[|<filename>]])
685 Start dictation machine using optional base dir for files.
686
687 \end{verbatim}
688
689
690 \section{Directory}
691 \subsection{Synopsis}
692 \begin{verbatim}
693 Provide directory of voicemail extensions
694 \end{verbatim}
695 \subsection{Description}
696 \begin{verbatim}
697   Directory(vm-context[|dial-context[|options]]): This application will present
698 the calling channel with a directory of extensions from which they can search
699 by name. The list of names and corresponding extensions is retrieved from the
700 voicemail configuration file, voicemail.conf.
701   This application will immediately exit if one of the following DTMF digits are
702 received and the extension to jump to exists:
703     0 - Jump to the 'o' extension, if it exists.
704     * - Jump to the 'a' extension, if it exists.
705
706   Parameters:
707     vm-context   - This is the context within voicemail.conf to use for the
708                    Directory.
709     dial-context - This is the dialplan context to use when looking for an
710                    extension that the user has selected, or when jumping to the
711                    'o' or 'a' extension.
712
713   Options:
714     e - In addition to the name, also read the extension number to the
715         caller before presenting dialing options.
716     f - Allow the caller to enter the first name of a user in the directory
717         instead of using the last name.
718
719 \end{verbatim}
720
721
722 \section{DISA}
723 \subsection{Synopsis}
724 \begin{verbatim}
725 DISA (Direct Inward System Access)
726 \end{verbatim}
727 \subsection{Description}
728 \begin{verbatim}
729 DISA(<numeric passcode>[|<context>[|<cid>[|mailbox[|options]]]]) or
730 DISA(<filename>[||||options])
731 The DISA, Direct Inward System Access, application allows someone from 
732 outside the telephone switch (PBX) to obtain an "internal" system 
733 dialtone and to place calls from it as if they were placing a call from 
734 within the switch.
735 DISA plays a dialtone. The user enters their numeric passcode, followed by
736 the pound sign (#). If the passcode is correct, the user is then given
737 system dialtone within <context> on which a call may be placed. If the user
738 enters an invalid extension and extension "i" exists in the specified
739 context, it will be used.
740
741 If you need to present a DISA dialtone without entering a password, simply
742 set <passcode> to "no-password".
743
744 Be aware that using this may compromise the security of your PBX.
745
746 The arguments to this application (in extensions.conf) allow either
747 specification of a single global passcode (that everyone uses), or
748 individual passcodes contained in a file.
749
750 The file that contains the passcodes (if used) allows a complete
751 specification of all of the same arguments available on the command
752 line, with the sole exception of the options. The file may contain blank
753 lines, or comments starting with "#" or ";".
754
755 <context> specifies the dialplan context in which the user-entered extension
756 will be matched. If no context is specified, the DISA application defaults
757 the context to "disa". Presumably a normal system will have a special
758 context set up for DISA use with some or a lot of restrictions.
759
760 <cid> specifies a new (different) callerid to be used for this call.
761
762 <mailbox[@context]> will cause a stutter-dialtone (indication "dialrecall")
763 to be used, if the specified mailbox contains any new messages.
764
765 The following options are available:
766   n - the DISA application will not answer initially.
767   p - the extension entered will be considered complete when a '#' is entered.
768
769 \end{verbatim}
770
771
772 \section{DumpChan}
773 \subsection{Synopsis}
774 \begin{verbatim}
775 Dump Info About The Calling Channel
776 \end{verbatim}
777 \subsection{Description}
778 \begin{verbatim}
779    DumpChan([<min_verbose_level>])
780 Displays information on channel and listing of all channel
781 variables. If min_verbose_level is specified, output is only
782 displayed when the verbose level is currently set to that number
783 or greater. 
784
785 \end{verbatim}
786
787
788 \section{EAGI}
789 \subsection{Synopsis}
790 \begin{verbatim}
791 Executes an EAGI compliant application
792 \end{verbatim}
793 \subsection{Description}
794 \begin{verbatim}
795   [E|Dead]AGI(command|args): Executes an Asterisk Gateway Interface compliant
796 program on a channel. AGI allows Asterisk to launch external programs
797 written in any language to control a telephony channel, play audio,
798 read DTMF digits, etc. by communicating with the AGI protocol on stdin
799 and stdout.
800   This channel will stop dialplan execution on hangup inside of this
801 application, except when using DeadAGI.  Otherwise, dialplan execution
802 will continue normally.
803   A locally executed AGI script will receive SIGHUP on hangup from the channel
804 except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel
805 variable to "no" before executing the AGI application.
806   Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
807 on file descriptor 3
808
809   Use the CLI command 'agi show' to list available agi commands
810   This application sets the following channel variable upon completion:
811      AGISTATUS      The status of the attempt to the run the AGI script
812                     text string, one of SUCCESS | FAILED | HANGUP
813
814 \end{verbatim}
815
816
817 \section{Echo}
818 \subsection{Synopsis}
819 \begin{verbatim}
820 Echo audio, video, or DTMF back to the calling party
821 \end{verbatim}
822 \subsection{Description}
823 \begin{verbatim}
824   Echo(): This application will echo any audio, video, or DTMF frames read from
825 the calling channel back to itself. If the DTMF digit '#' is received, the
826 application will exit.
827
828 \end{verbatim}
829
830
831 \section{EndWhile}
832 \subsection{Synopsis}
833 \begin{verbatim}
834 End a while loop
835 \end{verbatim}
836 \subsection{Description}
837 \begin{verbatim}
838 Usage:  EndWhile()
839 Return to the previous called While
840
841 \end{verbatim}
842
843
844 \section{Exec}
845 \subsection{Synopsis}
846 \begin{verbatim}
847 Executes dialplan application
848 \end{verbatim}
849 \subsection{Description}
850 \begin{verbatim}
851 Usage: Exec(appname(arguments))
852   Allows an arbitrary application to be invoked even when not
853 hardcoded into the dialplan.  If the underlying application
854 terminates the dialplan, or if the application cannot be found,
855 Exec will terminate the dialplan.
856   To invoke external applications, see the application System.
857   If you would like to catch any error instead, see TryExec.
858
859 \end{verbatim}
860
861
862 \section{ExecIf}
863 \subsection{Synopsis}
864 \begin{verbatim}
865 Executes dialplan application, conditionally
866 \end{verbatim}
867 \subsection{Description}
868 \begin{verbatim}
869 Usage:  ExecIF (<expr>|<app>|<data>)
870 If <expr> is true, execute and return the result of <app>(<data>).
871 If <expr> is true, but <app> is not found, then the application
872 will return a non-zero value.
873
874 \end{verbatim}
875
876
877 \section{ExecIfTime}
878 \subsection{Synopsis}
879 \begin{verbatim}
880 Conditional application execution based on the current time
881 \end{verbatim}
882 \subsection{Description}
883 \begin{verbatim}
884   ExecIfTime(<times>|<weekdays>|<mdays>|<months>?appname[|appargs]):
885 This application will execute the specified dialplan application, with optional
886 arguments, if the current time matches the given time specification.
887
888 \end{verbatim}
889
890
891 \section{ExitWhile}
892 \subsection{Synopsis}
893 \begin{verbatim}
894 End a While loop
895 \end{verbatim}
896 \subsection{Description}
897 \begin{verbatim}
898 Usage:  ExitWhile()
899 Exits a While loop, whether or not the conditional has been satisfied.
900
901 \end{verbatim}
902
903
904 \section{ExtenSpy}
905 \subsection{Synopsis}
906 \begin{verbatim}
907 Listen to a channel, and optionally whisper into it
908 \end{verbatim}
909 \subsection{Description}
910 \begin{verbatim}
911   ExtenSpy(exten[@context][|options]): This application is used to listen to the
912 audio from an Asterisk channel. This includes the audio coming in and
913 out of the channel being spied on. Only channels created by outgoing calls for the
914 specified extension will be selected for spying. If the optional context is not
915 supplied, the current channel's context will be used.
916   While spying, the following actions may be performed:
917     - Dialing # cycles the volume level.
918     - Dialing * will stop spying and look for another channel to spy on.
919   Note: The X option superseeds the two features above in that if a valid
920         single digit extension exists in the correct context it ChanSpy will
921         exit to it.
922   Options:
923     b             - Only spy on channels involved in a bridged call.
924     g(grp)        - Match only channels where their ${SPYGROUP} variable is set to
925                     contain 'grp' in an optional : delimited list.
926     q             - Don't play a beep when beginning to spy on a channel, or speak the
927                     selected channel name.
928     r[(basename)] - Record the session to the monitor spool directory. An
929                     optional base for the filename may be specified. The
930                     default is 'chanspy'.
931     v([value])    - Adjust the initial volume in the range from -4 to 4. A
932                     negative value refers to a quieter setting.
933     w             - Enable 'whisper' mode, so the spying channel can talk to
934                     the spied-on channel.
935     W             - Enable 'private whisper' mode, so the spying channel can
936                     talk to the spied-on channel but cannot listen to that
937                     channel.
938     o             - Only listen to audio coming from this channel.
939     X             - Allow the user to exit ChanSpy to a valid single digit
940                     numeric extension in the current context or the context
941                     specified by the SPY_EXIT_CONTEXT channel variable. The
942                     name of the last channel that was spied on will be stored
943                     in the SPY_CHANNEL variable.
944
945 \end{verbatim}
946
947
948 \section{ExternalIVR}
949 \subsection{Synopsis}
950 \begin{verbatim}
951 Interfaces with an external IVR application
952 \end{verbatim}
953 \subsection{Description}
954 \begin{verbatim}
955   ExternalIVR(command[|arg[|arg...]]): Forks an process to run the supplied command,
956 and starts a generator on the channel. The generator's play list is
957 controlled by the external application, which can add and clear entries
958 via simple commands issued over its stdout. The external application
959 will receive all DTMF events received on the channel, and notification
960 if the channel is hung up. The application will not be forcibly terminated
961 when the channel is hung up.
962 See doc/externalivr.txt for a protocol specification.
963
964 \end{verbatim}
965
966
967 \section{Festival}
968 \subsection{Synopsis}
969 \begin{verbatim}
970 Say text to the user
971 \end{verbatim}
972 \subsection{Description}
973 \begin{verbatim}
974   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
975 the value, or 'any' to allow any number back (useful in dialplan)
976
977 \end{verbatim}
978
979
980 \section{Flash}
981 \subsection{Synopsis}
982 \begin{verbatim}
983 Flashes a Zap Trunk
984 \end{verbatim}
985 \subsection{Description}
986 \begin{verbatim}
987   Flash(): Sends a flash on a zap trunk.  This is only a hack for
988 people who want to perform transfers and such via AGI and is generally
989 quite useless oths application will only work on Zap trunks.
990
991 \end{verbatim}
992
993
994 \section{FollowMe}
995 \subsection{Synopsis}
996 \begin{verbatim}
997 Find-Me/Follow-Me application
998 \end{verbatim}
999 \subsection{Description}
1000 \begin{verbatim}
1001   FollowMe(followmeid|options):
1002 This application performs Find-Me/Follow-Me functionality for the caller
1003 as defined in the profile matching the <followmeid> parameter in
1004 followme.conf. If the specified <followmeid> profile doesn't exist in
1005 followme.conf, execution will be returned to the dialplan and call
1006 execution will continue at the next priority.
1007
1008   Options:
1009     s    - Playback the incoming status message prior to starting the follow-me step(s)
1010     a    - Record the caller's name so it can be announced to the callee on each step
1011     n    - Playback the unreachable status message if we've run out of steps to reach the
1012            or the callee has elected not to be reachable.
1013 Returns -1 on hangup
1014
1015 \end{verbatim}
1016
1017
1018 \section{ForkCDR}
1019 \subsection{Synopsis}
1020 \begin{verbatim}
1021 Forks the Call Data Record
1022 \end{verbatim}
1023 \subsection{Description}
1024 \begin{verbatim}
1025   ForkCDR([options]):  Causes the Call Data Record to fork an additional
1026 cdr record starting from the time of the fork call
1027 If the option 'v' is passed all cdr variables will be passed along also.
1028
1029 \end{verbatim}
1030
1031
1032 \section{GetCPEID}
1033 \subsection{Synopsis}
1034 \begin{verbatim}
1035 Get ADSI CPE ID
1036 \end{verbatim}
1037 \subsection{Description}
1038 \begin{verbatim}
1039   GetCPEID: Obtains and displays ADSI CPE ID and other information in order
1040 to properly setup zapata.conf for on-hook operations.
1041
1042 \end{verbatim}
1043
1044
1045 \section{Gosub}
1046 \subsection{Synopsis}
1047 \begin{verbatim}
1048 Jump to label, saving return address
1049 \end{verbatim}
1050 \subsection{Description}
1051 \begin{verbatim}
1052 Gosub([[context|]exten|]priority[(arg1[|...][|argN])])
1053   Jumps to the label specified, saving the return address.
1054
1055 \end{verbatim}
1056
1057
1058 \section{GosubIf}
1059 \subsection{Synopsis}
1060 \begin{verbatim}
1061 Conditionally jump to label, saving return address
1062 \end{verbatim}
1063 \subsection{Description}
1064 \begin{verbatim}
1065 GosubIf(condition?labeliftrue[(arg1[|...])][:labeliffalse[(arg1[|...])]])
1066   If the condition is true, then jump to labeliftrue.  If false, jumps to
1067 labeliffalse, if specified.  In either case, a jump saves the return point
1068 in the dialplan, to be returned to with a Return.
1069
1070 \end{verbatim}
1071
1072
1073 \section{Goto}
1074 \subsection{Synopsis}
1075 \begin{verbatim}
1076 Jump to a particular priority, extension, or context
1077 \end{verbatim}
1078 \subsection{Description}
1079 \begin{verbatim}
1080   Goto([[context|]extension|]priority): This application will set the current
1081 context, extension, and priority in the channel structure. After it completes, the
1082 pbx engine will continue dialplan execution at the specified location.
1083 If no specific extension, or extension and context, are specified, then this
1084 application will just set the specified priority of the current extension.
1085   At least a priority is required as an argument, or the goto will return a -1,
1086 and the channel and call will be terminated.
1087   If the location that is put into the channel information is bogus, and asterisk cannot
1088 find that location in the dialplan,
1089 then the execution engine will try to find and execute the code in the 'i' (invalid)
1090 extension in the current context. If that does not exist, it will try to execute the
1091 'h' extension. If either or neither the 'h' or 'i' extensions have been defined, the
1092 channel is hung up, and the execution of instructions on the channel is terminated.
1093 What this means is that, for example, you specify a context that does not exist, then
1094 it will not be possible to find the 'h' or 'i' extensions, and the call will terminate!
1095
1096 \end{verbatim}
1097
1098
1099 \section{GotoIf}
1100 \subsection{Synopsis}
1101 \begin{verbatim}
1102 Conditional goto
1103 \end{verbatim}
1104 \subsection{Description}
1105 \begin{verbatim}
1106   GotoIf(condition?[labeliftrue]:[labeliffalse]): This application will set the current
1107 context, extension, and priority in the channel structure based on the evaluation of
1108 the given condition. After this application completes, the
1109 pbx engine will continue dialplan execution at the specified location in the dialplan.
1110 The channel will continue at
1111 'labeliftrue' if the condition is true, or 'labeliffalse' if the condition is
1112 false. The labels are specified with the same syntax as used within the Goto
1113 application.  If the label chosen by the condition is omitted, no jump is
1114 performed, and the execution passes to the next instruction.
1115 If the target location is bogus, and does not exist, the execution engine will try 
1116 to find and execute the code in the 'i' (invalid)
1117 extension in the current context. If that does not exist, it will try to execute the
1118 'h' extension. If either or neither the 'h' or 'i' extensions have been defined, the
1119 channel is hung up, and the execution of instructions on the channel is terminated.
1120 Remember that this command can set the current context, and if the context specified
1121 does not exist, then it will not be able to find any 'h' or 'i' extensions there, and
1122 the channel and call will both be terminated!
1123
1124 \end{verbatim}
1125
1126
1127 \section{GotoIfTime}
1128 \subsection{Synopsis}
1129 \begin{verbatim}
1130 Conditional Goto based on the current time
1131 \end{verbatim}
1132 \subsection{Description}
1133 \begin{verbatim}
1134   GotoIfTime(<times>|<weekdays>|<mdays>|<months>?[[context|]exten|]priority):
1135 This application will set the context, extension, and priority in the channel structure
1136 if the current time matches the given time specification. Otherwise, nothing is done.
1137 Further information on the time specification can be found in examples
1138 illustrating how to do time-based context includes in the dialplan.
1139 If the target jump location is bogus, the same actions would be taken as for Goto.
1140
1141 \end{verbatim}
1142
1143
1144 \section{Hangup}
1145 \subsection{Synopsis}
1146 \begin{verbatim}
1147 Hang up the calling channel
1148 \end{verbatim}
1149 \subsection{Description}
1150 \begin{verbatim}
1151   Hangup([causecode]): This application will hang up the calling channel.
1152 If a causecode is given the channel's hangup cause will be set to the given
1153 value.
1154
1155 \end{verbatim}
1156
1157
1158 \section{IAX2Provision}
1159 \subsection{Synopsis}
1160 \begin{verbatim}
1161 Provision a calling IAXy with a given template
1162 \end{verbatim}
1163 \subsection{Description}
1164 \begin{verbatim}
1165   IAX2Provision([template]): Provisions the calling IAXy (assuming
1166 the calling entity is in fact an IAXy) with the given template or
1167 default if one is not specified.  Returns -1 on error or 0 on success.
1168
1169 \end{verbatim}
1170
1171
1172 \section{ICES}
1173 \subsection{Synopsis}
1174 \begin{verbatim}
1175 Encode and stream using 'ices'
1176 \end{verbatim}
1177 \subsection{Description}
1178 \begin{verbatim}
1179   ICES(config.xml) Streams to an icecast server using ices
1180 (available separately).  A configuration file must be supplied
1181 for ices (see examples/asterisk-ices.conf). 
1182
1183 \end{verbatim}
1184
1185
1186 \section{ImportVar}
1187 \subsection{Synopsis}
1188 \begin{verbatim}
1189 Import a variable from a channel into a new variable
1190 \end{verbatim}
1191 \subsection{Description}
1192 \begin{verbatim}
1193   ImportVar(newvar=channelname|variable): This application imports a variable
1194 from the specified channel (as opposed to the current one) and stores it as
1195 a variable in the current channel (the channel that is calling this
1196 application). Variables created by this application have the same inheritance
1197 properties as those created with the Set application. See the documentation for
1198 Set for more information.
1199
1200 \end{verbatim}
1201
1202
1203 \section{JabberSend}
1204 \subsection{Synopsis}
1205 \begin{verbatim}
1206 JabberSend(jabber,screenname,message)
1207 \end{verbatim}
1208 \subsection{Description}
1209 \begin{verbatim}
1210 JabberSend(Jabber,ScreenName,Message)
1211   Jabber - Client or transport Asterisk uses to connect to Jabber
1212   ScreenName - User Name to message.
1213   Message - Message to be sent to the buddy
1214
1215 \end{verbatim}
1216
1217
1218 \section{JabberStatus}
1219 \subsection{Synopsis}
1220 \begin{verbatim}
1221 JabberStatus(Jabber,ScreenName,Variable)
1222 \end{verbatim}
1223 \subsection{Description}
1224 \begin{verbatim}
1225 JabberStatus(Jabber,ScreenName,Variable)
1226   Jabber - Client or transport Asterisk uses to connect to Jabber
1227   ScreenName - User Name to retrieve status from.
1228   Variable - Variable to store presence in will be 1-6.
1229              In order, Online, Chatty, Away, XAway, DND, Offline
1230              If not in roster variable will = 7
1231
1232 \end{verbatim}
1233
1234
1235 \section{Log}
1236 \subsection{Synopsis}
1237 \begin{verbatim}
1238 Send arbitrary text to a selected log level
1239 \end{verbatim}
1240 \subsection{Description}
1241 \begin{verbatim}
1242 Log(<level>|<message>)
1243   level must be one of ERROR, WARNING, NOTICE, DEBUG, VERBOSE, DTMF
1244
1245 \end{verbatim}
1246
1247
1248 \section{Macro}
1249 \subsection{Synopsis}
1250 \begin{verbatim}
1251 Macro Implementation
1252 \end{verbatim}
1253 \subsection{Description}
1254 \begin{verbatim}
1255   Macro(macroname|arg1|arg2...): Executes a macro using the context
1256 'macro-<macroname>', jumping to the 's' extension of that context and
1257 executing each step, then returning when the steps end. 
1258 The calling extension, context, and priority are stored in ${MACRO_EXTEN}, 
1259 ${MACRO_CONTEXT} and ${MACRO_PRIORITY} respectively.  Arguments become
1260 ${ARG1}, ${ARG2}, etc in the macro context.
1261 If you Goto out of the Macro context, the Macro will terminate and control
1262 will be returned at the location of the Goto.
1263 If ${MACRO_OFFSET} is set at termination, Macro will attempt to continue
1264 at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise.
1265 Extensions: While a macro is being executed, it becomes the current context.
1266             This means that if a hangup occurs, for instance, that the macro
1267             will be searched for an 'h' extension, NOT the context from which
1268             the macro was called. So, make sure to define all appropriate
1269             extensions in your macro! (Note: AEL does not use macros)
1270 WARNING: Because of the way Macro is implemented (it executes the priorities
1271          contained within it via sub-engine), and a fixed per-thread
1272          memory stack allowance, macros are limited to 7 levels
1273          of nesting (macro calling macro calling macro, etc.); It
1274          may be possible that stack-intensive applications in deeply nested macros
1275          could cause asterisk to crash earlier than this limit. It is advised that
1276          if you need to deeply nest macro calls, that you use the Gosub application
1277          (now allows arguments like a Macro) with explict Return() calls instead.
1278
1279 \end{verbatim}
1280
1281
1282 \section{MacroExclusive}
1283 \subsection{Synopsis}
1284 \begin{verbatim}
1285 Exclusive Macro Implementation
1286 \end{verbatim}
1287 \subsection{Description}
1288 \begin{verbatim}
1289   MacroExclusive(macroname|arg1|arg2...):
1290 Executes macro defined in the context 'macro-macroname'
1291 Only one call at a time may run the macro.
1292 (we'll wait if another call is busy executing in the Macro)
1293 Arguments and return values as in application Macro()
1294
1295 \end{verbatim}
1296
1297
1298 \section{MacroExit}
1299 \subsection{Synopsis}
1300 \begin{verbatim}
1301 Exit From Macro
1302 \end{verbatim}
1303 \subsection{Description}
1304 \begin{verbatim}
1305   MacroExit():
1306 Causes the currently running macro to exit as if it had
1307 ended normally by running out of priorities to execute.
1308 If used outside a macro, will likely cause unexpected
1309 behavior.
1310
1311 \end{verbatim}
1312
1313
1314 \section{MacroIf}
1315 \subsection{Synopsis}
1316 \begin{verbatim}
1317 Conditional Macro Implementation
1318 \end{verbatim}
1319 \subsection{Description}
1320 \begin{verbatim}
1321   MacroIf(<expr>?macroname_a[|arg1][:macroname_b[|arg1]])
1322 Executes macro defined in <macroname_a> if <expr> is true
1323 (otherwise <macroname_b> if provided)
1324 Arguments and return values as in application macro()
1325
1326 \end{verbatim}
1327
1328
1329 \section{MailboxExists}
1330 \subsection{Synopsis}
1331 \begin{verbatim}
1332 Check to see if Voicemail mailbox exists
1333 \end{verbatim}
1334 \subsection{Description}
1335 \begin{verbatim}
1336   MailboxExists(mailbox[@context][|options]): Check to see if the specified
1337 mailbox exists. If no voicemail context is specified, the 'default' context
1338 will be used.
1339   This application will set the following channel variable upon completion:
1340     VMBOXEXISTSSTATUS - This will contain the status of the execution of the
1341                         MailboxExists application. Possible values include:
1342                         SUCCESS | FAILED
1343
1344   Options: (none)
1345
1346 \end{verbatim}
1347
1348
1349 \section{MeetMe}
1350 \subsection{Synopsis}
1351 \begin{verbatim}
1352 MeetMe conference bridge
1353 \end{verbatim}
1354 \subsection{Description}
1355 \begin{verbatim}
1356   MeetMe([confno][,[options][,pin]]): Enters the user into a specified MeetMe
1357 conference.  If the conference number is omitted, the user will be prompted
1358 to enter one.  User can exit the conference by hangup, or if the 'p' option
1359 is specified, by pressing '#'.
1360 Please note: The Zaptel kernel modules and at least one hardware driver (or ztdummy)
1361              must be present for conferencing to operate properly. In addition, the chan_zap
1362              channel driver must be loaded for the 'i' and 'r' options to operate at all.
1363
1364 The option string may contain zero or more of the following characters:
1365       'a' -- set admin mode
1366       'A' -- set marked mode
1367       'b' -- run AGI script specified in ${MEETME_AGI_BACKGROUND}
1368              Default: conf-background.agi  (Note: This does not work with
1369              non-Zap channels in the same conference)
1370       'c' -- announce user(s) count on joining a conference
1371       'C' -- continue in dialplan when kicked out of conference
1372       'd' -- dynamically add conference
1373       'D' -- dynamically add conference, prompting for a PIN
1374       'e' -- select an empty conference
1375       'E' -- select an empty pinless conference
1376       'F' -- Pass DTMF through the conference.  DTMF used to activate any
1377              conference features will not be passed through.
1378       'i' -- announce user join/leave with review
1379       'I' -- announce user join/leave without review
1380       'l' -- set listen only mode (Listen only, no talking)
1381       'm' -- set initially muted
1382       'M' -- enable music on hold when the conference has a single caller
1383       'o' -- set talker optimization - treats talkers who aren't speaking as
1384              being muted, meaning (a) No encode is done on transmission and
1385              (b) Received audio that is not registered as talking is omitted
1386              causing no buildup in background noise
1387       'p' -- allow user to exit the conference by pressing '#'
1388       'P' -- always prompt for the pin even if it is specified
1389       'q' -- quiet mode (don't play enter/leave sounds)
1390       'r' -- Record conference (records as ${MEETME_RECORDINGFILE}
1391              using format ${MEETME_RECORDINGFORMAT}). Default filename is
1392              meetme-conf-rec-${CONFNO}-${UNIQUEID} and the default format is
1393              wav.
1394       's' -- Present menu (user or admin) when '*' is received ('send' to menu)
1395       't' -- set talk only mode. (Talk only, no listening)
1396       'T' -- set talker detection (sent to manager interface and meetme list)
1397       'w[(<secs>)]'
1398           -- wait until the marked user enters the conference
1399       'x' -- close the conference when last marked user exits
1400       'X' -- allow user to exit the conference by entering a valid single
1401              digit extension ${MEETME_EXIT_CONTEXT} or the current context
1402              if that variable is not defined.
1403       '1' -- do not play message when first person enters
1404
1405 \end{verbatim}
1406
1407
1408 \section{MeetMeAdmin}
1409 \subsection{Synopsis}
1410 \begin{verbatim}
1411 MeetMe conference Administration
1412 \end{verbatim}
1413 \subsection{Description}
1414 \begin{verbatim}
1415   MeetMeAdmin(confno,command[,user]): Run admin command for conference
1416       'e' -- Eject last user that joined
1417       'k' -- Kick one user out of conference
1418       'K' -- Kick all users out of conference
1419       'l' -- Unlock conference
1420       'L' -- Lock conference
1421       'm' -- Unmute one user
1422       'M' -- Mute one user
1423       'n' -- Unmute all users in the conference
1424       'N' -- Mute all non-admin users in the conference
1425       'r' -- Reset one user's volume settings
1426       'R' -- Reset all users volume settings
1427       's' -- Lower entire conference speaking volume
1428       'S' -- Raise entire conference speaking volume
1429       't' -- Lower one user's talk volume
1430       'T' -- Raise one user's talk volume
1431       'u' -- Lower one user's listen volume
1432       'U' -- Raise one user's listen volume
1433       'v' -- Lower entire conference listening volume
1434       'V' -- Raise entire conference listening volume
1435
1436 \end{verbatim}
1437
1438
1439 \section{MeetMeChannelAdmin}
1440 \subsection{Synopsis}
1441 \begin{verbatim}
1442 MeetMe conference Administration (channel specific)
1443 \end{verbatim}
1444 \subsection{Description}
1445 \begin{verbatim}
1446   MeetMeChannelAdmin(channel|command): Run admin command for a specific
1447 channel in any coference.
1448       'k' -- Kick the specified user out of the conference he is in
1449       'm' -- Unmute the specified user
1450       'M' -- Mute the specified user
1451
1452 \end{verbatim}
1453
1454
1455 \section{MeetMeCount}
1456 \subsection{Synopsis}
1457 \begin{verbatim}
1458 MeetMe participant count
1459 \end{verbatim}
1460 \subsection{Description}
1461 \begin{verbatim}
1462   MeetMeCount(confno[|var]): Plays back the number of users in the specified
1463 MeetMe conference. If var is specified, playback will be skipped and the value
1464 will be returned in the variable. Upon app completion, MeetMeCount will hangup
1465 the channel, unless priority n+1 exists, in which case priority progress will
1466 continue.
1467 A ZAPTEL INTERFACE MUST BE INSTALLED FOR CONFERENCING FUNCTIONALITY.
1468
1469 \end{verbatim}
1470
1471
1472 \section{Milliwatt}
1473 \subsection{Synopsis}
1474 \begin{verbatim}
1475 Generate a Constant 1000Hz tone at 0dbm (mu-law)
1476 \end{verbatim}
1477 \subsection{Description}
1478 \begin{verbatim}
1479 Milliwatt(): Generate a Constant 1000Hz tone at 0dbm (mu-law)
1480
1481 \end{verbatim}
1482
1483
1484 \section{MinivmAccMess}
1485 \subsection{Synopsis}
1486 \begin{verbatim}
1487 Record account specific messages
1488 \end{verbatim}
1489 \subsection{Description}
1490 \begin{verbatim}
1491 Syntax: MinivmAccmess(username@domain,option)
1492 This application is part of the Mini-Voicemail system, configured in minivm.conf.
1493 Use this application to record account specific audio/video messages for
1494 busy, unavailable and temporary messages.
1495 Account specific directories will be created if they do not exist.
1496
1497 The option selects message to be recorded:
1498    u      Unavailable
1499    b      Busy
1500    t      Temporary (overrides busy and unavailable)
1501    n      Account name
1502
1503 Result is given in channel variable MINIVM_ACCMESS_STATUS
1504         The possible values are:     SUCCESS |  FAILED
1505          FAILED is set if the file can't be created.
1506
1507
1508 \end{verbatim}
1509
1510
1511 \section{MinivmDelete}
1512 \subsection{Synopsis}
1513 \begin{verbatim}
1514 Delete Mini-Voicemail voicemail messages
1515 \end{verbatim}
1516 \subsection{Description}
1517 \begin{verbatim}
1518 Syntax: MinivmDelete(filename)
1519 This application is part of the Mini-Voicemail system, configured in minivm.conf.
1520 It deletes voicemail file set in MVM_FILENAME or given filename.
1521
1522 Result is given in channel variable MINIVM_DELETE_STATUS
1523         The possible values are:     SUCCESS |  FAILED
1524          FAILED is set if the file does not exist or can't be deleted.
1525
1526
1527 \end{verbatim}
1528
1529
1530 \section{MinivmGreet}
1531 \subsection{Synopsis}
1532 \begin{verbatim}
1533 Play Mini-Voicemail prompts
1534 \end{verbatim}
1535 \subsection{Description}
1536 \begin{verbatim}
1537 Syntax: MinivmGreet(username@domain[,options])
1538 This application is part of the Mini-Voicemail system, configured in minivm.conf.
1539 MinivmGreet() plays default prompts or user specific prompts for an account.
1540 Busy and unavailable messages can be choosen, but will be overridden if a temporary
1541 message exists for the account.
1542
1543 Result is given in channel variable MINIVM_GREET_STATUS
1544         The possible values are:     SUCCESS | USEREXIT | FAILED
1545
1546   Options:
1547     b    - Play the 'busy' greeting to the calling party.
1548     s    - Skip the playback of instructions for leaving a message to the
1549            calling party.
1550     u    - Play the 'unavailable greeting.
1551
1552
1553 \end{verbatim}
1554
1555
1556 \section{MinivmNotify}
1557 \subsection{Synopsis}
1558 \begin{verbatim}
1559 Notify voicemail owner about new messages.
1560 \end{verbatim}
1561 \subsection{Description}
1562 \begin{verbatim}
1563 Syntax: MinivmNotify(username@domain[,template])
1564 This application is part of the Mini-Voicemail system, configured in minivm.conf.
1565 MiniVMnotify forwards messages about new voicemail to e-mail and pager.
1566 If there's no user account for that address, a temporary account will
1567 be used with default options (set in minivm.conf).
1568 The recorded file name and path will be read from MVM_FILENAME and the 
1569 duration of the message will be accessed from MVM_DURATION (set by MinivmRecord() )
1570 If the channel variable MVM_COUNTER is set, this will be used in the
1571 message file name and available in the template for the message.
1572 If not template is given, the default email template will be used to send email and
1573 default pager template to send paging message (if the user account is configured with
1574 a paging address.
1575
1576 Result is given in channel variable MINIVM_NOTIFY_STATUS
1577         The possible values are:     SUCCESS | FAILED
1578
1579
1580 \end{verbatim}
1581
1582
1583 \section{MinivmRecord}
1584 \subsection{Synopsis}
1585 \begin{verbatim}
1586 Receive Mini-Voicemail and forward via e-mail
1587 \end{verbatim}
1588 \subsection{Description}
1589 \begin{verbatim}
1590 Syntax: MinivmRecord(username@domain[,options])
1591 This application is part of the Mini-Voicemail system, configured in minivm.conf.
1592 MiniVM records audio file in configured format and forwards message to e-mail and pager.
1593 If there's no user account for that address, a temporary account will
1594 be used with default options.
1595 The recorded file name and path will be stored in MINIVM_FILENAME and the 
1596 duration of the message will be stored in MINIVM_DURATION
1597
1598 Note: If the caller hangs up after the recording, the only way to send
1599 the message and clean up is to execute in the "h" extension.
1600
1601 The application will exit if any of the following DTMF digits are 
1602 received and the requested extension exist in the current context.
1603     0 - Jump to the 'o' extension in the current dialplan context.
1604     * - Jump to the 'a' extension in the current dialplan context.
1605
1606 Result is given in channel variable MINIVM_RECORD_STATUS
1607         The possible values are:     SUCCESS | USEREXIT | FAILED
1608
1609   Options:
1610     g(#) - Use the specified amount of gain when recording the voicemail
1611            message. The units are whole-number decibels (dB).
1612
1613
1614 \end{verbatim}
1615
1616
1617 \section{MixMonitor}
1618 \subsection{Synopsis}
1619 \begin{verbatim}
1620 Record a call and mix the audio during the recording
1621 \end{verbatim}
1622 \subsection{Description}
1623 \begin{verbatim}
1624   MixMonitor(<file>.<ext>[|<options>[|<command>]])
1625
1626 Records the audio on the current channel to the specified file.
1627 If the filename is an absolute path, uses that path, otherwise
1628 creates the file in the configured monitoring directory from
1629 asterisk.conf.
1630
1631 Valid options:
1632  a      - Append to the file instead of overwriting it.
1633  b      - Only save audio to the file while the channel is bridged.
1634           Note: Does not include conferences or sounds played to each bridged
1635                 party.
1636  v(<x>) - Adjust the heard volume by a factor of <x> (range -4 to 4)
1637  V(<x>) - Adjust the spoken volume by a factor of <x> (range -4 to 4)
1638  W(<x>) - Adjust the both heard and spoken volumes by a factor of <x>
1639          (range -4 to 4)
1640
1641 <command> will be executed when the recording is over
1642 Any strings matching ^{X} will be unescaped to ${X} and 
1643 all variables will be evaluated at that time.
1644 The variable MIXMONITOR_FILENAME will contain the filename used to record.
1645
1646 \end{verbatim}
1647
1648
1649 \section{Monitor}
1650 \subsection{Synopsis}
1651 \begin{verbatim}
1652 Monitor a channel
1653 \end{verbatim}
1654 \subsection{Description}
1655 \begin{verbatim}
1656 Monitor([file_format[:urlbase]|[fname_base]|[options]]):
1657 Used to start monitoring a channel. The channel's input and output
1658 voice packets are logged to files until the channel hangs up or
1659 monitoring is stopped by the StopMonitor application.
1660   file_format           optional, if not set, defaults to "wav"
1661   fname_base            if set, changes the filename used to the one specified.
1662   options:
1663     m   - when the recording ends mix the two leg files into one and
1664           delete the two leg files.  If the variable MONITOR_EXEC is set, the
1665           application referenced in it will be executed instead of
1666           soxmix and the raw leg files will NOT be deleted automatically.
1667           soxmix or MONITOR_EXEC is handed 3 arguments, the two leg files
1668           and a target mixed file name which is the same as the leg file names
1669           only without the in/out designator.
1670           If MONITOR_EXEC_ARGS is set, the contents will be passed on as
1671           additional arguements to MONITOR_EXEC
1672           Both MONITOR_EXEC and the Mix flag can be set from the
1673           administrator interface
1674
1675     b   - Don't begin recording unless a call is bridged to another channel
1676
1677 Returns -1 if monitor files can't be opened or if the channel is already
1678 monitored, otherwise 0.
1679
1680 \end{verbatim}
1681
1682
1683 \section{Morsecode}
1684 \subsection{Synopsis}
1685 \begin{verbatim}
1686 Plays morse code
1687 \end{verbatim}
1688 \subsection{Description}
1689 \begin{verbatim}
1690 Usage: Morsecode(<string>)
1691 Plays the Morse code equivalent of the passed string.  If the variable
1692 MORSEDITLEN is set, it will use that value for the length (in ms) of the dit
1693 (defaults to 80).  Additionally, if MORSETONE is set, it will use that tone
1694 (in Hz).  The tone default is 800.
1695
1696 \end{verbatim}
1697
1698
1699 \section{MP3Player}
1700 \subsection{Synopsis}
1701 \begin{verbatim}
1702 Play an MP3 file or stream
1703 \end{verbatim}
1704 \subsection{Description}
1705 \begin{verbatim}
1706   MP3Player(location) Executes mpg123 to play the given location,
1707 which typically would be a filename or a URL. User can exit by pressing
1708 any key on the dialpad, or by hanging up.
1709 \end{verbatim}
1710
1711
1712 \section{MusicOnHold}
1713 \subsection{Synopsis}
1714 \begin{verbatim}
1715 Play Music On Hold indefinitely
1716 \end{verbatim}
1717 \subsection{Description}
1718 \begin{verbatim}
1719 MusicOnHold(class): Plays hold music specified by class.  If omitted, the default
1720 music source for the channel will be used. Set the default 
1721 class with the SetMusicOnHold() application.
1722 Returns -1 on hangup.
1723 Never returns otherwise.
1724
1725 \end{verbatim}
1726
1727
1728 \section{NBScat}
1729 \subsection{Synopsis}
1730 \begin{verbatim}
1731 Play an NBS local stream
1732 \end{verbatim}
1733 \subsection{Description}
1734 \begin{verbatim}
1735   NBScat: Executes nbscat to listen to the local NBS stream.
1736 User can exit by pressing any key
1737 .
1738 \end{verbatim}
1739
1740
1741 \section{NoCDR}
1742 \subsection{Synopsis}
1743 \begin{verbatim}
1744 Tell Asterisk to not maintain a CDR for the current call
1745 \end{verbatim}
1746 \subsection{Description}
1747 \begin{verbatim}
1748   NoCDR(): This application will tell Asterisk not to maintain a CDR for the
1749 current call.
1750
1751 \end{verbatim}
1752
1753
1754 \section{NoOp}
1755 \subsection{Synopsis}
1756 \begin{verbatim}
1757 Do Nothing
1758 \end{verbatim}
1759 \subsection{Description}
1760 \begin{verbatim}
1761   NoOp(): This applicatiion does nothing. However, it is useful for debugging
1762 purposes. Any text that is provided as arguments to this application can be
1763 viewed at the Asterisk CLI. This method can be used to see the evaluations of
1764 variables or functions without having any effect.
1765 \end{verbatim}
1766
1767
1768 \section{ODBCFinish}
1769 \subsection{Synopsis}
1770 \begin{verbatim}
1771 Clear the resultset of a successful multirow query
1772 \end{verbatim}
1773 \subsection{Description}
1774 \begin{verbatim}
1775 ODBCFinish(<result-id>)
1776   Clears any remaining rows of the specified resultset
1777
1778 \end{verbatim}
1779
1780
1781 \section{Page}
1782 \subsection{Synopsis}
1783 \begin{verbatim}
1784 Pages phones
1785 \end{verbatim}
1786 \subsection{Description}
1787 \begin{verbatim}
1788 Page(Technology/Resource&Technology2/Resource2[|options])
1789   Places outbound calls to the given technology / resource and dumps
1790 them into a conference bridge as muted participants.  The original
1791 caller is dumped into the conference as a speaker and the room is
1792 destroyed when the original caller leaves.  Valid options are:
1793         d - full duplex audio
1794         q - quiet, do not play beep to caller
1795         r - record the page into a file (see 'r' for app_meetme)
1796         s - only dial channel if devicestate says it is not in use
1797
1798 \end{verbatim}
1799
1800
1801 \section{Park}
1802 \subsection{Synopsis}
1803 \begin{verbatim}
1804 Park yourself
1805 \end{verbatim}
1806 \subsection{Description}
1807 \begin{verbatim}
1808 Park():Used to park yourself (typically in combination with a supervised
1809 transfer to know the parking space). This application is always
1810 registered internally and does not need to be explicitly added
1811 into the dialplan, although you should include the 'parkedcalls'
1812 context (or the context specified in features.conf).
1813
1814 If you set the PARKINGEXTEN variable to an extension in your
1815 parking context, park() will park the call on that extension, unless
1816 it already exists. In that case, execution will continue at next
1817 priority.
1818
1819 \end{verbatim}
1820
1821
1822 \section{ParkAndAnnounce}
1823 \subsection{Synopsis}
1824 \begin{verbatim}
1825 Park and Announce
1826 \end{verbatim}
1827 \subsection{Description}
1828 \begin{verbatim}
1829   ParkAndAnnounce(announce:template|timeout|dial|[return_context]):
1830 Park a call into the parkinglot and announce the call to another channel.
1831
1832 announce template: Colon-separated list of files to announce.  The word PARKED
1833                    will be replaced by a say_digits of the extension in which
1834                    the call is parked.
1835 timeout:           Time in seconds before the call returns into the return
1836                    context.
1837 dial:              The app_dial style resource to call to make the
1838                    announcement.  Console/dsp calls the console.
1839 return_context:    The goto-style label to jump the call back into after
1840                    timeout.  Default <priority+1>.
1841
1842 The variable ${PARKEDAT} will contain the parking extension into which the
1843 call was placed.  Use with the Local channel to allow the dialplan to make
1844 use of this information.
1845
1846 \end{verbatim}
1847
1848
1849 \section{ParkedCall}
1850 \subsection{Synopsis}
1851 \begin{verbatim}
1852 Answer a parked call
1853 \end{verbatim}
1854 \subsection{Description}
1855 \begin{verbatim}
1856 ParkedCall(exten):Used to connect to a parked call.  This application is always
1857 registered internally and does not need to be explicitly added
1858 into the dialplan, although you should include the 'parkedcalls'
1859 context.
1860
1861 \end{verbatim}
1862
1863
1864 \section{PauseMonitor}
1865 \subsection{Synopsis}
1866 \begin{verbatim}
1867 Pause monitoring of a channel
1868 \end{verbatim}
1869 \subsection{Description}
1870 \begin{verbatim}
1871 PauseMonitor
1872 Pauses monitoring of a channel until it is re-enabled by a call to UnpauseMonitor.
1873
1874 \end{verbatim}
1875
1876
1877 \section{PauseQueueMember}
1878 \subsection{Synopsis}
1879 \begin{verbatim}
1880 Pauses a queue member
1881 \end{verbatim}
1882 \subsection{Description}
1883 \begin{verbatim}
1884    PauseQueueMember([queuename]|interface[|options]):
1885 Pauses (blocks calls for) a queue member.
1886 The given interface will be paused in the given queue.  This prevents
1887 any calls from being sent from the queue to the interface until it is
1888 unpaused with UnpauseQueueMember or the manager interface.  If no
1889 queuename is given, the interface is paused in every queue it is a
1890 member of. The application will fail if the interface is not found.
1891   This application sets the following channel variable upon completion:
1892      PQMSTATUS      The status of the attempt to pause a queue member as a
1893                      text string, one of
1894            PAUSED | NOTFOUND
1895 Example: PauseQueueMember(|SIP/3000)
1896
1897 \end{verbatim}
1898
1899
1900 \section{Pickup}
1901 \subsection{Synopsis}
1902 \begin{verbatim}
1903 Directed Call Pickup
1904 \end{verbatim}
1905 \subsection{Description}
1906 \begin{verbatim}
1907   Pickup(extension[@context][&extension2@context...]): This application can pickup any ringing channel
1908 that is calling the specified extension. If no context is specified, the current
1909 context will be used. If you use the special string "PICKUPMARK" for the context parameter, for example
1910 10@PICKUPMARK, this application tries to find a channel which has defined a channel variable with the same content
1911 as "extension".
1912 \end{verbatim}
1913
1914
1915 \section{Playback}
1916 \subsection{Synopsis}
1917 \begin{verbatim}
1918 Play a file
1919 \end{verbatim}
1920 \subsection{Description}
1921 \begin{verbatim}
1922   Playback(filename[&filename2...][|option]):  Plays back given filenames (do not put
1923 extension). Options may also be included following a pipe symbol. The 'skip'
1924 option causes the playback of the message to be skipped if the channel
1925 is not in the 'up' state (i.e. it hasn't been  answered  yet). If 'skip' is 
1926 specified, the application will return immediately should the channel not be
1927 off hook.  Otherwise, unless 'noanswer' is specified, the channel will
1928 be answered before the sound is played. Not all channels support playing
1929 messages while still on hook.
1930 This application sets the following channel variable upon completion:
1931  PLAYBACKSTATUS    The status of the playback attempt as a text string, one of
1932                SUCCESS | FAILED
1933
1934 \end{verbatim}
1935
1936
1937 \section{PlayTones}
1938 \subsection{Synopsis}
1939 \begin{verbatim}
1940 Play a tone list
1941 \end{verbatim}
1942 \subsection{Description}
1943 \begin{verbatim}
1944 PlayTones(arg): Plays a tone list. Execution will continue with the next step immediately,
1945 while the tones continue to play.
1946 Arg is either the tone name defined in the indications.conf configuration file, or a directly
1947 specified list of frequencies and durations.
1948 See the sample indications.conf for a description of the specification of a tonelist.
1949
1950 Use the StopPlayTones application to stop the tones playing. 
1951
1952 \end{verbatim}
1953
1954
1955 \section{PrivacyManager}
1956 \subsection{Synopsis}
1957 \begin{verbatim}
1958 Require phone number to be entered, if no CallerID sent
1959 \end{verbatim}
1960 \subsection{Description}
1961 \begin{verbatim}
1962   PrivacyManager([maxretries[|minlength[|options]]]): If no Caller*ID 
1963 is sent, PrivacyManager answers the channel and asks the caller to
1964 enter their phone number. The caller is given 3 attempts to do so.
1965 The application does nothing if Caller*ID was received on the channel.
1966   Configuration file privacy.conf contains two variables:
1967    maxretries  default 3  -maximum number of attempts the caller is allowed 
1968                to input a callerid.
1969    minlength   default 10 -minimum allowable digits in the input callerid number.
1970 If you don't want to use the config file and have an i/o operation with
1971 every call, you can also specify maxretries and minlength as application
1972 parameters. Doing so supercedes any values set in privacy.conf.
1973 The application sets the following channel variable upon completion: 
1974 PRIVACYMGRSTATUS  The status of the privacy manager's attempt to collect 
1975                   a phone number from the user. A text string that is either:
1976           SUCCESS | FAILED 
1977
1978 \end{verbatim}
1979
1980
1981 \section{Progress}
1982 \subsection{Synopsis}
1983 \begin{verbatim}
1984 Indicate progress
1985 \end{verbatim}
1986 \subsection{Description}
1987 \begin{verbatim}
1988   Progress(): This application will request that in-band progress information
1989 be provided to the calling channel.
1990
1991 \end{verbatim}
1992
1993
1994 \section{Queue}
1995 \subsection{Synopsis}
1996 \begin{verbatim}
1997 Queue a call for a call queue
1998 \end{verbatim}
1999 \subsection{Description}
2000 \begin{verbatim}
2001   Queue(queuename[|options[|URL][|announceoverride][|timeout][|AGI][|macro]):
2002 Queues an incoming call in a particular call queue as defined in queues.conf.
2003 This application will return to the dialplan if the queue does not exist, or
2004 any of the join options cause the caller to not enter the queue.
2005 The option string may contain zero or more of the following characters:
2006       'c' -- continue in the dialplan if the callee hangs up.
2007       'd' -- data-quality (modem) call (minimum delay).
2008       'h' -- allow callee to hang up by pressing *.
2009       'H' -- allow caller to hang up by pressing *.
2010       'n' -- no retries on the timeout; will exit this application and 
2011              go to the next step.
2012       'i' -- ignore call forward requests from queue members and do nothing
2013              when they are requested.
2014       'r' -- ring instead of playing MOH.
2015       't' -- allow the called user to transfer the calling user.
2016       'T' -- allow the calling user to transfer the call.
2017       'w' -- allow the called user to write the conversation to disk via Monitor.
2018       'W' -- allow the calling user to write the conversation to disk via Monitor.
2019   In addition to transferring the call, a call may be parked and then picked
2020 up by another user.
2021   The optional URL will be sent to the called party if the channel supports
2022 it.
2023   The optional AGI parameter will setup an AGI script to be executed on the 
2024 calling party's channel once they are connected to a queue member.
2025   The optional macro parameter will run a macro on the 
2026 calling party's channel once they are connected to a queue member.
2027   The timeout will cause the queue to fail out after a specified number of
2028 seconds, checked between each queues.conf 'timeout' and 'retry' cycle.
2029   This application sets the following channel variable upon completion:
2030       QUEUESTATUS    The status of the call as a text string, one of
2031              TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL | CONTINUE
2032
2033 \end{verbatim}
2034
2035
2036 \section{QueueLog}
2037 \subsection{Synopsis}
2038 \begin{verbatim}
2039 Writes to the queue_log
2040 \end{verbatim}
2041 \subsection{Description}
2042 \begin{verbatim}
2043    QueueLog(queuename|uniqueid|agent|event[|additionalinfo]):
2044 Allows you to write your own events into the queue log
2045 Example: QueueLog(101|${UNIQUEID}|${AGENT}|WENTONBREAK|600)
2046
2047 \end{verbatim}
2048
2049
2050 \section{Read}
2051 \subsection{Synopsis}
2052 \begin{verbatim}
2053 Read a variable
2054 \end{verbatim}
2055 \subsection{Description}
2056 \begin{verbatim}
2057   Read(variable[|filename[&filename2...]][|maxdigits][|option][|attempts][|timeout])
2058
2059 Reads a #-terminated string of digits a certain number of times from the
2060 user in to the given variable.
2061   filename   -- file(s) to play before reading digits or tone with option i
2062   maxdigits  -- maximum acceptable number of digits. Stops reading after
2063                 maxdigits have been entered (without requiring the user to
2064                 press the '#' key).
2065                 Defaults to 0 - no limit - wait for the user press the '#' key.
2066                 Any value below 0 means the same. Max accepted value is 255.
2067   option     -- options are 's' , 'i', 'n'
2068                 's' to return immediately if the line is not up,
2069                 'i' to play  filename as an indication tone from your indications.conf
2070                 'n' to read digits even if the line is not up.
2071   attempts   -- if greater than 1, that many attempts will be made in the 
2072                 event no data is entered.
2073   timeout    -- The number of seconds to wait for a digit response. If greater
2074                 than 0, that value will override the default timeout. Can be floating point.
2075
2076 Read should disconnect if the function fails or errors out.
2077
2078 \end{verbatim}
2079
2080
2081 \section{ReadFile}
2082 \subsection{Synopsis}
2083 \begin{verbatim}
2084 ReadFile(varname=file,length)
2085 \end{verbatim}
2086 \subsection{Description}
2087 \begin{verbatim}
2088 ReadFile(varname=file,length)
2089   Varname - Result stored here.
2090   File - The name of the file to read.
2091   Length - Maximum number of characters to capture.
2092
2093 \end{verbatim}
2094
2095
2096 \section{Record}
2097 \subsection{Synopsis}
2098 \begin{verbatim}
2099 Record to a file
2100 \end{verbatim}
2101 \subsection{Description}
2102 \begin{verbatim}
2103   Record(filename.format|silence[|maxduration][|options])
2104
2105 Records from the channel into a given filename. If the file exists it will
2106 be overwritten.
2107 - 'format' is the format of the file type to be recorded (wav, gsm, etc).
2108 - 'silence' is the number of seconds of silence to allow before returning.
2109 - 'maxduration' is the maximum recording duration in seconds. If missing
2110 or 0 there is no maximum.
2111 - 'options' may contain any of the following letters:
2112      'a' : append to existing recording rather than replacing
2113      'n' : do not answer, but record anyway if line not yet answered
2114      'q' : quiet (do not play a beep tone)
2115      's' : skip recording if the line is not yet answered
2116      't' : use alternate '*' terminator key (DTMF) instead of default '#'
2117      'x' : ignore all terminator keys (DTMF) and keep recording until hangup
2118
2119 If filename contains '%d', these characters will be replaced with a number
2120 incremented by one each time the file is recorded. A channel variable
2121 named RECORDED_FILE will also be set, which contains the final filemname.
2122
2123 Use 'core show file formats' to see the available formats on your system
2124
2125 User can press '#' to terminate the recording and continue to the next priority.
2126
2127 If the user should hangup during a recording, all data will be lost and the
2128 application will teminate. 
2129
2130 \end{verbatim}
2131
2132
2133 \section{RemoveQueueMember}
2134 \subsection{Synopsis}
2135 \begin{verbatim}
2136 Dynamically removes queue members
2137 \end{verbatim}
2138 \subsection{Description}
2139 \begin{verbatim}
2140    RemoveQueueMember(queuename[|interface[|options]]):
2141 Dynamically removes interface to an existing queue
2142 If the interface is NOT in the queue it will return an error.
2143   This application sets the following channel variable upon completion:
2144      RQMSTATUS      The status of the attempt to remove a queue member as a
2145                      text string, one of
2146            REMOVED | NOTINQUEUE | NOSUCHQUEUE 
2147 Example: RemoveQueueMember(techsupport|SIP/3000)
2148
2149 \end{verbatim}
2150
2151
2152 \section{ResetCDR}
2153 \subsection{Synopsis}
2154 \begin{verbatim}
2155 Resets the Call Data Record
2156 \end{verbatim}
2157 \subsection{Description}
2158 \begin{verbatim}
2159   ResetCDR([options]):  This application causes the Call Data Record to be
2160 reset.
2161   Options:
2162     w -- Store the current CDR record before resetting it.
2163     a -- Store any stacked records.
2164     v -- Save CDR variables.
2165
2166 \end{verbatim}
2167
2168
2169 \section{RetryDial}
2170 \subsection{Synopsis}
2171 \begin{verbatim}
2172 Place a call, retrying on failure allowing optional exit extension.
2173 \end{verbatim}
2174 \subsection{Description}
2175 \begin{verbatim}
2176   RetryDial(announce|sleep|retries|dialargs): This application will attempt to
2177 place a call using the normal Dial application. If no channel can be reached,
2178 the 'announce' file will be played. Then, it will wait 'sleep' number of
2179 seconds before retying the call. After 'retires' number of attempts, the
2180 calling channel will continue at the next priority in the dialplan. If the
2181 'retries' setting is set to 0, this application will retry endlessly.
2182   While waiting to retry a call, a 1 digit extension may be dialed. If that
2183 extension exists in either the context defined in ${EXITCONTEXT} or the current
2184 one, The call will jump to that extension immediately.
2185   The 'dialargs' are specified in the same format that arguments are provided
2186 to the Dial application.
2187
2188 \end{verbatim}
2189
2190
2191 \section{Return}
2192 \subsection{Synopsis}
2193 \begin{verbatim}
2194 Return from gosub routine
2195 \end{verbatim}
2196 \subsection{Description}
2197 \begin{verbatim}
2198 Return([return-value])
2199   Jumps to the last label on the stack, removing it.  The return value, if
2200 any, is saved in the channel variable GOSUB_RETVAL.
2201
2202 \end{verbatim}
2203
2204
2205 \section{Ringing}
2206 \subsection{Synopsis}
2207 \begin{verbatim}
2208 Indicate ringing tone
2209 \end{verbatim}
2210 \subsection{Description}
2211 \begin{verbatim}
2212   Ringing(): This application will request that the channel indicate a ringing
2213 tone to the user.
2214
2215 \end{verbatim}
2216
2217
2218 \section{SayAlpha}
2219 \subsection{Synopsis}
2220 \begin{verbatim}
2221 Say Alpha
2222 \end{verbatim}
2223 \subsection{Description}
2224 \begin{verbatim}
2225   SayAlpha(string): This application will play the sounds that correspond to
2226 the letters of the given string.
2227
2228 \end{verbatim}
2229
2230
2231 \section{SayDigits}
2232 \subsection{Synopsis}
2233 \begin{verbatim}
2234 Say Digits
2235 \end{verbatim}
2236 \subsection{Description}
2237 \begin{verbatim}
2238   SayDigits(digits): This application will play the sounds that correspond
2239 to the digits of the given number. This will use the language that is currently
2240 set for the channel. See the LANGUAGE function for more information on setting
2241 the language for the channel.
2242
2243 \end{verbatim}
2244
2245
2246 \section{SayNumber}
2247 \subsection{Synopsis}
2248 \begin{verbatim}
2249 Say Number
2250 \end{verbatim}
2251 \subsection{Description}
2252 \begin{verbatim}
2253   SayNumber(digits[,gender]): This application will play the sounds that
2254 correspond to the given number. Optionally, a gender may be specified.
2255 This will use the language that is currently set for the channel. See the
2256 LANGUAGE function for more information on setting the language for the channel.
2257
2258 \end{verbatim}
2259
2260
2261 \section{SayPhonetic}
2262 \subsection{Synopsis}
2263 \begin{verbatim}
2264 Say Phonetic
2265 \end{verbatim}
2266 \subsection{Description}
2267 \begin{verbatim}
2268   SayPhonetic(string): This application will play the sounds from the phonetic
2269 alphabet that correspond to the letters in the given string.
2270
2271 \end{verbatim}
2272
2273
2274 \section{SayUnixTime}
2275 \subsection{Synopsis}
2276 \begin{verbatim}
2277 Says a specified time in a custom format
2278 \end{verbatim}
2279 \subsection{Description}
2280 \begin{verbatim}
2281 SayUnixTime([unixtime][|[timezone][|format]])
2282   unixtime: time, in seconds since Jan 1, 1970.  May be negative.
2283               defaults to now.
2284   timezone: timezone, see /usr/share/zoneinfo for a list.
2285               defaults to machine default.
2286   format:   a format the time is to be said in.  See voicemail.conf.
2287               defaults to "ABdY 'digits/at' IMp"
2288
2289 \end{verbatim}
2290
2291
2292 \section{SendDTMF}
2293 \subsection{Synopsis}
2294 \begin{verbatim}
2295 Sends arbitrary DTMF digits
2296 \end{verbatim}
2297 \subsection{Description}
2298 \begin{verbatim}
2299  SendDTMF(digits[|timeout_ms]): Sends DTMF digits on a channel. 
2300  Accepted digits: 0-9, *#abcd, w (.5s pause)
2301  The application will either pass the assigned digits or terminate if it
2302  encounters an error.
2303
2304 \end{verbatim}
2305
2306
2307 \section{SendImage}
2308 \subsection{Synopsis}
2309 \begin{verbatim}
2310 Send an image file
2311 \end{verbatim}
2312 \subsection{Description}
2313 \begin{verbatim}
2314   SendImage(filename): Sends an image on a channel. 
2315 If the channel supports image transport but the image send
2316 fails, the channel will be hung up. Otherwise, the dialplan
2317 continues execution.
2318 This application sets the following channel variable upon completion:
2319         SENDIMAGESTATUS         The status is the result of the attempt as a text string, one of
2320                 OK | NOSUPPORT 
2321
2322 \end{verbatim}
2323
2324
2325 \section{SendText}
2326 \subsection{Synopsis}
2327 \begin{verbatim}
2328 Send a Text Message
2329 \end{verbatim}
2330 \subsection{Description}
2331 \begin{verbatim}
2332   SendText(text[|options]): Sends text to current channel (callee).
2333 Result of transmission will be stored in the SENDTEXTSTATUS
2334 channel variable:
2335       SUCCESS      Transmission succeeded
2336       FAILURE      Transmission failed
2337       UNSUPPORTED  Text transmission not supported by channel
2338
2339 At this moment, text is supposed to be 7 bit ASCII in most channels.
2340
2341 \end{verbatim}
2342
2343
2344 \section{SendURL}
2345 \subsection{Synopsis}
2346 \begin{verbatim}
2347 Send a URL
2348 \end{verbatim}
2349 \subsection{Description}
2350 \begin{verbatim}
2351   SendURL(URL[|option]): Requests client go to URL (IAX2) or sends the 
2352 URL to the client (other channels).
2353 Result is returned in the SENDURLSTATUS channel variable:
2354     SUCCESS       URL successfully sent to client
2355     FAILURE       Failed to send URL
2356     NOLOAD        Client failed to load URL (wait enabled)
2357     UNSUPPORTED   Channel does not support URL transport
2358
2359 If the option 'wait' is specified, execution will wait for an
2360 acknowledgement that the URL has been loaded before continuing
2361
2362 SendURL continues normally if the URL was sent correctly or if the channel
2363 does not support HTML transport.  Otherwise, the channel is hung up.
2364
2365 \end{verbatim}
2366
2367
2368 \section{Set}
2369 \subsection{Synopsis}
2370 \begin{verbatim}
2371 Set channel variable(s) or function value(s)
2372 \end{verbatim}
2373 \subsection{Description}
2374 \begin{verbatim}
2375   Set(name1=value1|name2=value2|..[|options])
2376 This function can be used to set the value of channel variables or dialplan
2377 functions. It will accept up to 24 name/value pairs. When setting variables,
2378 if the variable name is prefixed with _, the variable will be inherited into
2379 channels created from the current channel. If the variable name is prefixed
2380 with __, the variable will be inherited into channels created from the current
2381 channel and all children channels.
2382   Options:
2383     g - Set variable globally instead of on the channel
2384         (applies only to variables, not functions)
2385
2386 \end{verbatim}
2387
2388
2389 \section{SetAMAFlags}
2390 \subsection{Synopsis}
2391 \begin{verbatim}
2392 Set the AMA Flags
2393 \end{verbatim}
2394 \subsection{Description}
2395 \begin{verbatim}
2396   SetAMAFlags([flag]): This application will set the channel's AMA Flags for
2397   billing purposes.
2398
2399 \end{verbatim}
2400
2401
2402 \section{SetCallerPres}
2403 \subsection{Synopsis}
2404 \begin{verbatim}
2405 Set CallerID Presentation
2406 \end{verbatim}
2407 \subsection{Description}
2408 \begin{verbatim}
2409   SetCallerPres(presentation): Set Caller*ID presentation on a call.
2410   Valid presentations are:
2411
2412       allowed_not_screened    : Presentation Allowed, Not Screened
2413       allowed_passed_screen   : Presentation Allowed, Passed Screen
2414       allowed_failed_screen   : Presentation Allowed, Failed Screen
2415       allowed                 : Presentation Allowed, Network Number
2416       prohib_not_screened     : Presentation Prohibited, Not Screened
2417       prohib_passed_screen    : Presentation Prohibited, Passed Screen
2418       prohib_failed_screen    : Presentation Prohibited, Failed Screen
2419       prohib                  : Presentation Prohibited, Network Number
2420       unavailable             : Number Unavailable
2421
2422
2423 \end{verbatim}
2424
2425
2426 \section{SetMusicOnHold}
2427 \subsection{Synopsis}
2428 \begin{verbatim}
2429 Set default Music On Hold class
2430 \end{verbatim}
2431 \subsection{Description}
2432 \begin{verbatim}
2433 SetMusicOnHold(class): Sets the default class for music on hold for a given channel.  When
2434 music on hold is activated, this class will be used to select which
2435 music is played.
2436
2437 \end{verbatim}
2438
2439
2440 \section{SIPAddHeader}
2441 \subsection{Synopsis}
2442 \begin{verbatim}
2443 Add a SIP header to the outbound call
2444 \end{verbatim}
2445 \subsection{Description}
2446 \begin{verbatim}
2447   SIPAddHeader(Header: Content)
2448 Adds a header to a SIP call placed with DIAL.
2449 Remember to user the X-header if you are adding non-standard SIP
2450 headers, like "X-Asterisk-Accountcode:". Use this with care.
2451 Adding the wrong headers may jeopardize the SIP dialog.
2452 Always returns 0
2453
2454 \end{verbatim}
2455
2456
2457 \section{SIPDtmfMode}
2458 \subsection{Synopsis}
2459 \begin{verbatim}
2460 Change the dtmfmode for a SIP call
2461 \end{verbatim}
2462 \subsection{Description}
2463 \begin{verbatim}
2464 SIPDtmfMode(inband|info|rfc2833): Changes the dtmfmode for a SIP call
2465
2466 \end{verbatim}
2467
2468
2469 \section{SLAStation}
2470 \subsection{Synopsis}
2471 \begin{verbatim}
2472 Shared Line Appearance Station
2473 \end{verbatim}
2474 \subsection{Description}
2475 \begin{verbatim}
2476   SLAStation():
2477
2478 \end{verbatim}
2479
2480
2481 \section{SLATrunk}
2482 \subsection{Synopsis}
2483 \begin{verbatim}
2484 Shared Line Appearance Trunk
2485 \end{verbatim}
2486 \subsection{Description}
2487 \begin{verbatim}
2488   SLATrunk():
2489
2490 \end{verbatim}
2491
2492
2493 \section{SMS}
2494 \subsection{Synopsis}
2495 \begin{verbatim}
2496 Communicates with SMS service centres and SMS capable analogue phones
2497 \end{verbatim}
2498 \subsection{Description}
2499 \begin{verbatim}
2500   SMS(name|[a][s][t][p(d)][r][o]|addr|body):
2501 SMS handles exchange of SMS data with a call to/from SMS capable
2502 phone or SMS PSTN service center. Can send and/or receive SMS messages.
2503 Works to ETSI ES 201 912 compatible with BT SMS PSTN service in UK
2504 and Telecom Italia in Italy.
2505 Typical usage is to use to handle called from the SMS service centre CLI,
2506 or to set up a call using 'outgoing' or manager interface to connect
2507 service centre to SMS()
2508 name is the name of the queue used in /var/spool/asterisk/sms
2509 Arguments:
2510  a: answer, i.e. send initial FSK packet.
2511  s: act as service centre talking to a phone.
2512  t: use protocol 2 (default used is protocol 1).
2513  p(N): set the initial delay to N ms (default is 300).
2514 addr and body are a deprecated format to send messages out.
2515  s: set the Status Report Request (SRR) bit.
2516  o: the body should be coded as octets not 7-bit symbols.
2517 Messages are processed as per text file message queues.
2518 smsq (a separate software) is a command to generate message
2519 queues and send messages.
2520 NOTE: the protocol has tight delay bounds. Please use short frames
2521 and disable/keep short the jitter buffer on the ATA to make sure that
2522 respones (ACK etc.) are received in time.
2523
2524 \end{verbatim}
2525
2526
2527 \section{SoftHangup}
2528 \subsection{Synopsis}
2529 \begin{verbatim}
2530 Soft Hangup Application
2531 \end{verbatim}
2532 \subsection{Description}
2533 \begin{verbatim}
2534   SoftHangup(Technology/resource|options)
2535 Hangs up the requested channel.  If there are no channels to hangup,
2536 the application will report it.
2537 - 'options' may contain the following letter:
2538      'a' : hang up all channels on a specified device instead of a single resource
2539
2540 \end{verbatim}
2541
2542
2543 \section{SpeechActivateGrammar}
2544 \subsection{Synopsis}
2545 \begin{verbatim}
2546 Activate a Grammar
2547 \end{verbatim}
2548 \subsection{Description}
2549 \begin{verbatim}
2550 SpeechActivateGrammar(Grammar Name)
2551 This activates the specified grammar to be recognized by the engine. A grammar tells the speech recognition engine what to recognize, 
2552 and how to portray it back to you in the dialplan. The grammar name is the only argument to this application.
2553
2554 \end{verbatim}
2555
2556
2557 \section{SpeechBackground}
2558 \subsection{Synopsis}
2559 \begin{verbatim}
2560 Play a sound file and wait for speech to be recognized
2561 \end{verbatim}
2562 \subsection{Description}
2563 \begin{verbatim}
2564 SpeechBackground(Sound File|Timeout)
2565 This application plays a sound file and waits for the person to speak. Once they start speaking playback of the file stops, and silence is heard.
2566 Once they stop talking the processing sound is played to indicate the speech recognition engine is working.
2567 Once results are available the application returns and results (score and text) are available using dialplan functions.
2568 The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)} and ${SPEECH_SCORE(1)}.
2569 The first argument is the sound file and the second is the timeout integer in seconds. Note the timeout will only start once the sound file has stopped playing.
2570
2571 \end{verbatim}
2572
2573
2574 \section{SpeechCreate}
2575 \subsection{Synopsis}
2576 \begin{verbatim}
2577 Create a Speech Structure
2578 \end{verbatim}
2579 \subsection{Description}
2580 \begin{verbatim}
2581 SpeechCreate(engine name)
2582 This application creates information to be used by all the other applications. It must be called before doing any speech recognition activities such as activating a grammar.
2583 It takes the engine name to use as the argument, if not specified the default engine will be used.
2584
2585 \end{verbatim}
2586
2587
2588 \section{SpeechDeactivateGrammar}
2589 \subsection{Synopsis}
2590 \begin{verbatim}
2591 Deactivate a Grammar
2592 \end{verbatim}
2593 \subsection{Description}
2594 \begin{verbatim}
2595 SpeechDeactivateGrammar(Grammar Name)
2596 This deactivates the specified grammar so that it is no longer recognized. The only argument is the grammar name to deactivate.
2597
2598 \end{verbatim}
2599
2600
2601 \section{SpeechDestroy}
2602 \subsection{Synopsis}
2603 \begin{verbatim}
2604 End speech recognition
2605 \end{verbatim}
2606 \subsection{Description}
2607 \begin{verbatim}
2608 SpeechDestroy()
2609 This destroys the information used by all the other speech recognition applications.
2610 If you call this application but end up wanting to recognize more speech, you must call SpeechCreate
2611 again before calling any other application. It takes no arguments.
2612
2613 \end{verbatim}
2614
2615
2616 \section{SpeechLoadGrammar}
2617 \subsection{Synopsis}
2618 \begin{verbatim}
2619 Load a Grammar
2620 \end{verbatim}
2621 \subsection{Description}
2622 \begin{verbatim}
2623 SpeechLoadGrammar(Grammar Name|Path)
2624 Load a grammar only on the channel, not globally.
2625 It takes the grammar name as first argument and path as second.
2626
2627 \end{verbatim}
2628
2629
2630 \section{SpeechProcessingSound}
2631 \subsection{Synopsis}
2632 \begin{verbatim}
2633 Change background processing sound
2634 \end{verbatim}
2635 \subsection{Description}
2636 \begin{verbatim}
2637 SpeechProcessingSound(Sound File)
2638 This changes the processing sound that SpeechBackground plays back when the speech recognition engine is processing and working to get results.
2639 It takes the sound file as the only argument.
2640
2641 \end{verbatim}
2642
2643
2644 \section{SpeechStart}
2645 \subsection{Synopsis}
2646 \begin{verbatim}
2647 Start recognizing voice in the audio stream
2648 \end{verbatim}
2649 \subsection{Description}
2650 \begin{verbatim}
2651 SpeechStart()
2652 Tell the speech recognition engine that it should start trying to get results from audio being fed to it. This has no arguments.
2653
2654 \end{verbatim}
2655
2656
2657 \section{SpeechUnloadGrammar}
2658 \subsection{Synopsis}
2659 \begin{verbatim}
2660 Unload a Grammar
2661 \end{verbatim}
2662 \subsection{Description}
2663 \begin{verbatim}
2664 SpeechUnloadGrammar(Grammar Name)
2665 Unload a grammar. It takes the grammar name as the only argument.
2666
2667 \end{verbatim}
2668
2669
2670 \section{StackPop}
2671 \subsection{Synopsis}
2672 \begin{verbatim}
2673 Remove one address from gosub stack
2674 \end{verbatim}
2675 \subsection{Description}
2676 \begin{verbatim}
2677 StackPop()
2678   Removes last label on the stack, discarding it.
2679
2680 \end{verbatim}
2681
2682
2683 \section{StartMusicOnHold}
2684 \subsection{Synopsis}
2685 \begin{verbatim}
2686 Play Music On Hold
2687 \end{verbatim}
2688 \subsection{Description}
2689 \begin{verbatim}
2690 StartMusicOnHold(class): Starts playing music on hold, uses default music class for channel.
2691 Starts playing music specified by class.  If omitted, the default
2692 music source for the channel will be used.  Always returns 0.
2693
2694 \end{verbatim}
2695
2696
2697 \section{StopMixMonitor}
2698 \subsection{Synopsis}
2699 \begin{verbatim}
2700 Stop recording a call through MixMonitor
2701 \end{verbatim}
2702 \subsection{Description}
2703 \begin{verbatim}
2704   StopMixMonitor()
2705
2706 Stops the audio recording that was started with a call to MixMonitor()
2707 on the current channel.
2708
2709 \end{verbatim}
2710
2711
2712 \section{StopMonitor}
2713 \subsection{Synopsis}
2714 \begin{verbatim}
2715 Stop monitoring a channel
2716 \end{verbatim}
2717 \subsection{Description}
2718 \begin{verbatim}
2719 StopMonitor
2720 Stops monitoring a channel. Has no effect if the channel is not monitored
2721
2722 \end{verbatim}
2723
2724
2725 \section{StopMusicOnHold}
2726 \subsection{Synopsis}
2727 \begin{verbatim}
2728 Stop Playing Music On Hold
2729 \end{verbatim}
2730 \subsection{Description}
2731 \begin{verbatim}
2732 StopMusicOnHold: Stops playing music on hold.
2733
2734 \end{verbatim}
2735
2736
2737 \section{StopPlayTones}
2738 \subsection{Synopsis}
2739 \begin{verbatim}
2740 Stop playing a tone list
2741 \end{verbatim}
2742 \subsection{Description}
2743 \begin{verbatim}
2744 Stop playing a tone list
2745 \end{verbatim}
2746
2747
2748 \section{System}
2749 \subsection{Synopsis}
2750 \begin{verbatim}
2751 Execute a system command
2752 \end{verbatim}
2753 \subsection{Description}
2754 \begin{verbatim}
2755   System(command): Executes a command  by  using  system(). If the command
2756 fails, the console should report a fallthrough. 
2757 Result of execution is returned in the SYSTEMSTATUS channel variable:
2758    FAILURE      Could not execute the specified command
2759    SUCCESS      Specified command successfully executed
2760
2761 \end{verbatim}
2762
2763
2764 \section{TestClient}
2765 \subsection{Synopsis}
2766 \begin{verbatim}
2767 Execute Interface Test Client
2768 \end{verbatim}
2769 \subsection{Description}
2770 \begin{verbatim}
2771 TestClient(testid): Executes test client with given testid.
2772 Results stored in /var/log/asterisk/testreports/<testid>-client.txt
2773 \end{verbatim}
2774
2775
2776 \section{TestServer}
2777 \subsection{Synopsis}
2778 \begin{verbatim}
2779 Execute Interface Test Server
2780 \end{verbatim}
2781 \subsection{Description}
2782 \begin{verbatim}
2783 TestServer(): Perform test server function and write call report.
2784 Results stored in /var/log/asterisk/testreports/<testid>-server.txt
2785 \end{verbatim}
2786
2787
2788 \section{Transfer}
2789 \subsection{Synopsis}
2790 \begin{verbatim}
2791 Transfer caller to remote extension
2792 \end{verbatim}
2793 \subsection{Description}
2794 \begin{verbatim}
2795   Transfer([Tech/]dest[|options]):  Requests the remote caller be transferred
2796 to a given destination. If TECH (SIP, IAX2, LOCAL etc) is used, only
2797 an incoming call with the same channel technology will be transfered.
2798 Note that for SIP, if you transfer before call is setup, a 302 redirect
2799 SIP message will be returned to the caller.
2800
2801 The result of the application will be reported in the TRANSFERSTATUS
2802 channel variable:
2803        SUCCESS      Transfer succeeded
2804        FAILURE      Transfer failed
2805        UNSUPPORTED  Transfer unsupported by channel driver
2806
2807 \end{verbatim}
2808
2809
2810 \section{TryExec}
2811 \subsection{Synopsis}
2812 \begin{verbatim}
2813 Executes dialplan application, always returning
2814 \end{verbatim}
2815 \subsection{Description}
2816 \begin{verbatim}
2817 Usage: TryExec(appname(arguments))
2818   Allows an arbitrary application to be invoked even when not
2819 hardcoded into the dialplan. To invoke external applications
2820 see the application System.  Always returns to the dialplan.
2821 The channel variable TRYSTATUS will be set to:
2822     SUCCESS   if the application returned zero
2823     FAILED    if the application returned non-zero
2824     NOAPP     if the application was not found or was not specified
2825
2826 \end{verbatim}
2827
2828
2829 \section{TrySystem}
2830 \subsection{Synopsis}
2831 \begin{verbatim}
2832 Try executing a system command
2833 \end{verbatim}
2834 \subsection{Description}
2835 \begin{verbatim}
2836   TrySystem(command): Executes a command  by  using  system().
2837 on any situation.
2838 Result of execution is returned in the SYSTEMSTATUS channel variable:
2839    FAILURE      Could not execute the specified command
2840    SUCCESS      Specified command successfully executed
2841    APPERROR     Specified command successfully executed, but returned error code
2842
2843 \end{verbatim}
2844
2845
2846 \section{UnpauseMonitor}
2847 \subsection{Synopsis}
2848 \begin{verbatim}
2849 Unpause monitoring of a channel
2850 \end{verbatim}
2851 \subsection{Description}
2852 \begin{verbatim}
2853 UnpauseMonitor
2854 Unpauses monitoring of a channel on which monitoring had
2855 previously been paused with PauseMonitor.
2856
2857 \end{verbatim}
2858
2859
2860 \section{UnpauseQueueMember}
2861 \subsection{Synopsis}
2862 \begin{verbatim}
2863 Unpauses a queue member
2864 \end{verbatim}
2865 \subsection{Description}
2866 \begin{verbatim}
2867    UnpauseQueueMember([queuename]|interface[|options]):
2868 Unpauses (resumes calls to) a queue member.
2869 This is the counterpart to PauseQueueMember and operates exactly the
2870 same way, except it unpauses instead of pausing the given interface.
2871   This application sets the following channel variable upon completion:
2872      UPQMSTATUS       The status of the attempt to unpause a queue 
2873                       member as a text string, one of
2874             UNPAUSED | NOTFOUND
2875 Example: UnpauseQueueMember(|SIP/3000)
2876
2877 \end{verbatim}
2878
2879
2880 \section{UserEvent}
2881 \subsection{Synopsis}
2882 \begin{verbatim}
2883 Send an arbitrary event to the manager interface
2884 \end{verbatim}
2885 \subsection{Description}
2886 \begin{verbatim}
2887   UserEvent(eventname[|body]): Sends an arbitrary event to the manager
2888 interface, with an optional body representing additional arguments.  The
2889 body may be specified as a | delimeted list of headers. Each additional
2890 argument will be placed on a new line in the event. The format of the
2891 event will be:
2892     Event: UserEvent
2893     UserEvent: <specified event name>
2894     [body]
2895 If no body is specified, only Event and UserEvent headers will be present.
2896
2897 \end{verbatim}
2898
2899
2900 \section{Verbose}
2901 \subsection{Synopsis}
2902 \begin{verbatim}
2903 Send arbitrary text to verbose output
2904 \end{verbatim}
2905 \subsection{Description}
2906 \begin{verbatim}
2907 Verbose([<level>|]<message>)
2908   level must be an integer value.  If not specified, defaults to 0.
2909
2910 \end{verbatim}
2911
2912
2913 \section{VMAuthenticate}
2914 \subsection{Synopsis}
2915 \begin{verbatim}
2916 Authenticate with Voicemail passwords
2917 \end{verbatim}
2918 \subsection{Description}
2919 \begin{verbatim}
2920   VMAuthenticate([mailbox][@context][|options]): This application behaves the
2921 same way as the Authenticate application, but the passwords are taken from
2922 voicemail.conf.
2923   If the mailbox is specified, only that mailbox's password will be considered
2924 valid. If the mailbox is not specified, the channel variable AUTH_MAILBOX will
2925 be set with the authenticated mailbox.
2926
2927   Options:
2928     s - Skip playing the initial prompts.
2929
2930 \end{verbatim}
2931
2932
2933 \section{VoiceMail}
2934 \subsection{Synopsis}
2935 \begin{verbatim}
2936 Leave a Voicemail message
2937 \end{verbatim}
2938 \subsection{Description}
2939 \begin{verbatim}
2940   VoiceMail(mailbox[@context][&mailbox[@context]][...][|options]): This
2941 application allows the calling party to leave a message for the specified
2942 list of mailboxes. When multiple mailboxes are specified, the greeting will
2943 be taken from the first mailbox specified. Dialplan execution will stop if the
2944 specified mailbox does not exist.
2945   The Voicemail application will exit if any of the following DTMF digits are
2946 received:
2947     0 - Jump to the 'o' extension in the current dialplan context.
2948     * - Jump to the 'a' extension in the current dialplan context.
2949   This application will set the following channel variable upon completion:
2950     VMSTATUS - This indicates the status of the execution of the VoiceMail
2951                application. The possible values are:
2952                SUCCESS | USEREXIT | FAILED
2953
2954   Options:
2955     b    - Play the 'busy' greeting to the calling party.
2956     g(#) - Use the specified amount of gain when recording the voicemail
2957            message. The units are whole-number decibels (dB).
2958     s    - Skip the playback of instructions for leaving a message to the
2959            calling party.
2960     u    - Play the 'unavailable greeting.
2961
2962 \end{verbatim}
2963
2964
2965 \section{VoiceMailMain}
2966 \subsection{Synopsis}
2967 \begin{verbatim}
2968 Check Voicemail messages
2969 \end{verbatim}
2970 \subsection{Description}
2971 \begin{verbatim}
2972   VoiceMailMain([mailbox][@context][|options]): This application allows the
2973 calling party to check voicemail messages. A specific mailbox, and optional
2974 corresponding context, may be specified. If a mailbox is not provided, the
2975 calling party will be prompted to enter one. If a context is not specified,
2976 the 'default' context will be used.
2977
2978   Options:
2979     p    - Consider the mailbox parameter as a prefix to the mailbox that
2980            is entered by the caller.
2981     g(#) - Use the specified amount of gain when recording a voicemail
2982            message. The units are whole-number decibels (dB).
2983     s    - Skip checking the passcode for the mailbox.
2984     a(#) - Skip folder prompt and go directly to folder specified.
2985            Defaults to INBOX
2986
2987 \end{verbatim}
2988
2989
2990 \section{Wait}
2991 \subsection{Synopsis}
2992 \begin{verbatim}
2993 Waits for some time
2994 \end{verbatim}
2995 \subsection{Description}
2996 \begin{verbatim}
2997   Wait(seconds): This application waits for a specified number of seconds.
2998 Then, dialplan execution will continue at the next priority.
2999   Note that the seconds can be passed with fractions of a second. For example,
3000 '1.5' will ask the application to wait for 1.5 seconds.
3001
3002 \end{verbatim}
3003
3004
3005 \section{WaitExten}
3006 \subsection{Synopsis}
3007 \begin{verbatim}
3008 Waits for an extension to be entered
3009 \end{verbatim}
3010 \subsection{Description}
3011 \begin{verbatim}
3012   WaitExten([seconds][|options]): This application waits for the user to enter
3013 a new extension for a specified number of seconds.
3014   Note that the seconds can be passed with fractions of a second. For example,
3015 '1.5' will ask the application to wait for 1.5 seconds.
3016   Options:
3017     m[(x)] - Provide music on hold to the caller while waiting for an extension.
3018                Optionally, specify the class for music on hold within parenthesis.
3019
3020 \end{verbatim}
3021
3022
3023 \section{WaitForRing}
3024 \subsection{Synopsis}
3025 \begin{verbatim}
3026 Wait for Ring Application
3027 \end{verbatim}
3028 \subsection{Description}
3029 \begin{verbatim}
3030   WaitForRing(timeout)
3031 Returns 0 after waiting at least timeout seconds. and
3032 only after the next ring has completed.  Returns 0 on
3033 success or -1 on hangup
3034
3035 \end{verbatim}
3036
3037
3038 \section{WaitForSilence}
3039 \subsection{Synopsis}
3040 \begin{verbatim}
3041 Waits for a specified amount of silence
3042 \end{verbatim}
3043 \subsection{Description}
3044 \begin{verbatim}
3045   WaitForSilence(silencerequired[|iterations][|timeout]) 
3046 Wait for Silence: Waits for up to 'silencerequired' 
3047 milliseconds of silence, 'iterations' times or once if omitted.
3048 An optional timeout specified the number of seconds to return
3049 after, even if we do not receive the specified amount of silence.
3050 Use 'timeout' with caution, as it may defeat the purpose of this
3051 application, which is to wait indefinitely until silence is detected
3052 on the line.  This is particularly useful for reverse-911-type
3053 call broadcast applications where you need to wait for an answering
3054 machine to complete its spiel before playing a message.
3055 The timeout parameter is specified only to avoid an infinite loop in
3056 cases where silence is never achieved.  Typically you will want to
3057 include two or more calls to WaitForSilence when dealing with an answering
3058 machine; first waiting for the spiel to finish, then waiting for the beep, etc.
3059
3060 Examples:
3061   - WaitForSilence(500|2) will wait for 1/2 second of silence, twice
3062   - WaitForSilence(1000) will wait for 1 second of silence, once
3063   - WaitForSilence(300|3|10) will wait for 300ms silence, 3 times,
3064      and returns after 10 sec, even if silence is not detected
3065
3066 Sets the channel variable WAITSTATUS with to one of these values:
3067 SILENCE - if exited with silence detected
3068 TIMEOUT - if exited without silence detected after timeout
3069
3070 \end{verbatim}
3071
3072
3073 \section{WaitMusicOnHold}
3074 \subsection{Synopsis}
3075 \begin{verbatim}
3076 Wait, playing Music On Hold
3077 \end{verbatim}
3078 \subsection{Description}
3079 \begin{verbatim}
3080 WaitMusicOnHold(delay): Plays hold music specified number of seconds.  Returns 0 when
3081 done, or -1 on hangup.  If no hold music is available, the delay will
3082 still occur with no sound.
3083
3084 \end{verbatim}
3085
3086
3087 \section{While}
3088 \subsection{Synopsis}
3089 \begin{verbatim}
3090 Start a while loop
3091 \end{verbatim}
3092 \subsection{Description}
3093 \begin{verbatim}
3094 Usage:  While(<expr>)
3095 Start a While Loop.  Execution will return to this point when
3096 EndWhile is called until expr is no longer true.
3097
3098 \end{verbatim}
3099
3100
3101 \section{Zapateller}
3102 \subsection{Synopsis}
3103 \begin{verbatim}
3104 Block telemarketers with SIT
3105 \end{verbatim}
3106 \subsection{Description}
3107 \begin{verbatim}
3108   Zapateller(options):  Generates special information tone to block
3109 telemarketers from calling you.  Options is a pipe-delimited list of
3110 options.  The following options are available:
3111 'answer' causes the line to be answered before playing the tone,
3112 'nocallerid' causes Zapateller to only play the tone if there
3113 is no callerid information available.  Options should be separated by |
3114 characters
3115
3116 \end{verbatim}
3117
3118
3119 \section{ZapBarge}
3120 \subsection{Synopsis}
3121 \begin{verbatim}
3122 Barge in (monitor) Zap channel
3123 \end{verbatim}
3124 \subsection{Description}
3125 \begin{verbatim}
3126   ZapBarge([channel]): Barges in on a specified zap
3127 channel or prompts if one is not specified.  Returns
3128 -1 when caller user hangs up and is independent of the
3129 state of the channel being monitored.
3130 \end{verbatim}
3131
3132
3133 \section{ZapRAS}
3134 \subsection{Synopsis}
3135 \begin{verbatim}
3136 Executes Zaptel ISDN RAS application
3137 \end{verbatim}
3138 \subsection{Description}
3139 \begin{verbatim}
3140   ZapRAS(args): Executes a RAS server using pppd on the given channel.
3141 The channel must be a clear channel (i.e. PRI source) and a Zaptel
3142 channel to be able to use this function (No modem emulation is included).
3143 Your pppd must be patched to be zaptel aware. Arguments should be
3144 separated by | characters.
3145
3146 \end{verbatim}
3147
3148
3149 \section{ZapScan}
3150 \subsection{Synopsis}
3151 \begin{verbatim}
3152 Scan Zap channels to monitor calls
3153 \end{verbatim}
3154 \subsection{Description}
3155 \begin{verbatim}
3156   ZapScan([group]) allows a call center manager to monitor Zap channels in
3157 a convenient way.  Use '#' to select the next channel and use '*' to exit
3158 Limit scanning to a channel GROUP by setting the option group argument.
3159
3160 \end{verbatim}
3161
3162