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

# Conversations API

> Omnichannel inbox — list, reply, assign, hand off from AI to human, and manage conversation lifecycle across SMS, WhatsApp, email, RCS, Viber, Instagram, Messenger, and LINE.

# Conversations API

A single thread per contact-channel pair, regardless of which channel the message came in on. Conversations are how the inbox UI groups inbound messages, AI replies, and agent replies — and how you'd integrate the same lifecycle into your own UI.

**Base path:** `/api/v1/conversations`

**Authentication:** API key (`X-API-Key`) or session JWT.

This page is a curated map of the whole surface, grouped by task. Every endpoint below is live and callable. For per-endpoint request/response schemas and copy-pasteable code samples in six languages, see the [full Conversations endpoint reference](/api-reference/endpoints/conversations).

## Read & inspect

| Method | Path                                            | Purpose                                                              |
| ------ | ----------------------------------------------- | -------------------------------------------------------------------- |
| `GET`  | `/api/v1/conversations`                         | List conversations (unified omnichannel inbox, with filters)         |
| `GET`  | `/api/v1/conversations/export`                  | Export the filtered inbox as CSV or JSON                             |
| `GET`  | `/api/v1/conversations/tags/distinct`           | List every tag in use across the tenant, with counts                 |
| `GET`  | `/api/v1/conversations/{id}`                    | Get a single conversation                                            |
| `GET`  | `/api/v1/conversations/{id}/messages`           | Get the message thread                                               |
| `GET`  | `/api/v1/conversations/{id}/activity`           | Get the operator activity feed (assignments, status changes, merges) |
| `GET`  | `/api/v1/conversations/{id}/cost`               | Get the live LLM + tool-call cost for the conversation               |
| `GET`  | `/api/v1/conversations/{id}/sentiment-timeline` | Get the per-message sentiment trajectory                             |
| `GET`  | `/api/v1/conversations/{id}/outcome-prediction` | Get live outcome / predicted-CSAT scoring for an open conversation   |

## Lifecycle

| Method  | Path                                        | Purpose                                                 |
| ------- | ------------------------------------------- | ------------------------------------------------------- |
| `POST`  | `/api/v1/conversations/{id}/reply`          | Reply in the conversation's channel                     |
| `POST`  | `/api/v1/conversations/{id}/close`          | Close (resolved)                                        |
| `POST`  | `/api/v1/conversations/{id}/snooze`         | Snooze until a future time                              |
| `POST`  | `/api/v1/conversations/{id}/reopen`         | Reopen a closed or snoozed conversation                 |
| `PUT`   | `/api/v1/conversations/{id}/tags`           | Replace the tags array                                  |
| `PATCH` | `/api/v1/conversations/{id}/priority`       | Set the manual-triage priority flag (no notifications)  |
| `POST`  | `/api/v1/conversations/{id}/escalate`       | Escalate — notify your configured escalation recipients |
| `POST`  | `/api/v1/conversations/{id}/resume-channel` | Continue the same thread on a different channel         |
| `POST`  | `/api/v1/conversations/bulk`                | Apply one action across many conversation IDs           |

## Assignment & routing

| Method | Path                                            | Purpose                                                  |
| ------ | ----------------------------------------------- | -------------------------------------------------------- |
| `POST` | `/api/v1/conversations/{id}/assign`             | Assign to an agent (or unassign)                         |
| `POST` | `/api/v1/conversations/{id}/assignment/accept`  | Accept a conversation the router offered you             |
| `POST` | `/api/v1/conversations/{id}/assignment/decline` | Decline an offer and re-route to the next best-fit agent |

`assign` targets an individual agent only — pass `agent_id: null` to unassign. To route a conversation into a team's queue instead of to one person, use `handoff` with a `target_queue`; omit it to place the conversation in the org-wide queue.

## AI handoff & copilot

For AI-led conversations, Orbit provides explicit handoff mechanics so a human agent picks up exactly where the AI left off.

