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
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 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()
