Making your Plivo Call Recordings Searchable

This was originally published on the Clarify blog on 01 July 2014.

“This call may be recorded for quality assurance.”

You’ve heard it a thousand times but how often is it true? How often does a company record those calls? More importantly, what do they do with those recordings after the fact?

The truth is that the vast majority of organizations spot check calls flagged as problematic and that’s it. They don’t do anything with the rest of the calls or really have any insight into the content of any of them. The recordings sit on a server somewhere taking up space and not being useful. Fortunately, some organizations are investing in making these calls searchable, collecting common words, and trying to identify common threads of problems earlier.

So how can you accomplish the same at a fraction of the cost and time?

The easiest way is to integrate your call recording system directly with Clarify. In fact, if you use a system like Plivo – which has Recording Callbacks – you can make the indexing near-realtime with almost no effort.

Install the Clarify library

Our first step is getting the helper library for Clarify. Luckily, through the power that is Composer, we can do that with a simple configuration file and single command. Here’s our composer.json:

{
    "require": {
        "clarify/clarify-helper": "~1.2.1"
    }
}

composer.json

and then we run composer install which will configure our library automatically.

Next, we need to accept the incoming phone call and record it. This can be accomplished with a trivial amount of Plivo XML to greet the caller and record:

<Response>
    <Speak>Hello. This call will be recorded for quality assurance.</Speak>
    <Record action="http://www.example.com/store-in-clarify.php" maxLength="60" finishOnKey="*" />
    <Speak>Recording not received</Speak>
</Response>

record.xml

Using the Recording Webhook

The key aspect of that snippet is the action attribute on the Record XML. Once the recording is completed, Plivo will make an HTTP POST to the file specified in it. The POST will include a few pieces of information – such as the start and end times of the call – along with the RecordUrl of the file itself. That gives us the next step: audio indexing.

<?php

include 'vendor/autoload.php';

$apiKey = 'update with your api key';

$recording_url = $_POST['RecordUrl'];

$recording_start = (int) $_POST['RecordingStartMs'];
$recording_end = (int) $_POST['RecordingEndMs'];

$jsonData = '{"started": "'.date('Y-m-d H:i:s', $recording_start).'", "ended": "'.date('Y-m-d H:i:s', $recording_end).'"}';

$bundle = new Clarify\Bundle($apiKey);
$bundle->create('phone recording', $recording_url, $jsonData, '', '');

store-in-clarify.php

In this case, we’ll collect those three parameters – RecordingStartMs, RecordingEndMs, RecordUrl – and pass them into Clarify. The RecordUrl takes the place of our media url and is parsed accordingly. On the other hand, we use the RecordingStartMs and RecordingEndMs information in our metadata field. As Ivo talked about in “Searching Audio and Video Metadata [Clarify blog post on metadata search]” previous, we can use this information to do advanced searches and even filtering. It will allow us to build a query that says “show me every call that occurred between Date A and Date B.” If we wanted, we could query a CRM and add even more information to our metadata fields.. but that’s beyond the scope of this post.

Embedding the Clarify Audio Player

From here, we our stock audio player from Github and plug in our PHP helper library and our API key and in minutes we have a player that looks like the screencap below:

How many phone calls does your company make? How many of them are recorded and collect digital dust? We hope to change that and let you open that information to drive new and useful insights and features for your organization. You can explore and continue this project from the Plivo/Clarify project on Github.

If you’d like to get in touch, don’t hesitate: keith@clarify.io or @CaseySoftware on Twitter.