---
title: Declare a Chat Interaction
slug: tutorials/declare-a-chat-interaction
description: Learn how to declare and process chat interactions in ElevateAI with this comprehensive document. Discover how successful POST requests return an interactionIdentifier that must be stored for future use. Find out how interactions count towards your monthl
createdAt: 2022-06-14T17:24:57.000Z
---
# // Overview
The first step in processing any chat 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": "6091d697-9a98-4953-9850-d3e9b82cd5ab"
}
```
:::
**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 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 the file upload status or processing outcome.
Only interactions that have **successfully processed** are eligible for billing.
**--> **Once declared, you can [check 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)
:::
***
# // Request Parameters & Code Samples
*Details on language support for CX AI features can be found on the [CX AI Feature Overview](docId\:ZATcqMNsVApZs9WWKgeCn) page.*
:::ApiMethodV2
```json
{
"tab": "examples",
"url": "https://api.elevateai.com/v1/interactions",
"name": "Declare a Chat Interaction",
"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\n\"chat\""
},
{
"kind": "required",
"name": "languageTag",
"type": "string",
"description": "Primary language of the chat, will be \n\"en-us\" (for North American English), \n\"en\" (for International English), or \n\"es-419\" (for North American Spanish)"
},
{
"kind": "required",
"name": "vertical",
"type": "string",
"description": "Vertical associated with interaction, will be \"default\""
},
{
"kind": "required",
"name": "chat",
"type": "Object",
"description": "Formatted chat text (see below)"
}
],
"formDataParameters": []
},
"results": {
"languages": [
{
"id": "IkVdsxIFeIysauK1UAE-R",
"code": "{\n \"interactionIdentifier\": \"string\"\n} ",
"language": "201",
"customLabel": ""
},
{
"id": "ogn--fHK6DTgAEYiv7jAi",
"code": "{\n \"errorMessage\": \"string\"\n}",
"language": "400",
"customLabel": ""
},
{
"id": "x6cJ5u7giQEcVl-2Yh9jn",
"code": "{\r\n \"errorMessage\": \"string\"\r\n}",
"language": "401",
"customLabel": ""
},
{
"id": "OA5jretM7_0dBEf-uJ2UE",
"code": "{\r\n \"errorMessage\": \"string\"\r\n}",
"language": "429",
"customLabel": ""
}
],
"selectedLanguageId": "OA5jretM7_0dBEf-uJ2UE"
},
"examples": {
"languages": [
{
"id": "b00i4WtyTtXKbrPWpgfCo",
"language": "curl",
"code": "curl --location 'https://api.elevateai.com/v1/interactions' \\\n--header 'X-API-Token: string' \\\n--header 'Content-Type: string' \\\n--data '{\"type\":\"String\",\"languageTag\":\"String\",\"vertical\":\"String\",\"chat\":\"Object\"}'",
"customLabel": ""
},
{
"id": "Lzfpbg1mdD4P-nW95I41c",
"language": "nodejs",
"code": "var request = require('request');\nvar options = {\n 'method': 'POST',\n 'url': 'https://api.elevateai.com/v1/interactions',\n 'headers': {\n 'X-API-Token': 'string',\n 'Content-Type': 'string'\n },\n body: '{\"type\":\"String\",\"languageTag\":\"String\",\"vertical\":\"String\",\"chat\":\"Object\"}'\n\n};\nrequest(options, function (error, response) {\n if (error) throw new Error(error);\n console.log(response.body);\n});\n",
"customLabel": ""
},
{
"id": "WPvm_M7-_aMub3GnbLPp4",
"language": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"X-API-Token\", \"string\");\nmyHeaders.append(\"Content-Type\", \"string\");\n\nvar raw = \"{\\\"type\\\":\\\"String\\\",\\\"languageTag\\\":\\\"String\\\",\\\"vertical\\\":\\\"String\\\",\\\"chat\\\":\\\"Object\\\"}\";\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));",
"customLabel": ""
},
{
"id": "s1945QbhEqS4m9i0N5Qrj",
"language": "python",
"code": "import requests\n\nurl = \"https://api.elevateai.com/v1/interactions\"\n\npayload = \"{\\\"type\\\":\\\"String\\\",\\\"languageTag\\\":\\\"String\\\",\\\"vertical\\\":\\\"String\\\",\\\"chat\\\":\\\"Object\\\"}\"\nheaders = {\n 'X-API-Token': 'string',\n 'Content-Type': 'string'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n",
"customLabel": ""
},
{
"id": "kO_YJCi7Z4Qu2vIZPH8it",
"language": "ruby",
"code": "require \"uri\"\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[\"X-API-Token\"] = \"string\"\nrequest[\"Content-Type\"] = \"string\"\nrequest.body = \"{\\\"type\\\":\\\"String\\\",\\\"languageTag\\\":\\\"String\\\",\\\"vertical\\\":\\\"String\\\",\\\"chat\\\":\\\"Object\\\"}\"\n\nresponse = https.request(request)\nputs response.read_body\n",
"customLabel": ""
}
],
"selectedLanguageId": "WPvm_M7-_aMub3GnbLPp4"
},
"description": "",
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"autoGeneratedAnchorSlug": "declare-a-chat-interaction",
"legacyHash": "iHVRmRW3Gq8XkGIn79N5S"
}
```
:::
***
# // Formatting a Chat for Processing
`Chat` files will be formatted according to the schema below and included as a body parameter when declaring a chat interaction for processing.
::::ExpandableHeading{isOpen="true"}
## Sample Chat File Format
:::CodeblockTabs
Sample Chat Format
```json
{
"participants": [
{
"participant_id": "ElevateAI Team",
"name": "Madison",
"role": "agent"
},
{
"participant_id": "ElevateAI Evangelist",
"name": "Developer",
"role": "customer"
}
],
"messages": [
{
"participant_id": "ElevateAI Team",
"timestamp": "2022-07-04T14:25:15Z",
"content": "We hope this documentation is useful!"
},
{
"participant_id": "ElevateAI Evangelist",
"timestamp": "2022-07-04T14:26:45Z",
"content": "It is, thank you!"
}
]
}
```
:::
::::
:::ExpandableHeading{isOpen="true"}
## Schema
| **Element** | **Type** | **Description** |
| ------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **participants** | array of objects | Ordered list of details associated with each participant, will include 1+ objects |
| participant/**participant\_id** | string | Unique identifier associated with participant |
| participants/**name** | string | Name of participant |
| participants/**role** | string or null | Will be **`agent`** or **`customer`** |
| **messages** | array of objects | Ordered list of details associated with each chat message, will include 1+ objects |
| messages/**participant\_id** | string | Maps to a unique participant\_id within participants object |
| messages/**timestamp** | string | Date/time that the chat message was sent, formatted according to [ISO 8601 (UTC) guidelines](https://www.cl.cam.ac.uk/~mgk25/iso-time.html). |
| messages/**content** | string | Chat message |
:::
**Need more help? **Contact the [ElevateAI Support team](mailto\:support@elevateai.com).