Conversations
Text chat endpoints for third-party chat tool integration.
Conversations connect your chat tool (help desk, in-app messenger, custom widget) to the same agent that answers your calls — knowledge base, workflows, tools and persona included. The model is strictly request→reply: you POST the end-user's message and the agent's answer comes back in the same HTTP response (up to 60 s), so there are no callbacks to host.
Every reply carries an actions array — the machine-readable side-channel for your integration. handoff means route the thread to a human seat in your tool; end_conversation means archive it; ticket_created and workflow_completed report work the agent did mid-turn. Ignore action types you don't recognize — new ones are added without an API version bump.
POST /v1/conversations— Create a conversationGET /v1/conversations— List conversationsGET /v1/conversations/{id}— Retrieve a conversationPOST /v1/conversations/{id}/messages— Send a message and get the replyGET /v1/conversations/{id}/messages— List messages (transcript)POST /v1/conversations/{id}/end— End a conversationPOST /v1/messages— Send a message by external thread id
Delete a knowledge entry
Permanently removes the entry from the agent's knowledge base. The deletion is recorded in the project's knowledge history, so a trainer can roll it back from the admin UI if needed.
Create a conversation
Opens a conversation for a chat thread in your tool. Linking a `customer` (by phone or email) gives the agent per-customer memory and workflow context; `external_id` maps the conversation to your thread id and enables the shortcut `POST /v1/messages`. Returns `409 external_id_taken` (with `error.existing_id`) when a live conversation already exists under the same `external_id` — post messages to that one, or end it first. An ended conversation frees its `external_id` for reuse.