Conversations API

Read-only access to conversations and messages. Useful for CRM sync, reporting, and analytics integrations.

List Conversations


GET /api/v1/conversations

Returns conversations ordered by most recent message.

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)
`contactId`	uuid	Filter by contact
`status`	string	`active` or `archived`

Response:


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contactId": "770e8400-e29b-41d4-a716-446655440000",
      "propertyId": "660e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "startedAt": "2026-02-10T14:30:00Z",
      "lastMessageAt": "2026-02-11T09:15:00Z",
      "createdAt": "2026-02-10T14:30:00Z",
      "updatedAt": "2026-02-11T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 34,
    "totalPages": 2
  }
}

Get Messages


GET /api/v1/conversations/:id/messages

Returns messages in a conversation, newest first.

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Messages per page (default: 20)

Response:


{
  "data": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "direction": "inbound",
      "content": "Hi, I'm interested in the 2BR on Main St. Is it still available?",
      "channel": "whatsapp",
      "metadata": null,
      "sentAt": "2026-02-11T09:15:00Z",
      "createdAt": "2026-02-11T09:15:00Z"
    },
    {
      "id": "990e8400-e29b-41d4-a716-446655440000",
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "direction": "outbound",
      "content": "Yes, it's available! Would you like to schedule a showing?",
      "channel": "whatsapp",
      "metadata": null,
      "sentAt": "2026-02-11T09:15:05Z",
      "createdAt": "2026-02-11T09:15:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20
  }
}

Search Messages


GET /api/v1/conversations/search

Full-text keyword search across all message content. Returns matching messages with conversation and contact context.

Query Parameters:

Parameter	Type	Description
`query`	string	Search term (required, case-insensitive substring match)
`limit`	number	Max results (default: 10, max: 50)

Response:


{
  "data": [
    {
      "messageId": "880e8400-e29b-41d4-a716-446655440000",
      "content": "I'm looking for a 2-bedroom apartment",
      "direction": "inbound",
      "channel": "whatsapp",
      "sentAt": "2026-02-11T09:15:00Z",
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "contactName": "Jane Smith"
    }
  ],
  "total": 1
}

Notes

Read-only — conversations and messages are created by the AI agent pipeline when prospects message through your channels.
Message direction is inbound (from prospect) or outbound (from your AI agent).
channel indicates the messaging platform: whatsapp, telegram, email, sms, or web.