# 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:**

```json
{
  "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 Conversation

```
GET /api/v1/conversations/:id
```

Returns a single conversation by ID.

**Response (`200 OK`):** `{ "data": <conversation> }` (same shape as a list entry).

## 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, capped per plan) |

**Response (`200 OK`):**

```json
{
  "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,
    "total": 12,
    "totalPages": 1
  }
}
```

## 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:**

```json
{
  "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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 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`.