Conversations API

The Conversations API exposes the AI chat sessions your chatbots hold with leads across connected platforms. Use it to read transcripts, send messages, and hand a conversation off to a human agent.

Overview

A conversation is a single thread between one chatbot and one contact, persisted with its full message history. Each message carries a role: USER, ASSISTANT, SYSTEM, or HUMAN_AGENT. All endpoints require a Bearer API key with the read:conversations or write:conversations scope.

List Conversations

Filter by chatbot, status, or contact.

curl -X GET "https://api.anvilhk.com/v1/conversations?status=HUMAN_TAKEOVER" \
  -H "Authorization: Bearer anv_live_sk_49kPz9..." \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    { "id": "conv_3a1", "botId": "bot_12", "contactId": "ctc_88", "status": "HUMAN_TAKEOVER", "lastMessageAt": "2026-07-16T09:12:00Z" }
  ],
  "meta": { "total": 34, "cursor": "eyJp...", "hasMore": true }
}

Fetch Messages

Retrieve the full transcript for one conversation. Messages are returned in chronological order, each with role, content, and createdAt.

curl -X GET https://api.anvilhk.com/v1/conversations/conv_3a1/messages \
  -H "Authorization: Bearer anv_live_sk_49kPz9..."

Send a Message

Post a message into a conversation. If the conversation is bot-driven, set role to ASSISTANT; if a human is replying after takeover, use HUMAN_AGENT.

curl -X POST https://api.anvilhk.com/v1/conversations/conv_3a1/messages \
  -H "Authorization: Bearer anv_live_sk_49kPz9..." \
  -H "Content-Type: application/json" \
  -d '{ "role": "HUMAN_AGENT", "content": "Hi! Our MOQ is 500 units. Happy to send a quote." }'

Human Takeover

When a bot escalates — or when you want to step in — switch the conversation to human control:

curl -X POST https://api.anvilhk.com/v1/conversations/conv_3a1/takeover \
  -H "Authorization: Bearer anv_live_sk_49kPz9..."

The status moves to HUMAN_TAKEOVER and the bot stops auto-replying until you close or reassign the thread. Close a resolved conversation with POST /v1/conversations/:id/close.

Statuses

Errors

Responses use the standard envelope. Posting to a closed conversation returns:

{
  "success": false,
  "error": { "code": "CONVERSATION_CLOSED", "message": "Cannot post to a closed conversation. Reopen it first." }
}

See [Rate Limits](/docs/api-reference/rate-limits) for per-endpoint caps.