Getting started

What you'll be learning here: How to retrieve Calls data from the API and save it in a file to share with your colleagues for example.

Overview

This guide describes how to consume our HTTP Activate API by sending it a request and receiving Call data in the response. It also presents you the basic concepts to have in mind when using this API. Once you cover this documentation page, you will know how to:

  • authenticate to our servers
  • request for data using pagination
  • explore with some of the data you'll get in the response's payload

Get your API token

You have to already be a customer of Allo-Media in order to be able to get data from this API. If so, please see with your account manager to get an API token. You will then be able to pass this value in the Authorization header of each request.

Install an SDK

Unfortunately, we don't have any SDK to share with you yet. We are going to use Python for the examples.

What are you building here

This Getting Started guides you to build a very simple app that retrieves Call data from the API, and saves some of the payload in a CSV file. For the sake of the exercise, we'll store in the CSV the unique identifier of the Call, a link to Scribr, our data exploration website, and the first 50 words a consumer has said during the Call.

Of course the way this code is implemented might be further optimized or more zen, especially with less loops.

But for the sake and clarity of the exercise, which is to consume the API and not to learn Python, we won't bother about this matter right now.

You can download the Python script we're going to build here.

Connect to the server

First things first, you need to initiate a connection to our servers. Our API URL is: https://api.allo-media.net

Make sure you have a valid token, otherwise you'll receive an error. We recommend you pass tokens in as environment variables, or persist them in a database that is accessed at runtime. You can add a token to the environment by starting your app as:

ACTIVATE_API_TOKEN="some-token" ACTIVATE_API_URL="https://api.allo-media.net" python myapp.py

Here is in Python how we'll prepare the URL and header for our next to come requests:

#!/bin/env python3
import os

activate_token = os.getenv('ACTIVATE_API_TOKEN')
activate_url = os.getenv('ACTIVATE_API_URL')
headers = {"Authorization": f"Token {activate_token}"}

Retrieve 3 pages of data

Data is paginated in the Activate API. You will see that a single Call can expose a lot of data, especially with a long transcript. In order to prevent response timeout, we've limited the maximum number of Calls to be returned per response to 200. You can specify another value using limit query parameter, and define the page you want by using offset.

Let's continue our script and retrieve 3 pages of 20 Calls each.

Let's update our import with requests.

import requests

Now we append the code:

LIMIT = 20
offset = 0

call_list = []
while offset < 3 * LIMIT:
r = requests.get(f"{activate_url}/calls?limit={LIMIT}&offset={offset}", headers=headers)
r.raise_for_status()
data = r.json()
call_list += data["data"]
offset += LIMIT

Transform the data and save it in a file

We have our raw data. Let's dig into what we have at hand in order to create this CSV file.

As our API reference describes, one Call object exposes a bunch of data.
Here we'll focus on two fields:

  • unique_id, which is you guessed it a unique identifier for the Call in our system
  • transcript_json which contains a lot of data regarding the transcription

Within transcript_json, the callData lists each and every segment of the conversation. A segment is an utterance of a given speaker, or a sentence if such concept may apply to spoken language. For our example, we want to retrieve segments of the customer. We can filter her segments thanks to the from key, by spotting the value in (out being the brand's agent she was calling).

output = []
for call in call_list:
transcript = call["transcript_json"].get("callData", [])
words = []
for segment in transcript:
if segment["from"] == "in":
words += [word["value"] for word in segment["words"]]

output.append({
'unique_id': call['unique_id'],
'url': f"https://scribr.allo-media.net/#/call/{call['unique_id']}",
'50words': " ".join(words[:50])
})

Only thing left is to save the output in a CSV file. Let's update our import:

import csv

And save our data by appending th code:

with open("client_first_words.csv", "w") as csvfile:
writer = csv.DictWriter(csvfile, fieldnames=['unique_id', 'url', '50words'])
writer.writeheader()
writer.writerows(output)

There you go! You are now able to retrieve data from the Activate API, handle its pagination, and you've started to explore the data at hand.

To dive in deeper, you can browse the API Reference documentation.

If you are stuck, want to suggest something, or just want to say hello, send us an e-mail to support@allo-media.fr.