website logo
System StatusChange LogLog In / Sign Up
Reference
Tutorials
Navigate through spaces
⌘K
Overview
Transcription Features
CX AI Features
Getting Started
ElevateAI Dashboards
Submit an Interaction
Declare an Audio Interaction
Declare a Transcript
Declare a Chat Interaction
Check the Status
Check the Processing Status
Retrieve Declared Parameters
Retrieve Results
Get Phrase-by-Phrase Transcript
Get Punctuated Transcript
Get CX AI
Delete Data
.Net SDK
Python SDK
Java SDK
Docs powered by
Archbee
Submit an Interaction

Declare a Transcript

// Overview

The first step in processing any interaction is to declare the interaction.

When the POST request successfully executes, an HTTP status is returned to indicate the request was successful, along with a JSON response containing the interactionIdentifier.

Sample API Response
|
{
    "interactionIdentifier":  "46985457-fa6b-4071-a3f6-5c4858160ec9"
}


It is important you store the interactionIdentifier as it will serve as a required parameter for all other ElevateAI endpoints, enabling you to POST, GET, and/or DELETE information associated with this interaction.

If an error occurs when requesting to declare the interaction, a standard HTTP response code is retuned to indicate the request was unsuccessful, along with a JSON response containing additional details to assist in troubleshooting.

All interactions successfully declared will count towards your monthly request quota, irrespective of file upload status or processing outcome.



Only interactions successfully processed are eligible for billing. Once declared, you are able to confirm the processing status of the interaction as well as track impacts to usage and spend.



// Request Parameters & Code Examples

Details on CX AI features supported by language can be found on the overview page.

POST
Params
Header Parameters
X-API-Token
required
String
Valid API key associated with your account for authentication and usage tracking
Content-Type
required
String
Will be 'application/JSON'
Body Parameters
type
required
String
Type of interaction to be processed, will be "transcript"
languageTag
required
String
Primary language of transcript, will be "en-us" (for North American English), "en" (for International English), or "es-419" (for North American Spanish)
vertical
required
String
Vertical associated with interaction, will be "default"
transcript
required
Object
transcript text to be analyzed (see below)
Curl
Node.js
JS
Python
|
curl --location --request POST 'https://api.elevateai.com/v1/interactions' \
--header 'Content-Type: application/json' \
--header 'X-API-Token: {Your API Token}' \
--data-raw '{
    "type": "transcript",
    "languageTag": "en-us",
    "vertical": "default",
    "transcript": {
        "allParticipants": {
            "phrases": [
                "{word A}",
                "{word B}"
            ],
            "phraseSegments": [
                {
                    "startTimeOffset": {startA},
                    "endTimeOffset": {endA},
                    "phraseIndex": 0,
                    "score": 1
                },
                {
                    "startTimeOffset": {startB},
                    "endTimeOffset": {endB},
                    "phraseIndex": 1,
                    "score": 1
                }
            ]
        },
        "participantOne": {
            "phrases": [
                "{word A}"
            ],
            "phraseSegments": [
                {
                    "startTimeOffset": {startA},
                    "endTimeOffset": {endA},
                    "phraseIndex": 0,
                    "score": 1
                }
            ]
        },
        "participantTwo": {
            "phrases": [
                "{word B}"
            ],
            "phraseSegments": [
                {
                    "startTimeOffset": {startB},
                    "endTimeOffset": {endB},
                    "phraseIndex": 0,
                    "score": 1
                }
            ]
        }
    }
}'
RESPONSES
201
400
401
429
|
{
    "interactionIdentifier":  "string"
}



// Formatting a Transcript for Processing

Transcript files will be formatted according to the schema below, and included as a body parameter when declaring the transcript for processing.

Sample Transcription Format

Sample Transcription Format
|
{
    "allParticipants": {
        "phrases": [
            "I", "Hope", "This", "Documentation", "Was", "Useful", "Thank", "You",
            ...
        ]
        "phraseSegments": [
            {
                "startTimeOffset": 870,
                "endTimeOffset": 1330,
                "phraseIndex" 0,
                "score": 1
            }
            ...
        ]
    },
    "participantOne": {
        "phrases": [
            "I","Hope","This","Documentation","Was","Useful",
            ...
        ]
        ...
    },
    ...
}


Schema

Element

Type

Description

{participant}

object

Top level for speaker label, will be "allParticipants", or "participantOne", or "participantTwo"

{participant}/phrases

array of strings

Ordered list of each unique phase spoken by {participant} in the interaction

{participant}/phraseSegments

array of objects

List of details associated with each phrase in transcript for the {participant}

{participant}/phraseSegments/startTimeOffset

number

Start time of phrase (in milliseconds)

{participant}/phraseSegments/endTimeOffset

number

End time of phrase (in milliseconds)

{participant}/phraseSegments/phraseIndex

number

Index of phrase in {participant}/phrases

{participant}/phraseSegments/score

float

Confidence score, if not available should be 1

Pro tip: allParticpants is a required object when providing a transcript for analysis. While participantOne and participantTwo objects are not required, they are highly recommended.



PREVIOUS
Upload an Audio File
NEXT
Declare a Chat Interaction
Docs powered by
Archbee
Declare an Interaction for Processing (Transcript)
TABLE OF CONTENTS
// Overview
// Request Parameters & Code Examples
POST
Declare an Interaction for Processing (Transcript)
// Formatting a Transcript for Processing
Sample Transcription Format
Schema
Docs powered by
Archbee