Submit an Interaction

Declare an Audio Interaction

// 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


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 can confirm the processing status of the interaction as well as track impacts to usage and spend.

Echo

Introducing Echo, our most accurate transcription model ever!

Echo delivers a significant leap in accuracy, outperforming our previous CX-focused model by 40%, ensuring superior transcription quality across every use case.

To take advantage of the Echo model, add the body parameter "model" to your POST declare and set the value to "echo".

NOTE: Currently the Echo model does not diarize between speakers, perform redaction or process for CX-AI. Future releases will move Echo towards feature parity with the CX model.



// Request Parameters & Code Examples

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 "audio"
languageTag
optional
String
Specifies the language to use when processing the audio. NOTE: For the Echo model, use "auto" to automatically determine the language (over 50 supported). For the CX model, the options are: "en-us" (for North American English), "en" (for International English), "es-419" (for North American Spanish), "pt-br" for Brazilian Portuguese or "ja" for Japanese. Omitting this parameter will default to "auto" for model echo and "en-us" for model cx.
vertical
optional
String
Vertical associated with interaction, will be "default"
model
optional
String
Defines the transcription model to be used. Available options are "cx" and "echo". Default is "cx".
audioTranscriptionMode
optional
String
NOTE: Effective v1.11 on February 29, 2024 all declared interactions will be processed with "highAccuracy". This previously required parameter has been depricated and is no longer required and any value will be ignored.
originalFileName
optional
String
The filename of the original file for this interaction
externalIdentifier
optional
String
Any external identifier that the user would like associated with this interaction
downloadUri
optional
String
The URL of your audio file Important: Do not include the downloadUri parameter if you wish to upload a local audio file; an empty string will cause the download to fail
includeAiResults
optional
Boolean
NOTE: Effective v1.11 on February 29, 2024 all declared interactions will be processed with includeAiResults set to 'true'.
metadata
optional
String
JSON payload containing the metadata for this audio file. Must only be used if the account has Explore enabled. If not, specifying this element will cause a response of 400 Bad Request.
Curl
Node.js
JS
Python
Ruby
C#
PHP
Responses
201
400
401
429


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



// Submitting an Audio File for Processing

Download URL

Providing access to audio files via the downloadUri parameter is highly recommended for fastest processing times.

We take data security seriously, and know you do to! If required, we are able to provide an IP address to support IP whitelisting or assist in setting up a private, secure SFTP to support transferring via SFTP with URL format. If you have any questions on how to transfer your audio, reach out at any time to [email protected] - we're here to help

Local File

If the downloadUri parameter is not included when declaring the interaction, the audio should be uploaded to the API directly for processing.

// Submitting metadata

Metadata must only be submitted with an API-Token for an account which has Explore enabled. Use under other circumstances will cause the Declare to fail, and a response of 400 Bad Request.

For details on the types and formatting of metadata, please see Metadata.