> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoverbiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Read conversations, send manual messages, and manage AI handoff.

## List Conversations

`GET /accounts/:id/conversations`

<ParamField query="limit" type="integer" default="50">
  Max results (1-250)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset
</ParamField>

<ParamField query="needs_handoff" type="boolean">
  Filter conversations flagged for human review
</ParamField>

```bash theme={null}
curl https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/conversations?limit=20 \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

**Response: `200 OK`**

```json theme={null}
{
  "conversations": [
    {
      "phone": "+14155551234",
      "name": "John Doe",
      "preview": "Sure, I can send the T4 slip tomorrow morning.",
      "last_message_at": "2026-02-14T15:30:00Z",
      "message_count": 12,
      "needs_handoff": false,
      "lead_status": "qualified",
      "in_sequence": true
    }
  ],
  "total": 289,
  "limit": 20,
  "offset": 0
}
```

## Get Messages

`GET /accounts/:id/conversations/:phone/messages`

Returns the message history for a conversation, newest first.

<ParamField query="limit" type="integer" default="50">
  Max messages to return (1-250)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset
</ParamField>

```bash theme={null}
curl https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/conversations/+14155551234/messages?limit=50 \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

**Response: `200 OK`**

```json theme={null}
{
  "messages": [
    {
      "id": "msg_001",
      "direction": "outbound",
      "body": "Hi John, this is Acme Lending. We noticed your loan application is almost complete — just a few documents left. Can I help?",
      "sent_at": "2026-02-10T10:00:00Z",
      "source": "sequence"
    },
    {
      "id": "msg_002",
      "direction": "inbound",
      "body": "Hey, yeah I still need to send my bank statements. What exactly do you need?",
      "sent_at": "2026-02-10T10:05:00Z"
    },
    {
      "id": "msg_003",
      "direction": "outbound",
      "body": "No problem! We need your last 3 months of bank statements. You can just snap a photo and text it to me here, or send a PDF if you have one.",
      "sent_at": "2026-02-10T10:05:30Z",
      "source": "ai"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}
```

## Send Message (Manual Takeover)

`POST /accounts/:id/conversations/:phone/messages`

Send a message as a human operator. The AI pauses automatic responses for this conversation until manually re-enabled or a configured timeout passes.

<ParamField body="body" type="string" required>
  Message text to send
</ParamField>

<ParamField body="sender_name" type="string">
  Display name of the human sender (for internal tracking)
</ParamField>

```bash theme={null}
curl -X POST https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/conversations/+14155551234/messages \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi John, this is Sarah from Acme Lending. I wanted to follow up personally — let me know if you have any questions about the application.",
    "sender_name": "Sarah Johnson"
  }'
```

**Response: `200 OK`**

```json theme={null}
{
  "success": true,
  "message_id": "msg_042",
  "direction": "outbound",
  "source": "manual"
}
```

## Resume AI

`POST /accounts/:id/conversations/:phone/resume-ai`

Re-enable AI responses after manual takeover.

```bash theme={null}
curl -X POST https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/conversations/+14155551234/resume-ai \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

**Response: `200 OK`**

```json theme={null}
{
  "success": true,
  "ai_enabled": true
}
```