API Quick Integration Guide

Getting started with Beyond Verbal’s REST API

PURPOSE

This Quick Reference Guide is made to help you get up and running using Beyond Verbal’s Emotions Analytics REST API (API).

Using the API you will:

  1. Send the voice samples to Beyond Verbal cloud-based Emotions Analytics engine
    for analysis.
  2. Receive the analysis back from the API.

To obtain better understanding of the data received back from the API, please take a moment to browse our Analysis Result Interpretation guide.
To better understand how to create and record good-quality, emotionally effective voice inputs please refer to our Voice Input Guidelines for Analysis by Beyond Verbal REST API guide.

THE ESSENTIALS PROCESSES OF WORKING WITH OUR API

Each of the below callouts represents a separate step in the process of working with our API. These steps are described in further details – each in a separately dedicated chapter. Feel free to browse the guide in full or jump directly to the chapters that interest you the most.

img01

AUTHENTICATION

Use this request to acquire an authentication token from the API Key. This token needs to be sent with each subsequent request to the analysis server.

The Authentication Token must be sent as an Authorization field in the HTTP request header.

Authentication Request Parameters

Name Location (Body URL Header) Optional Default value Explanation
grant_type Body No client_credentials Client requests an access token.
apiKey Body No Your API key The API key you received from Beyond Verbal.
Content-Type Header No x-www-form-urlencoded Default Internet media type.

 

Example: Get token request

POST https://token.beyondverbal.com/token
Content-Type:application/x-www-form-urlencoded

grant_type=client_credentials&apikey=**********

Example: Response token

{
“access_token”:”21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8″,
“token_type”:”bearer”,
“expires_in”:172799
}

You must use the received authentication token in all subsequent requests.

Example: Using the token

POST https://apiv3.beyondverbal.com/v3/recording/start

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

This token may be reused for multiple sessions.

START

Use this request to initialize an analysis session.

Define the type of audio file you will send (wav or pcm). If the format is pcm, also provide the channels, sample rate, and bits per sample (in a wav file these parameters are read from the header).

Optionally, you can send metadata about the client, such as clientId or deviceId. See “Metadata Guide” for more details.

Example: Simple request header

{ dataFormat: { type:”WAV” } , metadata:{ ClientID:”12345” } }

Start Request

Method: POST

URL: https://apiv3.beyondverbal.com/v3/recording/start

Start Request Parameters

 

Name Location
(Body URL Header)
Optional Default value Explanation Example
dataFormat Body Yes

dataFormat: {type: “WAV”}

Information about the data stream that will
be sent to the server (using recording / call).

For file with WAV header
dataFormat:{ type:”WAV” }

For Raw PCM file
dataFormat : {
“type”: “pcm”,
“channels”: 1,
“sample_rate”: 8000,
“bits_per_sample”: 16 }

metadata Body Yes metadata: {}

Metadata information describing
user/ client/ device/ session.
For more details see “Metadata” on page 9.

metadata:

{ clientId: “someUser123@gmail.com”,
deviceId: “121332423423”, phone: “1718-555-555”
}

displayLang Body Yes displayLang: “en-us” Language used for the result.
If the requested language is not supported,
an error is returned.
Note that “en-us” is always supported.
 
Auth token Authorization Header No     Bearer XXX_TOKEN_XXX

Example: Start request (including token)

POST https://apiv3.beyondverbal.com/v3/recording/start

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

{
“dataFormat”: {“type”: “WAV”},
“metadata”: {“clientId”: “12345”}
}

Start Response

Example: OK Response (200)

{status: “success”, recordingId: “someGUID”}

The recordingId field is used to access a particular session that was created.

Example: Error Response (4xx)

{status: “failure”, reason: “This is optional text explaining the error”}

UPSTREAM

Use this request to send a voice input to the server for analysis. The response contains the analysis for the whole file.

Note: The response to this request is returned only when the whole body has been received and analyzed by the server. This may take a long time; thus to receive intermediate analysis results use the ANALYSIS request.

Upstream Request

Method: POST

URL: https://apiv3.beyondverbal.com/v3/recording/{recordingId}

Upstream Request Parameters

Name Location (Body URL Header) Optional Explanation
recordingId URL No Unique identifier of recording. Provided in the recordingId field of the START response.
Auth token Authorization Header No See “Authentication”
Sample Data Body No

Post your audio samples as the body of this HTTP message.

 Note: Http “Content-Length” header

If the length of your sample is unknown in advance (real-time streaming), use a Chunked Transfer Encoding. See (http://en.wikipedia.org/wiki/Chunked_transfer_encoding for details.

Example: Upstream request

POST https://apiv3.beyondverbal.com/v3/recording/{recordingId}

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

Upstream Response

The response is a JSON object containing an array of the analysis results for whole analysis session.

Example: OK Response (200)

{
status: “success”
recordingId: “someGUID”,
result: {
duration: 295096,
sessionStatus: “Done”,
analysisSegments: [
{
“offset”: 1586,
“duration”: 23201,
“analysis”: {…}
}
]
}
}

ANALYSIS

Use this request to fetch the analysis for a particular offset (segment) of the analysis session. You can issue this request in parallel with the UPSTREAM request in order to receive intermediate analysis.

Analysis Request

Method: GET

URL: https://apiv3.beyondverbal.com/v3/recording/{recordingId}/analysis?fromMs=n

Analysis Request Parameters

Name Location (Body URL Header) Optional Explanation
recordingId URL No Unique identifier of recording. Provided in the recordingId field of the START response.
fromMs URL Yes Filters out any analysis older than the given value.
Auth token Authorization Header No See “Authentication”

Example: Initial analysis request

This example requests an analysis from the beginning of the recording session (fromMS=0).

GET https://apiv3.beyondverbal.com/v3/recording/{recordingId}/analysis?fromMs=0

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

Analysis Response

The response is a JSON object containing an array of all the analysis segments from the fromFS, offset from the beginning of the session, until the current moment in time. This moment is the duration. The value of duration indicates the beginning of the next analysis segment.

Example: Analysis OK response (200)

{
status: “success”
recordingId: “someGUID”,
result: {
duration: 295096,
sessionStatus: “Done”,
analysisSegments: […]
}
}

Subsequent Analysis Request

In the next analysis request, increase fromMS to the next offset, that is the duration received in the response, to receive only the most recent analysis.

Example: Subsequent analysis request

This example requests an analysis from where the previous recording session finished (fromMS=295096).

GEThttps://apiv3.beyondverbal.com/v3/recording/{recordingId}/analysis?fromMs=295096

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

Continue with such requests until the session is completed (session status = done).
Note that you can request additional analysis requests for up to 24 hours after the session started. The analysis data is cached for 24 hours.