Plum Fuse

Using the Outbound API

« Prev Section Using the Outbound Modules

The Outbound API can be used by developers to queue outbound calls programmatically. In this section we'll walk you through a couple of examples that demonstrate how you can queue an outbound campaign by POSTing parameters to the URL:

http://quickfuseapps.com/api/1/outbound/queue

NOTE: For our examples, we'll be using PHP and its cURL library to demonstrate what we can do with the outbound API. You can use any other programming language that can make HTTP requests, and if the language has libcurl bindings the below examples will still be relevant. You can even use the command-line binary of cURL, a free download for many platforms, with the Plum Fuse API. The API documentation provides examples using cURL command-line invocations.

Simple Outbound Call Example

For the Simple Outbound Call Example, we're going to use the bare minimum in queuing an outbound campaign. This means that we're only going to use the following parameters: app_id, tablekey, and dial_col.

runoutboundcall.php:

<?php

$params = array();
$params['app_id'] = "XNpo5myMZlk";
$params['tablekey'] = "plumvoice:Updatecallrow";
$params['dial_col'] = "Phone";

// php curls
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "plumvoice:passwordgoeshere");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, "http://quickfuseapps.com/api/1/outbound/queue");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

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

curl_close($ch);

?>

From this example, we have set up our parameters in $params: app_id, tablekey, and dial_col.

To get the app_id, you would need to mouse over one of your applications on the My Apps page.

For tablekey, it is simply the owner of the table and the name of the table. However, it must be written in the format of <tableowner>:<tablename>. So, for our example, plumvoice is the owner of our table, Updatecallrow and it is written as plumvoice:Updatecallrow.

For dial_col, it is just the column of phone numbers to dial in our data table, Updatecallrow.

Once the parameters are set up, we move on to our PHP cURL statements. A couple of important things to note:

1) We use CURLOPT_USERPWD to establish the connection with the username and password for our account (in this case, the username is “plumvoice” and the password is “passwordgoeshere”).

2) We use CURLOPT_POSTFIELDS to post our full data, stored in $params.

3) We use CURLOPT_URL to fetch our URL, http://quickfuseapps.com/api/1/outbound/queue.

From here, we can open up our web browser and queue up our outbound campaign by having our client application, runoutboundcall.php, post an HTTP request to http://quickfuseapps.com/api/1/outbound/queue.

If the campaign was successfully queued, you would see the following in your web browser:

{
  "result": true
}

and if not, an error response is issued.

Intermediate Outbound Call Example

For the Intermediate Outbound Call example, we're going to use the result_col parameter to save our results for each call and the start_timestamp parameter to set up a time to begin our outbound campaign.

runoutboundcall2.php:

<?php

$params = array();
$params['app_id'] = "XNpo5myMZlk";
$params['tablekey'] = "plumvoice:Updatecallrow";
$params['dial_col'] = "Phone";
$params['result_col'] = "Status";
$params['start_timestamp'] = "1280849900";

// php curls
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "plumvoice:passwordgoeshere");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, "http://quickfuseapps.com/api/1/outbound/queue");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

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

curl_close($ch);

?>

Note for our Intermediary Outbound Call example that we follow the same format for our Simple Outbound Call example. The required parameters still apply: app_id, tablekey, and dial_col. The only differences we've added are the result_col and start_timestamp parameters.

For result_col, we have added a “Status” column in our data table, Updatecallrow, and have designated it as the column that will store the result of each outbound call. This result will either be “success” (if the outbound call was answered by a answering machine or human) or “failure” (if the outbound call encountered a busy signal, no answer, operator, or fax)

For start_timestamp, we input the number of seconds since midnight, Jan. 1 1970, GMT marking when outbound calls from our campaign should begin. You could use this website, http://www.epochconverter.com/, to help you input the exact time of when you want your outbound calls to start.

Advanced Outbound Call Example

For our Advanced Outbound Call example, we're still using the required parameters: app_id, tablekey, and dial_col. However, we're going to use the following optional parameters: result_col, start_timestamp, last_secs, retry, retry_interval, params[], fields[], and filters.

runoutboundcall3.php:

<?php

$params = array();
$params['app_id'] = "XNpo5myMZlk";
$params['tablekey'] = "plumvoice:Updatecallrow";
$params['dial_col'] = "Phone";
$params['result_col'] = "Status";
$params['start_timestamp'] = "1280929400";
$params['last_secs'] = "1800";
$params['retry'] = "2";
$params['retry_interval'] = "120";
$params['filters[]']="Health = 'very sick'";
$params['params[]']="Name";
$params['fields[]']="Name";

// php curls
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "plumvoice:passwordgoeshere");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, "http://quickfuseapps.com/api/1/outbound/queue");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

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

curl_close($ch);

?>

By now, you're probably already familiar with the parameters mentioned in the previous examples: app_id, tablekey, dial_col, result_col, and start_timestamp. So, we'll only describe how we use the other optional parameters: last_secs, retry, retry_interval, params[], fields[], and filters[].

For last_secs, we set the amount of time, in seconds, during which calls can be made. Note that this time is based off of what is set for start_timestamp. In this case, we set it to “1800”, which is 30 minutes after the outbound call campaign begins.

For retry, we set the number of times that outbound calls can be retried if it encounters a failure (busy signal, no answer, operator, or fax). For our example, we have it set to “2”, meaning that our outbound campaign will attempt to dial the callee twice if it failed to reach a human voice or an answering machine.

For retry_interval, we set the number of seconds for our outbound campaign to retry a call if it encountered a failure (busy signal, no answer, operator, or fax). For our example, we have set it to “120”, meaning that our outbound campaign will wait 2 minutes before retrying an outbound call (if it failed).

For filters[], we have set the filtering such that our outbound campaign only selects a subset of rows from our data table, 'Updatecallrow', to make an outbound call. For 'Updatecallrow', we have added a new column, Health. For our filter, we have our campaign set to dial callees in our data table where the Health column equals “very sick”.

For params[] and fields[], we have set a parameter to “Name”, corresponding to the “Name” field in our data table. This allows us to use data from our data table right away in our application.

In our application, we have used the Reserve Variable module to reserve the variable, “Name”. From here, we use a Multipart Prompt module right at the beginning of our application, which would state the following message to the callee, “Hello, (Mary).”

This is the last section.
tutorial/outbound_apps/outboundapi.txt · Last modified: 2013/08/15 13:32 by victor