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

# Conversations API

> Read and manage Contact-centric threads and messages across chat, email, WhatsApp, and forms.

The Conversations API exposes the same durable thread and message records used by Taskbox. It is designed for CRMs, support tools, automations, and AI agents that need one customer timeline without taking a dependency on a specific channel provider.

Public Agent conversations also expose capability discovery and action requests beneath `/v1/public/agents/{agent_id}/conversations/{conversation_id}`. These endpoints require the opaque `X-Conversation-Token`. Assistant messages retain their existing `apps` cards and add an `actions` collection containing review, verification, processing, and result state. Sensitive action input remains in the encrypted action record rather than being duplicated into message payloads.

Use a bearer token with `engagements:read` to read threads and messages. Add `engagements:manage` to send messages or change inbox state.

## Resource model

* A **Contact** is the customer identity owned by one workspace.
* A **Thread** is the Contact-centric timeline shown in Taskbox. One thread can contain several channel conversations.
* A **Conversation** is the channel-specific binding within a thread, such as one web-chat session or email thread.
* A **Message** belongs to a Conversation and carries channel, direction, content, attachments, delivery state, and timestamps.

This deliberately borrows durable conversations, messages, media, delivery status, pagination, and idempotent mutations from mature messaging APIs. It does not copy carrier-specific participant orchestration, proxy addresses, or paid provider infrastructure that Contact Button does not need.

## List threads

```bash theme={null}
curl 'https://api.contactbutton.com/v1/workspaces/{workspace_id}/threads?view=inbox&limit=30' \
  -H 'Authorization: Bearer <access-token>'
```

Filter by `view`, `channel`, or `search`. Follow `meta.next_cursor` to page without skipping records while new messages arrive.

## Read messages

Read the recent timeline with the thread:

```bash theme={null}
curl 'https://api.contactbutton.com/v1/workspaces/{workspace_id}/threads/{thread_id}' \
  -H 'Authorization: Bearer <access-token>'
```

Or page messages independently:

```bash theme={null}
curl 'https://api.contactbutton.com/v1/workspaces/{workspace_id}/threads/{thread_id}/messages?limit=100' \
  -H 'Authorization: Bearer <access-token>'
```

## Send a message

Choose one of the thread's returned Conversations and use its `id` and `channel`. Sending is asynchronous; inspect `delivery_status` and retry only failed outbound messages.

```bash theme={null}
curl -X POST 'https://api.contactbutton.com/v1/workspaces/{workspace_id}/threads/{thread_id}/messages' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: reply-ticket-1842-v1' \
  -d '{
    "conversation_id": "{conversation_id}",
    "channel": "email",
    "body": "Thanks — we are looking into this now."
  }'
```

Channel capabilities in the thread response tell clients whether free-form replies, templates, and attachments are currently allowed. These constraints remain enforced server-side.

## Compatibility

Existing `/inbox-threads` endpoints remain supported and return the same representations. New integrations should use `/threads`; the alias avoids forcing existing Taskbox and partner integrations to migrate.

<Note>
  This first productized slice is REST and polling friendly. Event webhooks, SDK helpers, participant membership, and delivery callbacks are natural follow-on layers, but are not part of this initial contract.
</Note>