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

# Conversations

> Browse WhatsApp direct and existing group conversations and update local unread history

Paths are relative to `https://inkbox.ai/api/v1/whatsapp`. Use the selected `agent_identity_id` query parameter where required. History remains tied to the original agent, not whoever later receives a phone number.

## List conversations

```text theme={null}
GET /conversations
```

Returns a bare array ordered by recent activity. `limit` defaults to `50` and accepts 1–200; `offset` defaults to `0`. The optional `is_blocked` filter is available only within the caller's authorized visibility.

```python Python theme={null}
conversations = identity.list_whatsapp_conversations(limit=50, offset=0)
```

```typescript TypeScript theme={null}
const conversations = await identity.listWhatsAppConversations({ limit: 50, offset: 0 });
```

```bash CLI theme={null}
inkbox whatsapp conversations --identity my-agent --limit 50 --offset 0
```

### Find conversations with a person

Use either optional filter:

| Parameter | Type | Description |
| :- | :- | :- |
| `participants` | string\[] | Match any supplied E.164 phone number. Repeat the query parameter for multiple values (1–100, up to 320 characters each). Cannot be combined with `contact_id`. |
| `contact_id` | UUID | Match any accessible active phone number associated with this saved contact. Cannot be combined with `participants`. |

```text theme={null}
GET /conversations?participants=%2B15555550123&participants=%2B15555550124
```

Filters apply before pagination, include authorized direct and group conversations, and return each matching conversation once. A contact with no applicable phone numbers returns an empty list. Omitting both filters preserves the existing list. Invalid selectors or supplying both returns `422`; an unknown or inaccessible contact returns `404`. Filters do not expand access to messages or group members.

### Conversation fields

Every conversation contains `id`, `agent_identity_id`, `local_number`, nullable `remote_number`, `participants`, `is_group`, nullable `group_name`, `unresolved_participant_count`, `created_at`, and `updated_at`. For direct messages, `remote_number` is the remote E.164 number and `participants` remains a singleton array. For groups, `remote_number` is null and `participants` contains known remote E.164 numbers; the local number is separate. `unresolved_participant_count` counts members whose phone number is unavailable.

`group_name` is a display label, not an address or unique identifier. Use the returned `id` as `conversation_id` when replying. [Groups](https://inkbox.ai/docs/api/whatsapp/groups.md) are joined outside Inkbox and require an incoming message before outbound communication. Names do not grant access; current contact permissions still apply.

Groups are included in authorized lists without a separate opt-in. Older strict clients that require non-null phone numbers cannot parse group responses, including an entire list containing even one group; update them to SDK `0.7.29` or later before processing groups.

List entries also contain:

| Field | Type | Description |
| :- | :- | :- |
| `latest_text` | string or null | Latest stored text preview |
| `latest_message_at` | timestamp or null | Latest message time |
| `latest_direction` | string or null | `inbound` or `outbound` |
| `latest_has_media` | boolean | Whether the latest message has an attachment |
| `unread_count` | integer | Local unread count |
| `total_count` | integer | Stored message count |

## Get a conversation

```text theme={null}
GET /conversations/{conversation_id}
```

Returns a flat conversation object, not embedded message history. Read its messages with [`GET /messages?conversation_id=...`](https://inkbox.ai/docs/api/whatsapp/messages#list-messages). An inaccessible or unknown conversation returns `404`.

Use its ID to send another message in the same conversation. Reading a conversation does not enable a disabled channel or transfer its history to another identity.

## Mark local history read

```text theme={null}
POST /mark-read
```

Provide both UUIDs:

```json theme={null}
{
  "conversation_id": "22222222-2222-4222-8222-222222222222",
  "through_message_id": "33333333-3333-4333-8333-333333333333"
}
```

Only visible inbound messages through that message boundary are marked read. Newer arrivals remain unread. The response is `{ "conversation_id": "...", "updated_count": 1 }`. This updates local history only; it does not send a remote read receipt.

```python Python theme={null}
result = identity.mark_whatsapp_read(conversation_id, through_message_id)
```

```typescript TypeScript theme={null}
const result = await identity.markWhatsAppRead(conversationId, throughMessageId);
```

```bash CLI theme={null}
inkbox whatsapp mark-read --identity my-agent \
  --conversation-id 22222222-2222-4222-8222-222222222222 \
  --through-message-id 33333333-3333-4333-8333-333333333333
```

### Date filters

Both message and conversation lists accept `start_datetime`, `end_datetime`, and `tz`. Bounds filter `created_at`; start and end instants are inclusive. A bare end date includes the entire calendar day. Zone-less values use the supplied IANA timezone, or UTC by default. Explicit-offset timestamps retain their own timezone. Filtering happens before pagination.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.