Using the Outbound Tools in the DEV web UI

Queuing Single Outbound Calls Using the Web Interface

To queue up outbound calls, first go to the Outbound Calling page.

Once on the Outbound Calling page, click on “Plum Web Services API Examples” to open up an API examples page to allow you to place calls by entering information in the web form.

Once you're on the Plum Web Services API Examples page, you can begin to enter the information for queuing your outbound call. The required sections that need to be filled out are: Login, PIN, Phone Number, and Start URL. You can find the Login and PIN by looking back at the Outbound Calling page.

Once you've entered the Login and PIN, you will need to enter the phone number of the callee you want to dial along with the URL of your VXML application script. Once you've entered this information, click on the “Queue Call” button to queue your outbound call.

Queuing Multiple Outbound Calls Using the Web Interface

To queue an outbound campaign of multiple outbound calls, you can scroll down the Plum Web Services API Examples page to “Create a Call Campaign with the queuecalls web service”. The required sections that need to be filled out are: Login, PIN, Campaign Name, Phone Number List, and Start URL. As mentioned above, the Login and PIN can be found on the Outbound Calling page. The Campaign Name is a unique name that you give your campaign to differentiate it from other campaigns you may create. The Phone Number List is a text file that you upload to the form that contains a list of phone numbers that you want to dial. The Start URL is simply the URL of your VXML application script.

Using the Optional Parameters and Settings

Now that we've shown you how to queue simple calls and campaigns, let's demonstrate how you can use the optional parameters and settings within the web interface.

Result URL

result_url is a URL you can enter for post-call processing. Please note that the outbound system posts to the result_url either after all retry attempts have been made for the outbound call or after the outbound call successfully completes.

For the result_url callback, the parameters that are available for you to reference are: phone_number, message_reference, call_id, result, attempts, last_attempt_timestamp, and duration.

phone_number is the dialed phone number for the outbound call.

message_reference is an identifier that you can set to differentiate your outbound calls.

call_id is a specific Plum outbound assigned call identifier.

result is the status of the outbound call: it can return either “completed” or “failed”.

Below is an example you can reference that utilizes a result_url PHP script:

storeresults.php:

<?php
$File = "storeresults.txt";
$Handle = fopen($File, 'a+');
$Date = date("r");
$Result = $_POST[result];
$Callid = $_POST[call_id];
$Data = "$Date $Callid $Result\n";
fwrite($Handle, $Data);
print "Data Written";
fclose($Handle);
?>

From this example, after all retry attempts have been made for an outbound call or after an outbound call has successfully completed, the PHP script opens up a file called “storeresults.txt”. Then, a variable, $Date, is set to store the date. A variable, $Result, is set to store the result of the outbound call (“completed” or “failed”). A variable, $Callid, is set to store the call_id of the call. Next, a variable, $Data, is set to store $Date, $Result, and $Callid. Afterwards, the PHP script writes $Data to the storeresults.txt file.

Message Reference

message_reference is a unique identifier you can set that allows you to differentiate your outbound calls from one another. This same parameter can be used by the start_url to customize the call session.

Call Parameters

call_parameters allows you to send arbitrary data with possibly several different parameters sent in a single string.

Max Retries

max_retries allows you to set a maximum number of retries for attempting an outbound call before giving up. This number of retries can only be set to an integer between 0 and 10.

Retry Interval

retry_interval allows you to set the number of seconds in between retrying an outbound call. This number of seconds can be set to an integer between 60 and 172800.

Scheduled Timestamp

scheduled_timestamp allows you to set a UNIX-time integer indicating when to start attempting your outbound call. If you do not wish to use UNIX time, you can use the POST variable, scheduled_time, to use simple natural time expressions like “now”, “oct 14th, 2011 11:05PM EST”, or “+3 days”.

Expiration Timestamp

expiration_timestamp allows you to set a UNIX-time integer indicating when to give up attempting your outbound call. If you do not wish to use UNIX time, you can use the POST variable, expiration_time, to use simple natural time expressions like “now”, “oct 14th, 2011 11:05PM EST”, or “+3 days”.

Demonstration of Using Optional Parameters and Settings

From this example, we've entered the result_url and have set the maximum retries to 2, the retry interval to 10 minutes, the scheduled start time to 1323248400, and the expiration time to 1323249000.

The result_url utilizes the script above to store the date, result of the call (completed or failed), and the call ID. With maximum retries set to 2, the outbound system will attempt to dial the callee twice upon failure of an outbound call before giving up. With the retry interval set to 10 minutes, the outbound system will wait 10 minutes in between retry attempts. With the scheduled start time set to 1323248400, the outbound call is scheduled to start at 9:00 am on December 7, 2011. With the expiration time set to 1323249000, the outbound call is scheduled to expire at 9:10 am on December 7, 2011.

Checking the Status and Call Information for Outbound Calls

To check the outbound status of calls, place your mouse over Developer Tools and click on Outbound Calling. There, you will be able to see your outbound campaigns and see how many calls have Completed, how many calls have Failed, and how many calls are Pending.

To look at the status of a particular campaign, click on View for one of your campaigns. There, you will be able to see the Call Queue of your campaign and view the Phone Number, Call Info, Status, Attempt, Callee Type, and Message Reference (if one was included) for calls that have been completed and for calls that are still pending. To view the Call Info, click on the “i” symbol to view the details for the call.

If you wish to delete any pending calls, you can click on Delete to remove the call from the queue.

Queuing Outbound Calls Programmatically

Users can leverage Plum's Outbound APIs to automatically create and deploy outbound calling campaigns. See the DEV Outbound APIs for detailed information.

Below is a sample PHP script that utilizes the required POST variables to make a single outbound call:

singleoutboundcall.php

<?php

$params['login'] = "user1";
$params['pin'] = "12345678";
$params['phone_number'] = "tel:[phone]";
$params['start_url'] = "http://www.mywebserver.com/~user/myscript.php";

$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, "http://outbound.plumvoice.com/webservice/queuecall.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);
echo $result;

curl_close($ch);

?>

Queuing Multiple Outbound Calls Programmatically

Below is a sample PHP script that utilizes the required POST variables to queue an outbound campaign:

outboundcampaign.php

<?php

$params['login'] = "user2";
$params['pin'] = "88888888";
$params['campaign_name'] = "callnumbers";
$params['phone_list'] = "@path/to/file/phonenumbers.txt";
$params['start_url'] = "http://www.mywebserver.com/~user/myscript.php";

$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, "http://outbound.plumvoice.com/webservice/queuecalls.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);


$result = curl_exec($ch);
echo $result;

curl_close($ch);

?>

Please note that in the phonenumbers.txt file, when entering the phone numbers to dial, please be sure to include the 1 before the area code.