Select Page

Getting Started with Voxjar’s API

Table of Contents

 

This guide is intended to get you from 0 to uploading calls as quickly as possible.

This is not Voxjar’s API Documentation or intended to be your only API resource. For full Voxjar API Documentation and a web-based query environment go to api.voxjar.com/graphql

About Voxjar’s API

API Tokens

Python Client Library

     -Installation

     -Authentication

     -Metadata

     -Uploading Call Recordings

     -GraphQL

 

About Our API

 

Voxjar maintains an open GraphQL API along with a Python Client Library for uploading, transcribing, analyzing, and interacting with phone call recordings and call metadata. 

To learn more about GraphQL visit How to GraphQL or GraphQL.org

A web interface is available at api.voxjar.com/graphql where you can test queries and mutations, access our full API documentation, generate curl commands, and generally become familiar with our API.

We also provide a Python Client Library for simplified call recording and metadata uploading.The Python library will be the main focus of this guide due to the simplicity of implementation.

Although the Python library does expose a GraphQL library that you can use for executing Queries and Mutations found in our API documentation this guide will only briefly touch on it here.

API Tokens

 

Voxjar’s API authenticates with a system-generated API Token as a JWT.

Long-lived tokens (1 year) are generated in Voxjar’s web app on the settings/developers page. You cannot recover or disable a lost API token. Each new token that you generate will have a new expiration date.

(Tokens should be kept secret and safe. Ain’t nobody got time for a data breach.)

If you can’t view the developers page you might not have permission to do so. Talk with your administrator or reach out to Voxjar’s support team for help.

Generating a Long-Lived API Token

 

 

 

 

Short-lived tokens (generally a few hours) can be generated in Voxjar’s API Playground with the login mutation for testing purposes.
These tokens should NOT be used in production.

Generating a Short-Lived API Token for Testing

 

 

With your Token generated you can now authenticate API requests.

Python Client Library

 

Voxjar provides a Python library to simplify uploading calls and metadata. Documentation can be found here. The rest of this guide will walk you through implementation in detail.

Installation

 

$ pip3 install voxjar

 

Authentication

 

The Client() class needs a URL and a Token. We suggest using a JSON keyfile in production as seen in our docs.
For testing, you can hardcode the values as seen in the example below.

You can test against our dev server before moving to production with the URLs below.

URLs
Production: https://api.voxjar.com:9000
Development: https://api.voxjar.com:9001

Token
Use your system generated API token


import voxjar


client = voxjar.Client(url="https://api.voxjar.com:9000", token="MY_API_TOKEN")


Metadata

 

Next, you’ll need to create a metadata dictionary. This dictionary should be dynamically populated for each individual call recording.

The following example shows a completed metadata object with placeholder values. Many fields are not required, but we suggest populating as many fields as you can to create a rich dataset.

Required Fields

identifier string unique call id

type dictionary e.g sales, support, brand, etc.

identifierstringunique id for call type

namestringhuman readable call type name

timestamp datetime when the call took place

direction enumcall direction OUTGOING/INCOMING

agents list of dictionaries

identifierstring unique agent id

namestringthe agent’s name

customers list of dictionaries

identifierstring unique customer id

namestringcustomer’s name

Optional Fields

agents list of dictionaries

phoneNumberstringagent’s phone number/extension

metadata dictionaryset your own key value pairs to associate with this agent

customers list of dictionaries

phoneNumberstringcustomer’s phone number

metadata dictionaryset your own key value pairs to associate with this customer

disposition dictionary e.g. update billing, dropped call, deal won, etc.

identifierstringunique id for disposition

namestringhuman readable disposition name

tags list

metadata dictionary set your own key value pairs to associate with this call

Common Mistakes:

  • Copying the example code from the docs without replacing the Placeholder values. When every type.name comes across as “typeName” you’ve made the same mistake.
  • Again, forgetting to replace the Placeholder value for timestamp. Be sure to use the datetime that the call took place.
  • Using non-unique identifiers, especially for agents. This usually comes in the form of using phone extensions or phone numbers instead of an employee id or email address.
  • Locking yourself into the pre-defined metadata fields. We added the custommetadata fields so you can add any additional data to your calls, agents, or customers for a richer experience. All metadata fields become filters in the Voxjar webapp.
import datetime
import voxjar

metadata = {
    'identifier': 'callIdentifier',
    'type': {
        'identifier': 'typeIdentifier',
        'name': 'typeName',
    },
    'timestamp': datetime.datetime.now(),
    'direction': 'OUTGOING',  # or INCOMING
    'agents': [{
        'identifier': 'agentIdentifier',
        'name': 'Agent Name',
# optional 'phoneNumber': 1234567890, # optional 'metadata': { 'someCustomField': 'someCustomValue', }, }], 'customers': [{ 'identifier': 'customerIdentifier', 'name': 'Customer Name',
# optional 'phoneNumber': 9876543210, # optional 'metadata': { 'someCustomField': 'someCustomValue', }, }], # optional 'disposition': { 'identifier': 'dispositionIdentifier', 'name': 'dispositionName', }, # optional 'tags': ['tag1', 'tag2'], # optional 'metadata': { 'someCustomField': 'someCustomValue', }, }

Uploading

 

There two ways to upload call recordings and metadata with the library. Both require that the call recording as well as a complete metadata dictionary be uploaded together.

The first method is used when you have the recording files stored locally and the other is when you pull the recordings from a URL.

Local files

import voxjar


client = voxjar.Client()

with open('test.wav', 'rb') as f:
    client.push(metadata, f)

File like objects (URL)

import voxjar


client = voxjar.Client()

r = requests.get('https://somesource.com', stream=True)
with client.push_request(metadata) as push_request:
    for chunk in r.iter_content(chunk_size=1024):
        push_request.write(chunk)
    push_request.push()

GraphQL

 

It is also possible to execute GraphQL queries and mutations with Voxjar’s Python library. You can explore our API and test your queries/mutations in our playground first and then copy them into your script. 

To learn about GraphQL in detail visit How to GraphQL or GraphQL.org.

Check out the syntax below, then go build something cool!

import voxjar


client = voxjar.Client()


def get_hours(**kwargs):
    document = """{
          aggregate(sum:"duration"){
            sum
          }
        }"""
    response = client.execute(document, variable_values=kwargs)
    return response.get('aggregate', {}).get('sum')

get_hours()