Automated dial out

The Asterisk dial plan extensions.conf responds to someone calling an extension on a channel. If you want to initiate a call from an external application, there are several ways to do this.

There are basically four ways to initiate outgoing calls in Asterisk

• Use .call files. A call file is a text file that when placed in the correct directory makes Asterisk make an outgoing call.
• Use the manager API to activate a call. See Asterisk manager dialout
• Use the Asterisk CLI originate command
• FollowMe command of Asterisk 1.4: Since this has the abitility to fork (create multiple calls) it could be 'misused' to initiate outgoing calls.

See also additional Digium documents.

Call files

• Move a call file into /var/spool/asterisk/outgoing
• Asterisk will notice and immediately call the indicated channel and connect it to the specified extension at the priority specified in the call file.
• If the modification date on the call file is in the future, Asterisk will wait until the modification date arrives before executing the call file.
• Example: See "sample.call"
• if autoload=no in modules.conf be sure to load pbx_spool.so, otherwise call files will not work

Syntax of call files

• Specify where and how to call
  • Channel: <channel>: Channel to use for the outbound call
  • CallerID: Name <number> Caller ID, please note that it may not work if you do not respect the format: CallerID: Some Name <1234>
  • MaxRetries: <number> Number of retries before failing (not including the initial attempt, e.g. 0 = total of 1 attempt to make the call)
  • RetryTime: <number> Seconds between retries, don't hammer an unavailable phone
  • WaitTime: <number> Seconds to wait for an answer
  • Account: Set the account code to use.
• If the call answers, connect it here
  • Context: <context-name> Context in extensions.conf
  • Extension: <ext> Extension definition in extensions.conf
  • Priority: <priority> Priority of extension to start with
  • Set: Set a variable for use in the extension logic (example: file1=/tmp/to ); in Asterisk 1.0.x use 'SetVar' instead of 'Set'
  • Application: Asterisk Application to run (use instead of specifiying context, extension and priority)
  • Data: The options to be passed to application
• New (?) in Asterisk 1.4
  • Set: Can now also write to dialplan functions like CDR()
  • AlwaysDelete: Yes/No - If the file's modification time is in the future, the call file will not be deleted
  • Archive: Yes/No - Move to subdir "outgoing_done" with "Status: value", where value can be Completed, Expired or Failed.

At least one of app or extension must be specified, along with channel and destination

The 'failed' extension

If the call is not answered, and the standard extension failed with priority 1 exists in the same context, control will jump there (feature introduced in either Asterisk 1.2 or 1.4. NOTE: This works in asterisk 1.2.14)

• Note 1: This only works if you made the call with context, extension, and priority defined, and didn't use the application, data form.
• Note 2: This is a good place to update the CDR UserField with a value of the phone number that was being dialed using the SetCDRUserfield() application. Asterisk (as of 1.2.10) does not make the dialed channel (eg. IAX2/15551234567) available anywhere, so you have to pass it to yourself using Set: field of the .call file. (Along with anything else you want pass to the channel in this same variable).

Example

Scope of variables

• Make sure you know what prefixing a variable with _ or __ does!
• Especially Asterisk 1.0 and 1.2 behave differently for what concerns a) passing on variables to channels and b) global variables
• Consider using DBGet and DBPut if you experience trouble passing variables

Creating and moving call files

Because Asterisk can grab these files at any time (e.g. when the file is only 1/2 written), do not create the file directly in the /var/spool/asterisk/outgoing directory. Do something like this:

• create the call file in a different directory - e.g. /var/spool/asterisk/temp1234
• chown asterisk:asterisk /var/spool/asterisk/temp1234 (if temp1234 was created by root and Asterisk is running as username asterisk)
• mv /var/spool/asterisk/temp1234 /var/spool/asterisk/outgoing

This works because the Unix move operation (mv command) merely moves the "inode" — the pointer to the file — making the entire file appear all at once and eliminates the possibility that Asterisk could read and act upon a partially written file. (Note that this is only true if the source and destination are on the same file system; otherwise, it does the equivalent of a "cp"; see below.)
Note: Using the copy command (cp) is not a safe method for adding a file to the outbound directory since other programs can read the new file in the midst of the copy operation when the file is only partially written.

VB Scripts for creating your call files from a simple text file and then moving the files to asterisk spool directory using pscp.

