Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jAtInn71/chatwoot-costom/llms.txt

Use this file to discover all available pages before exploring further.

The voice_transcript endpoint records one turn of a live ElevenLabs voice call as a Chatwoot message. The widget calls this endpoint automatically on every completed turn — user or AI — during a voice session, building a full transcript in the conversation timeline that agents can read in the dashboard. If the visitor starts a voice call before sending any text message (a voice-first flow), the endpoint creates a new conversation on the fly so the transcript has a place to land. The conversation is tagged with additional_attributes: { initiated_from: "voice_agent" } to distinguish it from text-initiated conversations.

​
Endpoint

POST /api/v1/widget/conversations/voice_transcript

​
Authentication

Identified by the website_token query parameter. No agent session is required.

​
Query parameters

​
website_token
string
required
The website token from the widget embed script. Identifies the inbox and associates the transcript message with the correct contact and conversation.

​
Request body

​
source
string
required
Who spoke this turn. Must be either "user" (the visitor) or "ai" (the ElevenLabs agent). Any other value returns a 400 Bad Request.
​
content
string
required
The transcript text for this turn. Must not be blank. Returns 400 Bad Request if the value is empty or whitespace-only.

​
Behavior

The endpoint maps each turn to a Chatwoot message with the following rules:
  • source: "user" → message_type: incoming, sender set to the current contact
  • source: "ai" → message_type: outgoing, sender is null
Every message created by this endpoint has content_attributes set to: 
{
  "voice_transcript": true,
  "role": "<source value>"
}
This allows the Chatwoot dashboard and any downstream reporting to identify and style voice transcript messages differently from regular chat messages. Voice-first conversations: If the visitor has no open conversation when voice_transcript is called, a new conversation is created automatically: 
{
  "additional_attributes": {
    "initiated_from": "voice_agent"
  }
}
After each successful post, the widget dispatches conversation/syncLatestMessages so the visitor also sees their voice turns appear in the message bubble area in real time.

​
Response

Returns HTTP 200 on success with the created message’s ID and its parent conversation ID.
​
id
number
The numeric ID of the newly created message.
​
conversation_id
number
The ID of the conversation the message was appended to. Use this to correlate messages from the same voice session.

​
Example request

curl -X POST \
  "https://your-chatwoot-domain.com/api/v1/widget/conversations/voice_transcript?website_token=YOUR_WEBSITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "user", "content": "What are your business hours?"}'

​
Example response

{
  "id": 1042,
  "conversation_id": 87
}

​
Error responses

{
  "error": "invalid source"
}
Returned with HTTP 400 when source is not "user" or "ai". 
{
  "error": "empty content"
}
Returned with HTTP 400 when content is blank or missing.

​
Notes

This endpoint is called internally by the widget during a voice session. You do not need to call it yourself unless you are building a custom integration that handles ElevenLabs transcript events outside the standard widget.
Each call appends exactly one turn. The widget fires one request per completed turn as the ElevenLabs SDK delivers transcript events, so a full conversation is built incrementally over the lifetime of the call.

Build docs developers (and LLMs) love

Get started for freeTalk to us