Save call logs to external datasource

In this tutorial, we will go over how to save your call logs into an external datasource in order to gain understanding of your data. There are many places in which call logs can be saved(google sheets, excel and so on). For this example, we'll save our call logs into a JSON list, which can be used as a datasource for Tableau.

Prerequisites

Before you can get started, you will need to have a Vonage Developer account. If you do not have a Vonage Developer account, please use this guide to setup and create your account.

After you have an account, you will need to do the following using these guides:

For this example, you will need to Subscribe to the Reports API.

Authentication

After creating an application and subscribing to the Reports API, you will now need to log-in using your Vonage Business Communications credentials. Check out the Making an API Request guide for more details.

Next, we'll create a function that requests the /token API to generate an access token.

def get_token():
  url = "https://api.vonage.com/token"
  payload = 'grant_type=password&username={}&password={}&client_id={}&client_secret={}'.format(USERNAME, PASSWORD, CLIENT_ID, SECRET)
  headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
  }

  response = requests.request("POST", url, headers=headers, data = payload)
  return response.json()

To run this function, you will need to pass in the following:

  • USERNAME - Vonage Business Communications username. Be sure to append @vbc.prod to the username. firstname.lastname@vbc.prod.
  • PASSWORD - Vonage Business Communications password.
  • CLIENT_ID - The client id of your Vonage Developer application.
  • SECRET - The secret to your Vonage Developer application.

After running this function, you should see the following response:

{
  "access_token": "abc123-xxxxx-xxxxx",
  "expires_in": 9999,
  "refresh_token": "def456-xxxx-xxxx",
  "scope": "default",
  "token_type": "Bearer"
}

Call Logs API

The next step is to pull the list of calls from the call logs api. We can use this function to return a list of calls by a start date and end date. If there are more results than the number of items we have requested using the page_size parameter, this function will retrieve those other pages as well.

results = []
def get_reports(token, account_id, start_date, end_date, order="asc", page_size=10, page=1):
  url = "https://api.vonage.com/t/vbc.prod/reports/v1/accounts/{}/call-logs?start:gte={}&start:lte={}&page_size={}&page={}&order={}".format(account_id, start_date, end_date, page_size, page, order)
  headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer {}'.format(token),
  }

  response = requests.request("GET", url, headers=headers).json()
  if "_embedded" in response:
    results.extend(response["_embedded"]["call_logs"])

  if page < response["total_page"]:
    page = page + 1
    get_reports(token, account_id, start_date, end_date, page_size=page_size, page=page)

  return results

Next, we'll need to create a start and end date to pass into the function. The state date will be 1 day in the past and the end date will be 1 minute before midnight on the current day.

import datetime
from datetime import timedelta
today = datetime.datetime.now()
today_str = today.strftime('%Y-%m-%d 00:00:00')

yesterday = today - timedelta(days = 1)
yesterday_str = yesterday.strftime('%Y-%m-%d 23:59:59')

access_token = get_token()["access_token"]
reports = get_reports(access_token,account_id={YOUR_ACCOUNT_ID}, start_date=today_str, end_date=yesterday_str)

We then call the get_reports() function to return a list of calls between those 2 dates. Next, we'll then need to create a JSON file that contains a list of these logs.

import json

def write_json(data, filename='data.json'):
    with open(filename,'w') as f:
        return json.dump(data, f)

def read_json(filename='data.json'):
  try:
    with open(filename) as json_file:
      return  json.load(json_file)
  except IOError:
    return []

data = read_json()
data.extend(reports)
write_json(data)

Here, we create 2 functions to read and write to a JSON file. We then read our JSON file. If the file does not exist, we return a empty list([]). Next, we need to add our calls logs into the JSON file using the extend() function. Finally, we need to load this list back into the JSON file. For every day that we run this function, we will append the latest call logs in the JSON file.

CRON Job

The final step is to run our script every day using a CRON job. This way, we will not have to run these functions manually. A CRON is way to run scripts periodically at fixed times, dates, or intervals. You can create a CRON job locally by first running crontab -e on a OSX/Linux based system.

For a Windows machine:

  • Log on with a privileged account, e.g. Administrator
  • Go to Start > Control Panel > System and Security > Administrative Tools > Task Scheduler
  • In the right panel click on Create Basic Task

Our CRON job will look like this:

* 0 * * * get_call_logs.py >/dev/null 2>&1

This will run everyday at midnight. To create your own CRON job, check out https://crontab-generator.org/

Import into Tableau

For this example, we will be using Tableau to generate a dashboard from our call log data. It will look something like this:

First, in Tableau, click Connect To Data and under To a file, click JSON file

Next, locate the JSON file that contains the calls logs. You can optionally select a few columns. Then navigate to Sheet 1 to view your data.

Next, go to Sheet 1 and in the Folders section, right click on the End parameter and set Change Data Type to Date.

Then, drag the End parameter to the Columns section. Next, right click on the End parameter and change to Day. Then, drag the Count parameter under the Measured Names section to the row section. You should then see a line chart for the number of calls by day.

As our CRON job runs everyday, our Tableau dashboard will update itself with the new call logs. Dont forget to save the JSON in the same location as where you originally added the datasource for Tableau

Conclusion

In this example, we have seen how to create a function that returns a list of calls logs for a given day. Pushing this data is a dashboard like Tableu will be able to help your team analyze your call traffic. Our dashboard only shows the number of calls every day, but you can customize it to shown number of inbound / outbound calls, average cost per day, average length of calls, and much more.