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"
} 
{
    "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
Request
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
                }
            ]
        }
    }
}'
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"
} 
{
    "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
{
    "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",
            ...
        ]
        ...
    },
    ...
}
{
    "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",
            ...
        ]
        ...
    },
    ...
}
﻿
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.
﻿

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

Upload an Audio File

Declare a Chat Interaction

Declare a Transcript

﻿// Overview

﻿// Request Parameters & Code Examples

﻿// Formatting a Transcript for Processing

Sample Transcription Format

Schema

// Overview

// Request Parameters & Code Examples

// Formatting a Transcript for Processing