First you have to create the text files using a text file that has all the phone numbers, this script expects the text file to be in format of one phone number per line.
It then goes thru the text file and creates a new subfolder in current working directory for each 20 phone numbers it finds.
It uses the phone number as the file name for each call file. Each subfolder that contains 20 call files is named with a number starting from 1.
Once the call files are created use the second script to move it into the spool directory using pscp.
Pscp is a free file transfer program that works over SSH, before you use this script make sure you have putty on your machine, create a saved session on putty for your asterisk system.

;!!!!!!!!!!!!!!!!!!!!!
;Creates call text files taking the numbers from a flat text file that has one phone number per line
;expample phonenumbers.txt
;1234567890
;2134567890
;a text file that contains the 2 lines above (without the colons) will create 2 text files one for each number
;you can copy and paste this whole code into a .vbs file in windows and then execute it.
;put the file in the same directory as the text file with the phone numbers are.

Set objFSO = CreateObject("Scripting.FileSystemObject")
Set objFilePhones = objFSO.OpenTextFile("C:\calls\Phone.txt",1) ;change this line to your path
strfname=1
strcnt=1
Set objFolders=objFSO.CreateFolder(strfname)
Do While objFilePhones.AtEndOfStream = False
	If strcnt=20 then;change this number to anything else if you want more or fewer simultaneous calls.
		strfname=strfname+1

		Set objFolders=objFSO.CreateFolder(strfname)
		strcnt=1
	end if
	strLine = objFilePhones.ReadLine

	strFullName = objFSO.BuildPath(strfname, strLine)
	Set objFileCalls = objFSO.CreateTextFile(strFullName)
	objFileCalls.close
	Set objFileCalls = objFSO.OpenTextFile(strFullName,2)
	objFileCalls.Write("Channel: ");put your channel information here, add a 1 before the number if your provider requires that
	objFileCalls.WriteLine(strLine)
	objFileCalls.WriteLine("CallerID: Name <1234>");change caller id as needed
	objFileCalls.WriteLine("MaxRetries: 0");change this if you want it to retry
	objFileCalls.WriteLine("RetryTime: 3")
	objFileCalls.WriteLine("WaitTime: 30");change this if you want it to ring longer before giving up
	objFileCalls.WriteLine("Context: test");put context here
	objFileCalls.WriteLine("Extension: 800");put extension here
	objFileCalls.WriteLine("Priority: 1");put priority here
	objFileCalls.Close
	strcnt=strcnt+1
Loop
;end code for first script that creates the call files.
;the next script moves the files to the asterisk spool directory expecting pscp to be located under c:\pscp.exe and a named saved session to your asterisk box in putty as asterisk.
;paste as needed
Set objFSO = CreateObject("Scripting.FileSystemObject")

strcnt=1
strfldr="C:\calls\"&strcnt

for i=1 to 1000 ;assuming that you don't have more than 1000 folders or 20000 files, if you do change this number
If objFSO.FolderExists(strfldr) Then
	strfldr="C:\calls\"&strcnt ;change path as needed
	Set objShell = CreateObject("WScript.Shell")
	strcmd="C:\pscp -pw passwordhere c:\calls\"&strcnt&"\* root@asterisk:/var/spool/asterisk/outgoing";change username and password as needed, as well as path to pscp and call files
	objShell.Run strcmd
	strcnt=strcnt+1

else
	exit for
End If

wscript.sleep(36000);change time interval between every folder it moves, when I created it I was dealing with recordings of 15-20 seconds and 30 second wait time to answer the call, since I didn't want more than 20 calls simultaneous this worked for me. change as you like

next
;end second file, paste this to a new .vbs file under the same directory then execute it.
;end code

Examples

Example 1

Filename: 1.call


This will hook up to priority 2 of extension 800 in context callme in extensions.conf.

Example 2

The above examples are good if you want to automatically play some recorded message, or something automatic that must start when the other party picks up the phone. In fact if you use the above for a conversation, you will have the outgoing phone ring, and when the other person picks up his phone, only then your extension starts to ring, so you miss the initial "hello" and maybe some more words!
If you have outgoing calls in your dialplan defined in the [outgoing] context, to call 14109850123 do this:

Example 3

Example 4

Example 5

