--- title: Declare an Audio Interaction slug: tutorials/declare-an-audio-interaction description: Learn how to declare an interaction in ElevateAI with this comprehensive document. Discover the process, including the successful execution of a POST request and the retrieval of an interactionIdentifier. Troubleshoot potential errors by understanding the docTags: createdAt: 2022-06-14T17:24:57.000Z --- # // Overview The first step in processing any audio file 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`**. :::CodeblockTabs Sample API Response ```json { "interactionIdentifier": "2ebaffd6-7a4b-4bcf-a169-678af0705779" } ``` ::: **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, as well as a **`JSON`** response containing additional details to [assist with troubleshooting](https://docs.elevateai.com/#Qofti). :::hint{type="info"} All interactions** successfully declared** will count towards your [monthly request quota](https://docs.elevateai.com/#iwwlY), regardless of file upload status or processing outcome. Only interactions **successfully processed** are eligible for billing. **-->** Once declared, you can confirm the [processing status](docId\:dg0fHnxsBeEqTYD1ruQrQ) of your interaction, as well as tracking impacts to both [usage](https://docs.elevateai.com/tutorials/elevateai-dashboards#h1qyd) and [spend](https://docs.elevateai.com/tutorials/elevateai-dashboards#jYsvI). ::: :::hint{type="info"} ### Meet Echo Introducing** ElevateAI Echo**, our most accurate transcription model yet! Echo delivers a **significant leap in accuracy**, outperforming our previous, CX-focused model by 40% and ensuring **superior transcription quality** across every use case. **-->** To use 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* perform redaction**. Future releases will continue to move Echo towards feature parity with ElevateAI's CX transcription model. - Access feature updates via our [Release Notes](https://docs.elevateai.com/changelog) - Contact the [ElevateAI Team](https://docs.elevateai.com/#4zATw) with product or roadmap questions ::: *** # // Request Parameters & Code Examples Details on language support for CX AI features can be found on the [CX AI Features Overview](docId\:ZATcqMNsVApZs9WWKgeCn) page. :::ApiMethodV2 ```json { "tab": "examples", "url": "https://api.elevateai.com/v1/interactions", "name": "Declare an Interaction for Processing (Audio)", "method": "POST", "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "kind": "required", "name": "X-API-Token", "type": "string", "description": "Valid API key associated with your account for authentication and usage tracking" }, { "kind": "required", "name": "Content-Type", "type": "string", "description": "Will be 'application/JSON'" } ], "bodyDataParameters": [ { "kind": "required", "name": "type", "type": "string", "description": "Type of interaction to be processed, will be \"audio\"", "": "Type of interaction to be processed, will be \"audio\"" }, { "kind": "optional", "name": "languageTag", "type": "string", "description": "Specifies the language to use when processing the audio. \nNOTE: For the Echo model, use \"auto\" to automatically determine the language (over 50 supported). \n\nFor the CX model, the options are:\n\nen-us for North American English\nen for International English \nes-419 for North American Spanish\npt-br for Brazilian Portuguese\nja for Japanese\n\nNOTE: Omitting this parameter will default to \"auto\" for model echo and \"en-us\" for model cx.", "": "Specifies the language to use when processing the audio. \nNOTE: For the Echo model, use \"auto\" to automatically determine the language (over 50 supported). \n\nFor the CX model, the options are:\n\nen-us for North American English\nen for International English \nes-419 for North American Spanish\npt-br for Brazilian Portuguese\nja for Japanese\n\nNOTE: Omitting this parameter will default to \"auto\" for model echo and \"en-us\" for model cx." }, { "kind": "optional", "name": "vertical", "type": "string", "description": "Vertical associated with interaction, will be\n\"default\"" }, { "name": "model", "kind": "optional", "type": "string", "description": "Defines the transcription model to be used. Available options are \"cx\" and \"echo\". Default is \"cx\".", "children": [] }, { "kind": "optional", "name": "audioTranscriptionMode", "type": "string", "description": "Effective February 29. 2024 with the v1.11 release, all declared interactions will be processed with \"highAccuracy\" \n\nNOTE: This previously required parameter has been depricated and is no longer required. Any value will be ignored.", "": "Effective February 29. 2024 with the v1.11 release, all declared interactions will be processed with \"highAccuracy\" \n\nNOTE: This previously required parameter has been depricated and is no longer required. Any value will be ignored." }, { "name": "originalFileName", "kind": "optional", "type": "string", "description": "The filename of the original file for this interaction", "children": [] }, { "name": "externalIdentifier", "kind": "optional", "type": "string", "description": "Any external identifier that the user would like associated with this interaction", "children": [] }, { "kind": "optional", "name": "downloadUri", "type": "string", "description": "The URL of your audio file\n\nImportant: Do not include the downloadUri parameter if you wish to upload a local audio file; an empty string will cause the download to fail", "": "The URL of your audio file\n\nImportant: Do not include the downloadUri parameter if you wish to upload a local audio file; an empty string will cause the download to fail" }, { "name": "downloadAuth", "kind": "optional", "type": "object", "description": "This optional body parameter can be used when the downloadUri is specified and the download source requires authentication. \n\nNOTE: If an expiring token is used for authentication, make sure it has a reasonable amount of time left prior to expiration.", "": "This optional body parameter can be used when the downloadUri is specified and the download source requires authentication. \n\nNOTE: If an expiring token is used for authentication, make sure it has a reasonable amount of time left prior to expiration.", "children": [ { "name": "scheme", "kind": "optional", "type": "string", "description": "Specifies the download authentication method to use. Options are: basic and bearer." }, { "name": "value", "kind": "optional", "type": "string", "description": "Specifies the token or other authentication string to use when authenticating during the download process." } ], "schema": [ { "name": "scheme", "kind": "optional", "type": "string", "description": "Specifies the download authentication method to use. Options are: basic and bearer." }, { "name": "value", "kind": "optional", "type": "string", "description": "Specifies the token or other authentication string to use when authenticating during the download process." } ] }, { "kind": "optional", "name": "includeAiResults", "type": "Boolean", "description": "Effective February 29, 2024 with the v1.11 release, all declared interactions will be processed with includeAiResults set to 'true'.\n", "": "Effective February 29, 2024 with the v1.11 release, all declared interactions will be processed with includeAiResults set to 'true'.\n" }, { "name": "metadata", "kind": "optional", "type": "string", "description": "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.", "children": [] } ], "formDataParameters": [] }, "results": { "languages": [ { "id": "IkVdsxIFeIysauK1UAE-R", "code": "{\n \"interactionIdentifier\": \"string\"\n} ", "language": "201", "customLabel": "" }, { "id": "ogn--fHK6DTgAEYiv7jAi", "code": "{\n \"string\"\n}", "language": "400", "customLabel": "" }, { "id": "x6cJ5u7giQEcVl-2Yh9jn", "code": "{\r\n \"string\"\r\n}", "language": "401", "customLabel": "" }, { "id": "OA5jretM7_0dBEf-uJ2UE", "code": "{\r\n \"string\"\r\n}", "language": "429", "customLabel": "" } ], "selectedLanguageId": "ogn--fHK6DTgAEYiv7jAi" }, "examples": { "languages": [ { "id": "FcAJf7sxfneHIYFvcyI3R", "code": "curl --location --request POST 'https://api.elevateai.com/v1/interactions' \\\n--header 'Content-Type: application/json' \\\n--header 'X-API-Token: {Your API Token}' \\\n--data-raw '{\n \"type\": \"audio\",\n \"languageTag\": \"auto\",\n \"vertical\": \"default\",\n \"model\": \"echo\",\n \"audioTranscriptionMode\": \"highAccuracy\",\n \"originalFileName\": \"ABC00012.wav\",\n \"includeAiResults\": true,\n \"metadata\": \"{Your JSON metada payload}\"\n}'", "language": "curl", "customLabel": "" }, { "id": "YmCi9Bw9Qn-c2Fwxj2naz", "code": "var request = require('request');\nvar options = {\n 'method': 'POST',\n 'url': 'https://api.elevateai.com/v1/interactions',\n 'headers': {\n 'Content-Type': 'application/json',\n 'X-API-Token': '{Your API Token}'\n },\n body: JSON.stringify({\n \"type\": \"audio\",\n \"languageTag\": \"auto\",\n \"vertical\": \"default\",\n \"model\": \"echo\",\n \"audioTranscriptionMode\": \"highAccuracy\",\n \"originalFileName\": \"ABC00012.wav\",\n \"includeAiResults\": true,\n \"metadata\": \"{Your JSON metada payload}\"\n })\n\n};\nrequest(options, function (error, response) {\n if (error) throw new Error(error);\n console.log(response.body);\n});", "language": "nodejs", "customLabel": "" }, { "id": "LgaQ-0y77Xjz5joA88eed", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Content-Type\", \"application/json\");\nmyHeaders.append(\"X-API-Token\", \"{Your API Token}\");\n\nvar raw = JSON.stringify({\n \"type\": \"audio\",\n \"languageTag\": \"auto\",\n \"vertical\": \"default\",\n \"model\": \"echo\",\n \"audioTranscriptionMode\": \"highAccuracy\",\n \"originalFileName\": \"ABC00012.wav\",\n \"includeAiResults\": true,\n \"metadata\": \"{Your JSON metada payload}\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.elevateai.com/v1/interactions\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));", "language": "javascript", "customLabel": "" }, { "id": "EwMdPghouS2HMVX2D4Fsg", "code": "import http.client\nimport json\n\nconn = http.client.HTTPSConnection(\"api.elevateai.com\")\npayload = json.dumps({\n \"type\": \"audio\",\n \"languageTag\": \"auto\",\n \"vertical\": \"default\",\n \"model\": \"echo\",\n \"audioTranscriptionMode\": \"highAccuracy\",\n \"originalFileName\": \"ABC00012.wav\",\n \"includeAiResults\": True,\n \"metadata\": \"{Your JSON metada payload}\"\n})\nheaders = {\n 'Content-Type': 'application/json',\n 'X-API-Token': '{Your API Token}'\n}\nconn.request(\"POST\", \"/v1/interactions\", payload, headers)\nres = conn.getresponse()\ndata = res.read()\nprint(data.decode(\"utf-8\"))", "language": "python", "customLabel": "" }, { "id": "yGJx3TtjcUv4Suns2CJI9", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.elevateai.com/v1/interactions\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"Content-Type\"] = \"application/json\"\nrequest[\"X-API-Token\"] = \"{Your API Token}\"\nrequest.body = JSON.dump({\n \"type\": \"audio\",\n \"languageTag\": \"auto\",\n \"vertical\": \"default\",\n \"model\": \"echo\",\n \"audioTranscriptionMode\": \"highAccuracy\",\n \"originalFileName\": \"ABC00012.wav\",\n \"includeAiResults\": true,\n \"metadata\": \"{Your JSON metada payload}\"\n})\n\nresponse = https.request(request)\nputs response.read_body", "language": "ruby", "customLabel": "" }, { "id": "aWYJabfm8e7uV_azdwOXd", "code": "var client = new RestClient(\"https://api.elevateai.com/v1/interactions\");\nclient.Timeout = -1;\nvar request = new RestRequest(Method.POST);\nrequest.AddHeader(\"Content-Type\", \"application/json\");\nrequest.AddHeader(\"X-API-Token\", \"{Your API Token}\");\nvar body = @\"{\n\" + \"\\n\" +\n@\" \"\"type\"\": \"\"audio\"\",\n\" + \"\\n\" +\n@\" \"\"languageTag\"\": \"\"auto\"\",\n\" + \"\\n\" +\n@\" \"\"vertical\"\": \"\"default\"\",\n\" + \"\\n\" +\n@\" \"\"model\"\": \"\"echo\"\",\n\" + \"\\n\" +\n@\" \"\"audioTranscriptionMode\"\": \"\"highAccuracy\"\",\n\" + \"\\n\" +\n@\" \"\"originalFileName\"\": \"\"ABC00012.wav\"\",\n\" + \"\\n\" +\n@\" \"\"includeAiResults\"\": true,\n\" + \"\\n\" +\n@\" \"\"metadata\"\": \"\"{Your JSON metada payload}\"\"\n\" + \"\\n\" +\n@\"}\";\nrequest.AddParameter(\"application/json\", body, ParameterType.RequestBody);\nIRestResponse response = client.Execute(request);\nConsole.WriteLine(response.Content);", "language": "csharp", "customLabel": "" }, { "id": "NL5SCDByKKbrH1USPbk-S", "code": " 'https://api.elevateai.com/v1/interactions',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => '',\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 0,\n CURLOPT_FOLLOWLOCATION => true,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_POSTFIELDS =>'{\n \"type\": \"audio\",\n \"languageTag\": \"auto\",\n \"vertical\": \"default\",\n \"model\": \"echo\",\n \"audioTranscriptionMode\": \"highAccuracy\",\n \"includeAiResults\": true,\n \"metadata\": \"{Your JSON metada payload}\"\n}',\n CURLOPT_HTTPHEADER => array(\n 'Content-Type: application/json',\n 'X-API-Token: {Your API Token}'\n ),\n));\n\n$response = curl_exec($curl);\n\ncurl_close($curl);\necho $response;\n", "language": "php", "customLabel": "" } ], "selectedLanguageId": "FcAJf7sxfneHIYFvcyI3R" }, "description": "", "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "autoGeneratedAnchorSlug": "declare-an-interaction-for-processing-audio", "legacyHash": "WYGW5iauMfg7N79ADYhjF" } ``` ::: :::hint{type="info"} Details on transcription and CX AI features – supported by language – can be found on the [ElevateAI Overview page](https://docs.elevateai.com/overview#Bgq4z). ::: *** # // Submitting an Audio File for Processing ## Download URI Providing access to audio files via the **`downloadUri`** parameter is highly recommended for [faster processing times.](https://docs.elevateai.com/#4Uj8U) :::hint{type="info"} When using the **Download URI option**, authentication parameters can be included in the **`Declare`** for source systems which require it. See **Body Parameters**, above. ::: ## Local File If the **`downloadUri`** parameter is not included when declaring the interaction, the audio file(s) should be uploaded to the API directly for processing. # // Submitting Metadata Metadata must only be submitted with an API Token for an account that has ElevateAI Explore enabled. Any use or submission 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 ElevateAI's [Metadata Tutorial](docId\:SPnq7FPZvAHBXdbCCc7uO) or contact the [ElevateAI Support team](https://docs.elevateai.com/#4zATw).