Send Conversation
In addition to voice calls, you can send conversations from your live chat or messaging channels to ThinkVoice and have them analyzed the same way. When a conversation ends, send all of its messages in a single request. ThinkVoice saves and analyzes the conversation; the result appears alongside voice calls in the Call Records results, and the Call Analysis Completed webhook is sent to you if configured.
Text conversations have no audio recording. The recordUrl returned for these conversations cannot be used to download a recording.
Authentication
You can use either of two methods:
| Method | Headers |
|---|---|
| API key | X-Api-Key and X-Api-Secret (both required) |
| Bearer token | Authorization: Bearer <access_token> (Authentication) |
The company the data is written to is determined by the X-Api-Secret or token you use; you do not need to send company information separately.
For this endpoint to work, a text channel integration must be configured for your company by our team. If it is not configured, 422 is returned.
Request Body
{
"conversation_id": "chat-20260410-00815",
"channel": {
"id": "live-chat",
"name": "Live Chat"
},
"agent": {
"id": "1042",
"name": "Jane Smith"
},
"customer": {
"id_or_phone": "+905xxxxxxxxx",
"name": "John Doe"
},
"start_time": "2026-04-10T11:35:12Z",
"end_time": "2026-04-10T11:41:47Z",
"messages": [
{
"sender": "customer",
"sender_name": "John Doe",
"text": "Hi, my refund still hasn't reached my account.",
"timestamp": "2026-04-10T11:35:12Z"
},
{
"sender": "agent",
"sender_name": "Jane Smith",
"text": "Hi, let me check that for you right away.",
"timestamp": "2026-04-10T11:35:40Z"
}
],
"metadata": {
"ref_id": "q_6876"
}
}Parameters
Field names on this endpoint are written in snake_case (conversation_id, start_time, id_or_phone). The camelCase naming used by the other Public API endpoints does not apply here.
The conversation is created in ThinkVoice as an inbound, answered record. Its duration is calculated from the difference between start_time and end_time.
The limit for this endpoint is 600 requests per 60 seconds. When exceeded, 429 is returned and the Retry-After header indicates how long to wait, in seconds.
Example cURL
curl --request POST 'https://public-api.thinkvoice.ai/api/v1/webhooks/conversations' \
--header 'X-Api-Key: <API_KEY>' \
--header 'X-Api-Secret: <API_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"conversation_id": "chat-20260410-00815",
"channel": { "id": "live-chat", "name": "Live Chat" },
"agent": { "id": "1042", "name": "Jane Smith" },
"customer": { "id_or_phone": "+905xxxxxxxxx" },
"start_time": "2026-04-10T11:35:12Z",
"end_time": "2026-04-10T11:41:47Z",
"messages": [
{ "sender": "customer", "text": "Hi, my refund still hasn't reached my account.", "timestamp": "2026-04-10T11:35:12Z" },
{ "sender": "agent", "text": "Hi, let me check that for you right away.", "timestamp": "2026-04-10T11:35:40Z" }
]
}'Responses
The ID in message is the conversation’s callId in ThinkVoice. You can use it to query the conversation with the Call Detail endpoint.
Resending a request with the same conversation_id is safe. If the conversation has already been queued for analysis, Already processed. is returned. If a previous attempt was left incomplete, ThinkVoice resumes from where it stopped and returns successfully reprocessed. So when you receive a 5xx, you can resend the request unchanged.
| Message | HTTP | Description |
|---|---|---|
conversation_id is required. | 400 | conversation_id is empty. |
channel.id is required. | 400 | channel.id is empty. |
customer.id_or_phone is required. | 400 | customer.id_or_phone is empty. |
start_time and end_time are required. | 400 | The start or end time is missing. |
end_time cannot be earlier than start_time. | 400 | The end time is before the start time. |
messages cannot be empty. | 400 | The message list is missing or empty. |
messages[].text cannot be empty. | 400 | One of the messages has empty text. |
Invalid credentials. | 401 | The company could not be determined from the credentials. |
Text channel integration is not configured. | 422 | No text channel integration is configured for your company. Contact our team. |
An error occurred while processing the conversation data. | 500 | Unexpected error. Resend the same request; if it persists, contact our team. |
Requests with invalid or missing credentials may return 401 without a body. The JSON body above is returned only when authentication succeeds but the company cannot be determined.