Conversations API

All endpoints require a valid Bearer token. See Authentication.

Conversation schema

Field	Type	Description
`id`	UUID	Unique conversation identifier
`lead_id`	UUID	Associated lead
`session_key`	string	Channel-specific session key
`channel`	string	Channel: `whatsapp`, `telegram`, `web`, `voice`
`status`	string	Conversation status
`message_count`	integer	Total messages in this conversation
`created_at`	datetime	When the conversation started
`updated_at`	datetime	Last activity
`lead`	object	Brief lead info
`last_message_at`	datetime	Timestamp of the most recent message
`last_message_preview`	string	Preview of the most recent message

Conversation statuses

Status	Meaning
`active`	Conversation is in progress
`completed`	Booking was made or conversation ended naturally
`escalated`	Handed off to a human team member
`abandoned`	Customer stopped responding

Message schema

Field	Type	Description
`id`	UUID	Unique message identifier
`conversation_id`	UUID	Parent conversation
`role`	string	Message role: `user`, `assistant`, or `system`
`content`	string	Message text content
`metadata`	object	Additional data (provider-specific info)
`created_at`	datetime	When the message was sent

List conversations

GET /api/v1/conversations

Query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`size`	integer	20	Results per page (max: 100)
`lead_id`	UUID	—	Filter by lead ID
`status`	string	—	Filter by status
`channel`	string	—	Filter by channel

Response:

{
  "conversations": [
    {
      "id": "880b0500-...",
      "lead_id": "550e8400-...",
      "session_key": "whatsapp_+49123456789",
      "channel": "whatsapp",
      "status": "completed",
      "message_count": 12,
      "created_at": "2026-03-07T10:00:00Z",
      "updated_at": "2026-03-07T10:15:00Z",
      "lead": {
        "id": "550e8400-...",
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "last_message_at": "2026-03-07T10:15:00Z",
      "last_message_preview": "Your appointment is confirmed for..."
    }
  ],
  "total": 28,
  "page": 1,
  "size": 20
}

Get a conversation

GET /api/v1/conversations/{conversation_id}

Returns the conversation metadata and all messages in chronological order.

Response:

{
  "id": "880b0500-...",
  "lead_id": "550e8400-...",
  "session_key": "whatsapp_+49123456789",
  "channel": "whatsapp",
  "status": "completed",
  "created_at": "2026-03-07T10:00:00Z",
  "updated_at": "2026-03-07T10:15:00Z",
  "messages": [
    {
      "id": "990c0600-...",
      "conversation_id": "880b0500-...",
      "role": "user",
      "content": "Hi, I'd like to book a haircut",
      "metadata": {},
      "created_at": "2026-03-07T10:00:00Z"
    },
    {
      "id": "aa0d0700-...",
      "conversation_id": "880b0500-...",
      "role": "assistant",
      "content": "Hello! I'd be happy to help you book a haircut...",
      "metadata": {},
      "created_at": "2026-03-07T10:00:05Z"
    }
  ],
  "lead": {
    "id": "550e8400-...",
    "name": "Jane Smith"
  }
}

Get messages

Fetch messages for a specific conversation with pagination.

GET /api/v1/conversations/{conversation_id}/messages?limit=50&offset=0

Query parameters:

Parameter	Type	Default	Description
`limit`	integer	100	Max messages to return (max: 500)
`offset`	integer	0	Number of messages to skip

Returns an array of message objects.

Update conversation status

PATCH /api/v1/conversations/{conversation_id}
Content-Type: application/json

{
  "status": "completed"
}

Valid statuses: active, completed, escalated, abandoned.