Postback Guide

When developing an application with CallFire APIs, not only will you command CallFire to set up campaigns and send phone calls, your application will probably also need to get information about those campaigns and phone calls. Although there is a way to get data from CallFire with a pull strategy, the more elegant way to integrate your application with CallFire is to use a push strategy: expose part of your application to the Internet and register its URL with your CallFire account. This will help conserve resources and keep your application up to date with real-time data.

Assumptions

Registering a URL for notifications can be done programmatically with our APIs. However, before we begin with this example, you will need a couple of things:

1. A CallFire API login and password. If you don't have an API login, click here.
2. A website that can host PHP files.

First, let's write a program to register a URL for postbacks from CallFire:

<?php
$wsdl = "https://callfire.com/api/1.0/wsdl/callfire-service-http-soap12.wsdl";

/*
 * You'll need your login/password pair when you create the SOAP
 * client. Don't use this one; it's just for show and won't work.
 */
$client = new SoapClient($wsdl, array(
    'login'        => '72f42300c1a1',    
    'password'     => '44261a4592146a63',
    'soap_version' => 'SOAP_1_2'));

/*
 * You will need to provide a URL that you control to handle
 * the HTTP requests coming from CallFire.com.
 */
$endpoint = 'http://www.yourwebsite.com/somephpfile.php';

$subscriptionRequest = array('Subscription' => array(
    'Endpoint' => $endpoint,
    'NotificationFormat' => 'XML'
));

$response = $client->createSubscription($subscriptionRequest);

echo "Response: $response\n";

?>

If you run this program, CallFire will respond with the ID assigned to the newly created subscription. The URL that we just registered should start receiving HTTP posts from CallFire.com. These include various events that happen in your account, such as when calls finish.

Here’s an example of a postback that was generated when I received an incoming SMS on one of my phone numbers that I own through CallFire:

//Example from incoming SMS
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<n:TextNotification xmlns="http://api.callfire.com/data" xmlns:n="http://api.callfire.com/notification/xsd">
    <n:SubscriptionId>19001</n:SubscriptionId>
    <Text id="5707328001">
        <FromNumber>18185551212</FromNumber>
        <ToNumber>18186469991</ToNumber>
        <State>FINISHED</State>
        <ContactId>1418291001</ContactId>
        <Inbound>true</Inbound>
        <Created>2012-09-24T05:02:35Z</Created>
        <Modified>2012-09-24T05:02:35Z</Modified
        <FinalResult>RECEIVED</FinalResult>
        <Message>Hello, World!</Message>
        <TextRecord id="3526268001">
            <Result>RECEIVED</Result>
            <FinishTime>2012-09-24T05:02:35Z</FinishTime>
            <BilledAmount>0.03</BilledAmount>
            <Message>Hello, World!</Message>
        </TextRecord>
    </Text>
</n:TextNotification>

As you can see, the postback contains a lot of useful information, including the number from which the SMS came, the CallFire number which received the SMS, the time the message was received, billing information, and the text within the SMS. This information will allow us to write applications that can react in nontrivial ways to events in CallFire.

I want to receive all the SMS that come to my CallFire numbers as emails, so that I can read them on my desktop computer as they come in. Converting the SMS postbacks to emails can be done with just a few lines of code in PHP:

<?php
// This code will reside at the endpoint we defined earlier ...
// http://www.yourwebsite.com/somephpfile.php

$xml = simplexml_load_string($HTTP_RAW_POST_DATA);
$text = $xml->Text or die('No text');
$inbound = $text->Inbound == 'true' or die('Not inbound');
$fromNumber = (string)$text->FromNumber;
$toNumber   = (string)$text->ToNumber;
$time       = (string)$text->Created;
$message    = (string)$text->Message;

$emailSubject = "$toNumber received a new SMS from $fromNumber";
$emailMessage = "From: $fromNumber\n".
                "  To: $toNumber\n".
                "Time: $time\n".
                "Text: $message";

mail('whatsyourname@yourwebsite.com', $emailSubject, $emailMessage);

?>

Finally, if we are changing our application or putting it permanently to bed, we can always cancel our subscriptions to postbacks. These next few lines demonstrate two things:

1. Querying CallFire for our account's postbacks
2. Deleting them one by one

// Let's assume we have $client defined from the first example:
$response = $client->querySubscriptions();
$subscriptions = is_array($response->Subscription) ?
                          $response->Subscription :
                          array($response->Subscription);

foreach($subscriptions as $sub) {
    $id = $sub->id;
    $deleteRequest = array('Id' => $id);
    echo "Deleting $id...\n";
    $response = $client->deleteSubscription($deleteRequest);
}