Conversations API

List Conversations


GET /api/v1/conversations

Scope: conversations:read

Query Parameters

Param	Type	Description
`contact_id`	string	Filter by contact
`limit`	number	Max results (default 50, max 100)

Response


{
  "conversations": [
    {
      "id": "uuid",
      "channel": "email",
      "subject": "Follow-up",
      "status": "active",
      "override_status": "ai_active",
      "contact_id": "uuid",
      "starred": false,
      "tags": ["follow-up"],
      "last_activity_at": "2026-03-26T10:00:00Z",
      "created_at": "2026-03-25T09:00:00Z"
    }
  ]
}

Create Conversation / Add Message


POST /api/v1/conversations

Scope: conversations:write

Creates a new conversation or appends a message to an existing one.

Request Body


{
  "contact_id": "uuid",
  "channel": "email",
  "subject": "Assessment Follow-Up",
  "content": "Hi John, here are the results of your AI assessment...",
  "direction": "inbound",
  "conversation_id": "uuid"
}

Field	Required	Description
`contact_id`	Yes	The contact this conversation belongs to
`channel`	No	`email`, `sms`, `chat`, `whatsapp` (default: email)
`subject`	No	Conversation subject line
`content`	No	Message text (if provided, creates a message)
`direction`	No	`inbound` or `outbound` (default: inbound)
`conversation_id`	No	Append to existing conversation instead of creating new

Response (201)


{
  "conversation_id": "uuid"
}