doc/callfiles.txt

   1 Asterisk call files
   2 ===================
   3
   4 Asterisk has the ability to initiate a call from outside of the normal
   5 methods such as the dialplan, manager interface, or spooling interface.
   6
   7 Using the call file method, you must give Asterisk the following information:
   8
   9 * How to perform the call, similar to the Dial() application
  10 * What to do when the call is answered
  11
  12 With call files you submit this information simply by creating a file with
  13 the required syntax and placing it in the outgoing spooling directory, located
  14 by default in /var/spool/asterisk/outgoing/ (configurable in asterisk.conf).
  15
  16 The pbx_spool module aggressively examines the directory contents every second,
  17 creating a new call for every call file it finds. Do NOT write or create
  18 the call file directly in the outgoing directory, but always create the file
  19 in another directory of the same filesystem and then move the file to the
  20 /var/spool/asterisk/outgoing directory, or Asterisk may read just a partial
  21 file.
  22
  23
  24 The call file syntax
  25 ====================
  26
  27 The call file consists of <Key>: <value> pairs; one per line.
  28
  29 Comments are indicated by a '#' character that begins a line, or follows a space
  30 or tab character.  To be consistent with the configuration files in Asterisk,
  31 comments can also be indicated by a semicolon.  However, the multiline comments
  32 (;-- --;) used in Asterisk configuration files are not supported. Semicolons can
  33 be escaped by a backslash.
  34
  35
  36 The following keys-value pairs are used to specify how setup a call:
  37
  38 Channel: <channel>      the channel to use for the new call, in the form
  39                         technology/resource as in the Dial application. This
  40                         value is required.
  41
  42 Callerid: <callerid>    the caller id to use.
  43
  44 WaitTime: <number>      how many seconds to wait for an answer before the call
  45                         fails (ring cycle). Default 45 seconds.
  46
  47 Maxretries: <number>    number of retries before failing, not including the
  48                         initial attempt. Default = 0 e.g. don't retry if fails.
  49
  50 RetryTime: <number>     how many seconds to wait before retry. The default is
  51                         300 (5 minutes).
  52
  53 Account: <account>      the account code for the call. This value will be
  54                         assigned to CDR(accountcode)
  55
  56
  57
  58 When the call answers there are two choices:
  59 * Execute a single application, or
  60 * Execute the dialplan at the specified context/extension/priority.
  61
  62
  63 To execute an application:
  64 --------------------------
  65
  66 Application: <appname>  the application to execute
  67
  68 Data: <args>            the application arguments
  69
  70
  71 To start executing applications in the dialplan:
  72 ------------------------------------------------
  73
  74 Context: <context>      the context in the dialplan
  75
  76 Extension: <exten>      the extension in the specified context
  77
  78 Priority: <priority>    the priority of the specified extension
  79                         (numeric or label)
  80
  81
  82
  83 Setvar: <var=value>     you may also assign values to variables that will be
  84                         available to the channel, as if you had performed a
  85                         Set(var=value) in the dialplan. More than one Setvar:
  86                         maybe specified.
  87
  88
  89 The processing of the call file ends when the call is answered and terminated; when
  90 the call was not answered in the initial attempt and subsequent retries; or if
  91 the call file can't be successfully read and parsed.
  92
  93 To specify what to do with the call file at the end of processing:
  94
  95 Archive: <yes|no>       if "no" the call file is deleted. If set to "yes" the
  96                         call file is moved to the "outgoing_done" subdirectory
  97                         of the Asterisk spool directory. The default is to
  98                         delete the call file.
  99
 100
 101 If the call file is archived, Asterisk will append to the call file:
 102
 103 Status: <exitstatus>    can be "Expired", "Completed" or "Failed"
 104
 105
 106
 107 Other lines generated by Asterisk:
 108
 109 Asterisk keep track of how many retries the call has already attempted,
 110 appending to the call file the following key-pairs in the form:
 111
 112 StartRetry: <pid> <retrycount> (<time>)
 113 EndRetry: <pid> <retrycount> (<time>)
 114
 115 With the main process ID (pid) of the Asterisk process, the retry number, and
 116 the attempts start and end times in time_t format.
 117
 118
 119
 120 Directory locations
 121 ===================
 122
 123 <astspooldir>/outgoing          the outgoing dir, where call files are put
 124                                 for processing
 125
 126 <astspooldir>/outgoing_done     the archive dir
 127
 128
 129 <astspooldir> is specified in asterisk.conf, usually /var/spool/asterisk
 130
 131
 132
 133 How to schedule a call
 134 ======================
 135
 136 Call files that have the time of the last modification in the future are ignored
 137 by Asterisk. This makes it possible to modify the time of a call file to the
 138 wanted time, move to the outgoing directory, and Asterisk will attempt to
 139 create the call at that time.