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