Skip to Content
Text ChannelsSend Conversation

Send Conversation

POST/api/v1/webhooks/conversations
Forwards a conversation from a text channel such as live chat, together with its messages, to ThinkVoice for analysis.

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:

MethodHeaders
API keyX-Api-Key and X-Api-Secret (both required)
Bearer tokenAuthorization: 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

FieldTypeRequiredDescription
conversation_idstringYesUnique ID of the conversation in your system. If it is sent again with the same ID, the conversation is not created a second time.
channelobjectYesChannel the conversation came from. It is tracked as a queue in ThinkVoice, and analysis settings are applied per channel.
channel.idstringYesID of the channel in your system. A new queue is created automatically in ThinkVoice for a channel ID sent for the first time.
channel.namestringNoDisplay name of the channel. If omitted, channel.id is used.
agentobjectNoThe agent who handled the conversation.
agent.idstringNoID of the agent in your system. If omitted, the conversation is saved without an agent.
agent.namestringNoName of the agent. If agent.id is sent without a name, "Agent" is used.
customerobjectYesThe customer in the conversation.
customer.id_or_phonestringYesCustomer ID or phone number. Used to group conversations of the same customer; send the same value for the same customer in every conversation.
customer.namestringNoCustomer name. If omitted, the id_or_phone value is used.
start_timedatetimeYesMoment the conversation started. Send in ISO 8601 and UTC (ending with Z).
end_timedatetimeYesMoment the conversation ended. Cannot be earlier than start_time.
messagesarrayYesMessages in the conversation. Must contain at least one message.
messages[].senderstringYesWho wrote the message. "agent" means the agent; any other value is treated as the customer. E.g. agent, customer.
messages[].sender_namestringNoName of the sender. If omitted, agent.name or customer.name is used.
messages[].textstringYesMessage text. Cannot be empty; the request is rejected if any message is empty.
messages[].timestampdatetimeNoMoment the message was sent. Messages are ordered by this value; sending it is recommended to keep the message order correct.
metadataobjectNoFree-form key-value data. Returned unchanged in the metadata field of Call Records and webhook payloads. To match records with your own system, you can send e.g. ref_id.

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

200Success
{ "success": true, "message": "019e925a-5f79-7778-b0be-a45a146cf828 successfully processed" }

The ID in message is the conversation’s callId in ThinkVoice. You can use it to query the conversation with the Call Detail endpoint.

200Conversation already received
{ "success": true, "message": "Already processed." }

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.

400Required field missing
{ "success": false, "message": "messages cannot be empty." }
422Text channel integration not configured
{ "success": false, "message": "Text channel integration is not configured." }
MessageHTTPDescription
conversation_id is required.400conversation_id is empty.
channel.id is required.400channel.id is empty.
customer.id_or_phone is required.400customer.id_or_phone is empty.
start_time and end_time are required.400The start or end time is missing.
end_time cannot be earlier than start_time.400The end time is before the start time.
messages cannot be empty.400The message list is missing or empty.
messages[].text cannot be empty.400One of the messages has empty text.
Invalid credentials.401The company could not be determined from the credentials.
Text channel integration is not configured.422No text channel integration is configured for your company. Contact our team.
An error occurred while processing the conversation data.500Unexpected 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.

Last updated: