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.

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

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

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 instead.

API Reference

All Endpoints

Conversations API

Conversations API

Read & inspect

Lifecycle

Assignment & routing

AI handoff & copilot

Merge & link

Followers

Side conversations

Example — reply on whatever channel the conversation is on

See also

​Conversations API

​Read & inspect

​Lifecycle

​Assignment & routing

​AI handoff & copilot

​Custom fields, translation & sharing

​Merge & link

​Followers

​Side conversations

​Example — reply on whatever channel the conversation is on

​See also

Conversations API

Read & inspect

Lifecycle

Assignment & routing

AI handoff & copilot

Custom fields, translation & sharing

Merge & link

Followers

Side conversations

Example — reply on whatever channel the conversation is on

See also