On a trixbox/freepbx system this will dial internal extension 1000 (or you can put even an outside # here and it will follow outbound rules) and connect it to an AGI program. Note that unlike in extensions.conf where you can specify AGI(file.agi), here it must be separated. I use one agi to detect an incoming call to a special extension#, record the caller id, and then create the .call file to call back that number and connect it to a second agi.

How to schedule a Call in the Future

Files with a modified date in the future are ignored until that time arrives. Create the file in /var/spool/asterisk/tmp, modify the mtime using "touch", and then move it...

Tip on managing the number of simultaneous outbound calls

You can limit the number of simultaneous outgoing calls by managing the number of files in the outbound directory (/var/spool/asterisk/outgoing). For example, to limit Asterisk to only doing 10 simultaneous outdials just limit the number of files in the outbound directory to 10 at any one time. As the number decreases, you can move additional files into the directory to maintain the number of outgoing calls at the desired level.

Note: There are various user reports of Asterisk choking (=not processing some of the .call files) when too many files are moved simultaneously into the outgoing directory. Therefore it may be advisable to move them step-by-step with a slight delay.
However, even then it is possible that Asterisk once in a while 'forgets' to process a call file (seen e.g. in 1.0.9). Possible soltuions:

• 1. Find the cause and fix it in the source code,
• 2. Use the Manager API which hopefully doesn't exhibit this problem,
• 3. Design your application to cope with this effect, for example counter check the existence of CDR data against your .call file details (execution time, destination, accountcode etc).

More examples

• Asterisk tips callback: How to create a callback system with .call files
• Asterisk tips Wake-Up Call PHP: Create, manage and execute Wake-Up calls via phone
• Asterisk auto-dial out deliver message
• A telephone reminder system for Asterisk

Callfiles and Call Detail Records

• Avoid missing CDR records: Use either a) Context/Extension/Priority in the call file instead of Application/Data, or b) call a Local channel instead of directly calling the desired channel. Else Asterisk will bypass the process that tracks the call and no CDR record will be generated. When using Context/Extension/Priority, you are really using a Goto type function which just puts the call into the correct part of the dialplan and to it is the same as if the caller had dialed the call manually and so the call is logged.
• The phone number you are dialling will not be stored in the CDR by * - if you need this information for CDR processing you can set the CallerID in the call file to this number and it will be stored. However, this will present the person you are calling their own phone number, which doesn't make much sense. A better solution might be to put the number you are dialing in the Set: channel variable in the .call file and later put it into the UserField of the CDR. See example above in the first section.

Tips and hints

• Create the call file elsewhere, and move it (better not use copy, see above) into the directory after you're done creating it. Asterisk is very aggressive in grabbing these files, and if you're still creating it when it grabs the file, you'll get errors, so best to create first and then copy in to the outgoing directory all at once.
• The call file must be owned by the user asterisk runs as, so asterisk can utime() it, or you will get permission errors.
• If you are using POTS (Plain Old Telephone System) lines attached to a channel bank with FXO cards, it's likely that you will run into problems sensing when your callee picks up their phone - especially to cell phones. Once Asterisk hands off a call to an FXO line (ie, it starts to ring), the system counts the call as 'answered', and continues its merry way. This means that your voice prompts get played to a ring tone, and your users are presented with a silent call.

Some things to try:

• In zapata.conf, try adding callprogress=yes above your channel => n definition for the FXO lines. (remember that settings set above the channel flow down, and that you need to clear this setting with a callprogress=no for any channels you might not want this to affect!)
  • This is experimental, only sometimes works, and only for North American tones.
  • On my system, this setting failed miserably, to the point that I could no longer make outgoing calls, and calls were dropped.
• Another option (At least in example 3), is to repeat your message. Note the ResponseTimeout(2), to set the pause between repeats to 2 seconds, and the GoTo(s|1), to repeat the prompts.
• Yet another option is to use an application like "WaitForSilence" that will wait for a certain amount of silence before beginning to play the message. See bugs.digium.com #2467 for this app, which will probably soon appear in CVS.
• Try app_machinedetect.c application for detection of answering machines. This works best with PRI, VoIP, or a POTS with callprogress enabled.

A Few Ideas

What can you do with this interface?

• Set up a cron job to dial out at specific times
• You could start at an extension that checks if a user is logged in (chanIsAvailable) and if so, dials and reminds the user to log out, go home and go to bed :-)
• Have other applications create call files for alerts or alarms
• Dial a call group with agents
• Create a own callback from an extension, by using DISA. Caller calls the asterisk, asterisk hangs up and call him back, gives him a "free line" to call out!

See also

• Asterisk CLI: originate command
• Asterisk Manager API Action Originate
• Asterisk manager dialout
• Asterisk tips and tricks
• Asterisk config extensions.conf
• Asterisk variables
• Asterisk auto-dial out deliver message
• A telephone reminder system for Asterisk
• A free autodialer software (Windows platform) which utilizes Manager API.

---

Go back to Asterisk