| Method | Path                                                | Purpose                                               |
| ------ | --------------------------------------------------- | ----------------------------------------------------- |
| `POST` | `/api/v1/conversations/{id}/copilot/suggest`        | Suggest the next reply + next-best actions            |
| `POST` | `/api/v1/conversations/{id}/handoff`                | Hand off from AI to a human agent                     |
| `POST` | `/api/v1/conversations/{id}/handoff/resolve`        | Mark a handoff resolved (closes the AI pause)         |
| `GET`  | `/api/v1/conversations/{id}/handoff/queue-position` | Get the customer's live queue position                |
| `GET`  | `/api/v1/conversations/{id}/handoff/packet`         | Get the full handoff packet for the human taking over |
| `POST` | `/api/v1/conversations/{id}/agent/resume`           | Resume the AI agent after a human-in-the-loop pause   |
| `GET`  | `/api/v1/conversations/{id}/agent/active`           | Read whether the AI agent is currently active         |

## Custom fields, translation & sharing

| Method  | Path                                                  | Purpose                                                  |
| ------- | ----------------------------------------------------- | -------------------------------------------------------- |
| `GET`   | `/api/v1/conversations/{id}/custom-fields`            | Get the conversation's custom-field values               |
| `PUT`   | `/api/v1/conversations/{id}/custom-fields`            | Replace the conversation's custom-field values           |
| `PATCH` | `/api/v1/conversations/{id}/auto-translate`           | Pin a customer locale for always-on outbound translation |
| `POST`  | `/api/v1/conversations/{id}/messages/{mid}/translate` | Translate a single message to a target language          |
| `POST`  | `/api/v1/conversations/{id}/share`                    | Mint a time-limited, read-only public transcript link    |

## Merge & link

| Method   | Path                                        | Purpose                                       |
| -------- | ------------------------------------------- | --------------------------------------------- |
| `POST`   | `/api/v1/conversations/{id}/merge`          | Merge sibling conversations into this one     |
| `POST`   | `/api/v1/conversations/{id}/unmerge`        | Undo a recent merge (30-minute window)        |
| `POST`   | `/api/v1/conversations/{id}/links`          | Link a related conversation (without merging) |
| `GET`    | `/api/v1/conversations/{id}/links`          | List linked conversations                     |
| `DELETE` | `/api/v1/conversations/{id}/links/{linkId}` | Remove a conversation link                    |

## Followers

| Method   | Path                                            | Purpose                 |
| -------- | ----------------------------------------------- | ----------------------- |
| `POST`   | `/api/v1/conversations/{id}/followers`          | Follow a conversation   |
| `GET`    | `/api/v1/conversations/{id}/followers`          | List followers          |
| `DELETE` | `/api/v1/conversations/{id}/followers/{userId}` | Unfollow a conversation |

## Side conversations

Loop an external vendor or subject-matter expert into a child thread tied to the parent conversation, without exposing it to the customer.

| Method | Path                                                              | Purpose                             |
| ------ | ----------------------------------------------------------------- | ----------------------------------- |
| `POST` | `/api/v1/conversations/{id}/side-conversations`                   | Start a side conversation           |
| `GET`  | `/api/v1/conversations/{id}/side-conversations`                   | List side conversations             |
| `GET`  | `/api/v1/conversations/{id}/side-conversations/{sideId}/messages` | Get a side-conversation thread      |
| `POST` | `/api/v1/conversations/{id}/side-conversations/{sideId}/reply`    | Reply in a side conversation        |
| `POST` | `/api/v1/conversations/{id}/side-conversations/{sideId}/resolve`  | Resolve a side conversation         |
| `POST` | `/api/v1/conversations/{id}/side-conversations/{sideId}/reopen`   | Reopen a resolved side conversation |

## Example — reply on whatever channel the conversation is on

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_abc/reply \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Thanks — I just refunded that order." }'
```

The reply is sent over the same channel the conversation is on (SMS, WhatsApp, email, …). For WhatsApp specifically, the 24-hour customer-care window is enforced — if the contact hasn't messaged you in 24 hours, the API will return a `WHATSAPP_OUTSIDE_24H_WINDOW` error and you'll need to send an approved template via the [Messaging API](/api-reference/endpoints/messaging) instead.

## See also

* [Conversations endpoint reference](/api-reference/endpoints/conversations) — every endpoint with full request/response schemas and code samples
* [Inbox API](/api-reference/inbox) — collaboration, saved views, routing rules, macros
* [Webhooks → conversation events](/webhooks/events)