asterisk/doc/callfiles.txt

Asterisk call files
===================

Asterisk has the ability to initiate a call from outside of the normal
methods such as the dialplan, manager interface, or spooling interface.

Using the call file method, you must give Asterisk the following information:

* How to perform the call, similar to the Dial() application
* What to do when the call is answered

With call files you submit this information simply by creating a file with 
the required syntax and placing it in the outgoing spooling directory, located
by default in /var/spool/asterisk/outgoing/ (configurable in asterisk.conf).

The pbx_spool module aggressively examines the directory contents every second,
creating a new call for every call file it finds. Do NOT write or create
the call file directly in the outgoing directory, but always create the file
in another directory of the same filesystem and then move the file to the
/var/spool/asterisk/outgoing directory, or Asterisk may read just a partial 
file.


The call file syntax
====================

The call file consists of <Key>: <value> pairs; one per line.

Comments are indicated by a '#' character that begins a line, or follows a space
or tab character.  To be consistent with the configuration files in Asterisk,
comments can also be indicated by a semicolon.  However, the multiline comments
(;-- --;) used in Asterisk configuration files are not supported. Semicolons can
be escaped by a backslash.


The following keys-value pairs are used to specify how setup a call:

Channel: <channel>      the channel to use for the new call, in the form
                        technology/resource as in the Dial application. This
                        value is required.

Callerid: <callerid>    the caller id to use.

WaitTime: <number>      how many seconds to wait for an answer before the call
                        fails (ring cycle). Default 45 seconds.

Maxretries: <number>    number of retries before failing, not including the
                        initial attempt. Default = 0 e.g. don't retry if fails.

RetryTime: <number>     how many seconds to wait before retry. The default is
                        300 (5 minutes).

Account: <account>      the account code for the call. This value will be
                        assigned to CDR(accountcode)



When the call answers there are two choices: 
* Execute a single application, or
* Execute the dialplan at the specified context/extension/priority.


To execute an application:
--------------------------

Application: <appname>  the application to execute

Data: <args>            the application arguments


To start executing applications in the dialplan:
------------------------------------------------

Context: <context>      the context in the dialplan

Extension: <exten>      the extension in the specified context

Priority: <priority>    the priority of the specified extension 
                        (numeric or label)



Setvar: <var=value>     you may also assign values to variables that will be
                        available to the channel, as if you had performed a
			Set(var=value) in the dialplan. More than one Setvar:
			maybe specified.


The processing of the call file ends when the call is answered and terminated; when
the call was not answered in the initial attempt and subsequent retries; or if
the call file can't be successfully read and parsed.

To specify what to do with the call file at the end of processing:

Archive: <yes|no>       if "no" the call file is deleted. If set to "yes" the 
                        call file is moved to the "outgoing_done" subdirectory 
                        of the Asterisk spool directory. The default is to 
			delete the call file.


If the call file is archived, Asterisk will append to the call file:

Status: <exitstatus>    can be "Expired", "Completed" or "Failed"



Other lines generated by Asterisk:

Asterisk keep track of how many retries the call has already attempted, 
appending to the call file the following key-pairs in the form:

StartRetry: <pid> <retrycount> (<time>)
EndRetry: <pid> <retrycount> (<time>)

With the main process ID (pid) of the Asterisk process, the retry number, and
the attempts start and end times in time_t format.



Directory locations
===================

<astspooldir>/outgoing          the outgoing dir, where call files are put
                                for processing

<astspooldir>/outgoing_done     the archive dir


<astspooldir> is specified in asterisk.conf, usually /var/spool/asterisk



How to schedule a call
======================

Call files that have the time of the last modification in the future are ignored
by Asterisk. This makes it possible to modify the time of a call file to the
wanted time, move to the outgoing directory, and Asterisk will attempt to
create the call at that time.