7.2. Call Files

Call files are like a shell script for Asterisk. A user or application writes a call file into /var/spool/asterisk/outgoing/ where Asterisk processes it immediately.

Important

A mv (move) is an atomic operation (an operation which does not take effect until it is 100% complete) and as such is ideally suited for .call files. With cp (copy), the file is copied line by line, which could lead to Asterisk processing an incomplete file.
Let's demonstrate the .call file principle with an example. Assume that we have a SIP phone registered with the number 2000 in Asterisk. In addition, we have the following extension in the dialplan:
[call-file-test]
exten => 10,1,Answer()
exten => 10,n,Wait(1)
exten => 10,n,Playback(hello-world)
exten => 10,n,Wait(1)
exten => 10,n,Hangup()
We create a call file called a-test.call in /tmp/ with the following content:
Channel: SIP/2000
MaxRetries: 2
RetryTime: 60
WaitTime: 30
Context: call-file-test
Extension: 10
Now we move this file with mv /tmp/a-test.call /var/spool/asterisk/outgoing/
root@molokai:~>mv /tmp/a-test.call /var/spool/asterisk/outgoing/
The following happens:
  • Asterisk polls the /var/spool/asterisk/outgoing/ for new call files and processes any it finds.
  • Asterisk opens a connection to device SIP/2000. If the device is in use or not answered, Asterisk tries two more times (see MaxRetries).
  • If someone answers SIP/2000, Asterisk begins processing extension 10 in the context [call-file-test]. In this case, Asterisk plays hello-world to the answering party.

Parameters

These parameters may be used in call files:
Channel: <channel>
The channel upon which to initiate the call. Uses the same syntax as the Dial() command (see Section B.27, “Dial()).
Callerid: <callerid>
The caller ID to be used for the call.
WaitTime: <number>
Number of seconds the system waits for the call to be answered. If not specified, defaults to 45 seconds.
MaxRetries: <number>
Maximum number of dial retries (if an attempt fails because the device is busy or not reachable). If not specified, defaults to 0 (only one attempt is made).
RetryTime: <number>
Number of seconds to wait until the next dial attempt. If not specified, defaults to 300 seconds.
Account: <account>
The account code for the CDR.
Context: <context>
The destination context.
Extension: <exten>
The destination extension, in which dialplan execution begins if the device is answered.
Priority: <priority>
The destination priority. If not specified, defaults to 1.
Setvar: <var=value>
Setvar: lets you set one or more channel variables.
Archive: <yes|no>
By default, call files are deleted immediately upon execution. If Archive: yes is set, they are copied into /var/spool/asterisk/outgoing_done/ instead. Asterisk adds a line to the call file which describes the result:

Status: <Expired|Completed|Failed>

Executing call files in the future

When executing a call file, Asterisk compares the change time with the current time. If the change time is in the future, Asterisk ignores the call file. This is an easy way to implement time-based call files.

Hotel wake-up call example

A hotel wants to implement a simple wake-up call system. Clients must be able to set a wake-up call by dialing *77*, whereupon they hear a prompt asking for the date and time of the wake-up call.
[hotel-intern]
exten => _*77*XXXXXXXXXXXX,1,Answer()
exten => _*77*XXXXXXXXXXXX,n,Set(year=${EXTEN:4:4})
exten => _*77*XXXXXXXXXXXX,n,Set(month=${EXTEN:8:2})
exten => _*77*XXXXXXXXXXXX,n,Set(day=${EXTEN:10:2})
exten => _*77*XXXXXXXXXXXX,n,Set(hours=${EXTEN:12:2})
exten => _*77*XXXXXXXXXXXX,n,Set(minutes=${EXTEN:14:2})
exten => _*77*XXXXXXXXXXXX,n,NoOp(Wake-up call scheduled for ${CALLERID(num)} at ${hours}:${minutes} on ${day}.${month}.${year}.)
exten => _*77*XXXXXXXXXXXX,n,System(echo -e "Channel: SIP/${CALLERID(num)}\\nContext: wake-up\\nExtension: 23" > /tmp/${UNIQUEID}.call)
exten => _*77*XXXXXXXXXXXX,n,System(touch -t ${year}${month}${day}${hours}${minutes} /tmp/${UNIQUEID}.call)
exten => _*77*XXXXXXXXXXXX,n,System(mv /tmp/${UNIQUEID}.call /var/spool/asterisk/outgoing/)
exten => _*77*XXXXXXXXXXXX,n,Playback(rqsted-wakeup-for)
exten => _*77*XXXXXXXXXXXX,n,SayNumber(${hours})
exten => _*77*XXXXXXXXXXXX,n,SayNumber(${minutes})
exten => _*77*XXXXXXXXXXXX,n,Hangup()

[wake-up]
exten => 23,1,Answer()
exten => 23,n,Wait(1)
exten => 23,n,Playback(this-is-yr-wakeup-call)
exten => 23,n,Wait(1)
exten => 23,n,Hangup()