Build the future of communications.
Start building for free

Manage Your Call Recordings with the REST API

Under the hood of the REST API

Credit: http://www.flickr.com/photos/usnavy/

When we talk about our API, sometimes we use the term “REST” without describing what it actually means. When we look under the hood, we find a lots of moving pieces that fit together to make everything work as described.

Realistically, to people who just use Twilio on a day to day basis, those details are not important. The key part developers should understand is “nouns and verbs.”

Four HTTP Verbs Drive REST APIs

The four HTTP verbs that drive REST APIs are POST, GET, PUT, and DELETE. The POST and GET verbs and are well-understood by modern web developers because we use them to create and retrieve our nouns. Less common but just as important is PUT. Ideally, we use it to update our nouns. The fourth verb – DELETE – will delete our noun but is rarely used. Within the Twilio API, we use DELETE in one place: call recordings.

Depending on how you use Twilio, you could easily collect call recordings which you don’t want to store long term. You could delete these via the Dashboard on the site but programmatically using the REST API is more powerful and flexible. It’s even easy if you use our Helper Libraries.

Warning: If you just copy and paste the following code, it will delete all the Recordings within the specified date ranges. Please customize this code before you use it.

In PHP, it’s as simple as authenticating with our Account Sid and AuthToken and then calling the delete method on each Recording. In this sample, I get a specific date range of 50 recordings, display some information, and delete them one by one using their Recording Sid:

<?php
// Get the PHP helper library from https://twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php';
use Twilio\Rest\Client;
// Your Account Sid and Auth Token from twilio.com/console
$sid    = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token  = "your_auth_token";
$twilio = new Client($sid, $token);
$recordings = $twilio->recordings
                     ->read(array(
                                'callSid' => "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                                'dateCreatedBefore' => '2011-08-01'
                                'dateCreatedAfter' => '2011-07-05 08:00:00'
                            ), 50);
foreach ($recordings as $record) {
    echo "Deleting: " . $recording->sid . " -- " . $recording->date_created . "\n";
    $client->recordings($recording->sid)->delete();
}

Not surprisingly, the equivalent using our Python module is quite similar:

from datetime import date
from twilio.rest import Client

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = Client(account_sid, auth_token)

recordings = client.recordings.list(date_created_after=date(2012, 1, 1))

for recording in recordings:
    print("Deleting: " + recording.sid)
    recording.delete()

Of course, you can still go with raw cURL from the command line:

curl -X DELETE 'https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Recordings/RExxxx.json' \
  -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

* For an updated source of code snippets, please check the official documentation.

Delete Specific Call Recordings

Realistically, we probably don’t want to blindly delete Recordings by date range. We could have important customer calls, voice mail greetings, or other important Recordings. To ensure that the delete focuses exactly on the Recordings we want, we’ll combine a few pieces to make something more useful. In this particular case, first we get a list of Calls filtered by the To phone number and the StartTime. Next, we only delete the call recordings if they are less than 20 seconds. In my account, this To number is used exclusively for testing and development of voice apps, so deleting the shortest call recordings makes sense:

<?php
// Get the PHP helper library from https://twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php';
use Twilio\Rest\Client;
// Your Account Sid and Auth Token from twilio.com/console
$sid    = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token  = "your_auth_token";
$toNumber = "{fill this in with your number}";
$twilio = new Client($sid, $token);
$calls = $client->calls->read(
    array("to" => $toNumber, "startTimeBefore" => "2011-11-10")
);
foreach ($calls as $call) {
    if ($call->duration < 20) {
        echo "Call: " . $call->sid . " -- " . $call->start_time . "\n";
        $recordings = $call->recordings;
        foreach($recordings as $recording) {
            echo "Deleting: " . $recording->sid . "\n";
            $client->recordings($recording->sid)->delete();
        }
    }
}

In general, keeping your account “clean” is useful. While everything else within the REST API is text, Recordings are files and large by comparison. If you regularly delete the unimportant files, your processing will be easier and faster.

Authors
Sign up and start building
Not ready yet? Talk to an expert.