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.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.conversations.list();

Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

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

Worked request/response examples

Request and response envelopes side by side for the four operations an inbox integration calls first — reply, list the inbox, hand off to a human, and the bulk action. Each one pairs the curl call with the equivalent typed Node SDK call, and the response block shows the exact envelope the API returns, including meta.request_id and meta.pagination where it applies.

Reply to a conversation

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/reply \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your refund is on its way — 3-5 business days." }'

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: message } = await client.conversations.reply("conv_8a4", {
  body: "Your refund is on its way — 3-5 business days.",
});
console.log(message.id, message.status); // "msg_4fa0", "queued"

{
  "data": {
    "id": "msg_4fa0",
    "conversation_id": "conv_8a4",
    "channel": "sms",
    "to": "+1553201264",
    "body": "Your refund is on its way — 3-5 business days.",
    "status": "queued",
    "provider_response": { "sent_at": "2026-08-31T10:02:41Z" }
  },
  "meta": {
    "request_id": "req_90b2c1",
    "timestamp": "2026-08-31T10:02:41Z"
  }
}

A successful reply answers 202 Accepted: the message is queued onto the conversation and delivery continues asynchronously, so watch your message.delivered webhook or poll GET /:id/messages for the terminal state. The reply goes out on the conversation’s inbound channel unless you pass a channel override; a closed, snoozed, or archived conversation rejects the reply until you POST /:id/reopen.

List the inbox

Read the open queue with a channel filter, and page deeper with the cursor the response hands back.

curl "https://api.orbit.devotel.io/api/v1/conversations?status=open&channel=whatsapp&limit=25" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: inbox, meta } = await client.conversations.list({
  status: "open",
  channel: "whatsapp",
  limit: 25,
});
const nextCursor = meta.pagination?.cursor; // pass as `cursor` for page 2

{
  "data": [
    {
      "id": "conv_8a4",
      "contact_id": "ct_61e",
      "channel": "whatsapp",
      "status": "open",
      "unread_count": 2,
      "tags": ["refund"],
      "last_message_at": "2026-08-31T09:58:12Z",
      "created_at": "2026-08-31T09:41:03Z",
      "updated_at": "2026-08-31T09:58:12Z"
    },
    {
      "id": "conv_8b1",
      "contact_id": "ct_9d2",
      "channel": "whatsapp",
      "status": "open",
      "unread_count": 0,
      "tags": [],
      "last_message_at": "2026-08-31T09:22:47Z",
      "created_at": "2026-08-30T18:11:52Z",
      "updated_at": "2026-08-31T09:22:47Z"
    }
  ],
  "meta": {
    "request_id": "req_3d8f4",
    "timestamp": "2026-08-31T10:03:19Z",
    "pagination": { "cursor": "eyJsYXN0X21lc3NhZ2VfYXQiOiIyMDI2LTA4LTMx... ", "has_more": true }
  }
}

Filters are single-value params (status, channel, sentiment, unread, has_agent, search, …) — combine them in one query string. Page with limit plus the meta.pagination.cursor the previous page returned; when has_more is false the list is exhausted. The SDK’s client.conversations.iter() walks every page for you when you don’t want manual cursor handling.

Hand off to a human

handoff parks the AI and places the thread into a queue for a human operator; the response returns the handoff packet inline so the owner of the queue can greet the customer with context.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/handoff \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Refund needs manager approval",
    "reason_category": "policy_block",
    "target_queue": "tier-2-refunds"
  }'

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: conversation } = await client.conversations.handoff("conv_8a4", {
  reason: "Refund needs manager approval",
  reason_category: "policy_block",
  target_queue: "tier-2-refunds",
});
console.log(conversation.queue_position, conversation.est_wait_seconds);

{
  "data": {
    "id": "conv_8a4",
    "status": "pending",
    "needs_human": true,
    "agent_active": false,
    "handoff_reason": "Refund needs manager approval",
    "reason_category": "policy_block",
    "target_queue": "tier-2-refunds",
    "handoff_brief": "Refund acknowledged in-thread; amount exceeds the operator limit so a manager approval is required.",
    "matched_operator_count": 2,
    "matched_operators": [
      { "id": "usr_4c9", "name": "Marta K.", "overlap": 1 }
    ],
    "queue_position": 1,
    "est_wait_seconds": 90,
    "queue_length": 3
  },
  "meta": {
    "request_id": "req_51a9b2",
    "timestamp": "2026-08-31T10:04:05Z"
  }
}

While the handoff waits, GET /:id/handoff/queue-position returns the live position, and POST /:id/handoff/resolve marks it done. reason_category accepts cant_understand, policy_block, customer_request, tool_failed, escalation_threshold, or manual.

Bulk action across conversations

Apply one action — close, reopen, assign, add tags, remove tags — across a batch of conversation ids in a single call. The discriminator is action; assign needs agent_id, the tag actions need a tags list. Up to 200 ids per request.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/bulk \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_tags",
    "conversation_ids": ["conv_8a4", "conv_8b1", "conv_8b5"],
    "tags": ["refund-followup"]
  }'

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: result } = await client.conversations.bulk({
  action: "add_tags",
  conversation_ids: ["conv_8a4", "conv_8b1", "conv_8b5"],
  tags: ["refund-followup"],
});
console.log(result.succeeded, result.failed); // 3, 0

{
  "data": {
    "results": [
      { "id": "conv_8a4", "ok": true },
      { "id": "conv_8b1", "ok": true },
      { "id": "conv_8b5", "ok": true }
    ],
    "succeeded": 3,
    "failed": 0
  },
  "meta": {
    "request_id": "req_6ab114",
    "timestamp": "2026-08-31T10:05:02Z"
  }
}

The batch runs inside one transaction, so it is all-or-nothing: any per-id failure rolls the whole batch back and every entry in results reports ok: false with the error next to it, rather than leaving a partial state behind.

More worked samples

Worked request/response envelopes for the next operations an integration hits after the basics below: page a message thread, override the reply channel, tag and prioritize, answer a router offer, drive the conversation surface from webhooks, and loop in side-conversation participants. Each pairs the curl call with the typed Node SDK call, and every response block shows the exact envelope the API returns.

Page a conversation’s messages

The thread is oldest-newest by default; page with the participant_id filter when a side conversation or a monitor session scaffolds extra participants into one thread and you want one side’s view.

curl "https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/messages?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: messages, meta } = await client.conversations.listMessages("conv_8a4", {
  limit: 50,
});
const nextCursor = meta.pagination?.cursor; // pass as `cursor` for page 2

{
  "data": [
    {
      "id": "msg_9e01",
      "conversation_id": "conv_8a4",
      "direction": "inbound",
      "channel": "whatsapp",
      "from": "+1553301264",
      "to": "+1555000129",
      "body": "Where is my refund? It's been a week.",
      "status": "received",
      "sent_at": "2026-08-31T09:41:03Z"
    },
    {
      "id": "msg_9e07",
      "conversation_id": "conv_8a4",
      "direction": "outbound",
      "channel": "whatsapp",
      "from": "+1555000129",
      "to": "+1553301264",
      "body": "Your refund is on its way — 3-5 business days.",
      "status": "delivered",
      "sent_at": "2026-08-31T09:58:12Z"
    }
  ],
  "meta": {
    "request_id": "req_4b91d2",
    "timestamp": "2026-08-31T10:06:11Z",
    "pagination": { "cursor": "eyJpZCI6Im1zZ185ZTAxIn0=", "has_more": false }
  }
}

Operator actions (assignments, closes, merges) are NOT in this list — read those from GET /:id/activity. Internal notes live under the Inbox API, not the public thread.

Send a reply with a channel override

The reply goes out on the conversation’s inbound channel by default — pass channel to move the thread elsewhere (an email escalation on an SMS thread, a WhatsApp follow-up on a web-chat conversation). A closed conversation still rejects the reply until you POST /:id/reopen.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/reply \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Following up by email with the RMA details.",
    "channel": "email"
  }'

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: message } = await client.conversations.reply("conv_8a4", {
  body: "Following up by email with the RMA details.",
  channel: "email",
});
console.log(message.channel, message.status); // "email", "queued"

{
  "data": {
    "id": "msg_4fa7",
    "conversation_id": "conv_8a4",
    "channel": "email",
    "to": "customer@example.com",
    "body": "Following up by email with the RMA details.",
    "status": "queued",
    "provider_response": { "sent_at": "2026-08-31T10:06:59Z" }
  },
  "meta": {
    "request_id": "req_7c41a9",
    "timestamp": "2026-08-31T10:06:59Z"
  }
}

To move the whole thread onto another channel (so subsequent replies also start there), call POST /:id/resume-channel with { "channel": "email" } instead. To check which sender identity a reply will use before sending, GET /:id/reply-sender returns { channel, from, source }.

Tag and prioritize a conversation

There is no PATCH /api/v1/conversations/{id} on this surface — status moves are explicit lifecycle verbs (close, snooze, reopen, escalate, assignment accept/decline), and the granular writes use their own paths. Replace the tags array and set the manual-triage flag in two calls.

curl -X PUT https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/tags \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["refund", "priority-review"] }'

curl -X PATCH https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/priority \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent" }'

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

await client.conversations.updateTags("conv_8a4", { tags: ["refund", "priority-review"] });

const { data: conversation } = await client.conversations.updatePriority("conv_8a4", {
  priority: "urgent",
});
console.log(conversation.priority); // "urgent"

{
  "data": {
    "id": "conv_8a4",
    "tags": ["refund", "priority-review"],
    "priority": "urgent"
  },
  "meta": {
    "request_id": "req_2c88f1",
    "timestamp": "2026-08-31T10:08:14Z"
  }
}

PUT /tags replaces the whole array — send the full set, not a delta. The priority flag (none, low, medium, high, urgent) is a pure sort/filter marker: it never notifies anyone, matches the activity feed, and filters via GET /conversations?priority=urgent.

Answer a router offer

When the omnichannel router offers you a conversation, accept it to stamp the acceptance, or decline it so the router re-offers to the next best-fit agent (excluding everyone who already declined). The acting user must be the current assignee; a stale offer comes back as 422 ASSIGNMENT_OFFER_STALE.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/assignment/accept \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: assignment } = await client.conversations.acceptAssignment("conv_8a4");
console.log(assignment.assignment_state); // "accepted"

{
  "data": {
    "id": "conv_8a4",
    "assigned_to": "usr_4c9",
    "assignment_state": "accepted",
    "accepted_at": "2026-08-31T10:09:02Z"
  },
  "meta": {
    "request_id": "req_64d0b8",
    "timestamp": "2026-08-31T10:09:02Z"
  }
}

POST /:id/assignment/decline takes an empty body and returns the same shape with a next_offer summary when a replacement agent was found.

Drive the conversation surface from webhooks

The conversations surface emits message.received, message.delivered, conversation.created, conversation.updated, and the status lifecycle events (see the webhook events reference). Subscribe a tenant-owned endpoint, then watch the delivery stream. Events filter by exact type repeat param or a comma-separated list.

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://receiver.example.dev/webhooks",
    "events": ["message.received", "message.delivered", "conversation.updated"]
  }'

curl "https://api.orbit.devotel.io/api/v1/webhooks/" \
  -H "X-API-Key: dv_live_sk_your_key_here"

curl "https://api.orbit.devotel.io/api/v1/webhooks/deliveries?status=failed" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: endpoint } = await client.webhooks.create({
  url: "https://receiver.example.dev/webhooks",
  events: ["message.received", "message.delivered", "conversation.updated"],
});
console.log(endpoint.id, endpoint.signing_secret); // store the secret once

const { data: deliveries } = await client.webhooks.listDeliveries({
  status: "failed",
});

{
  "data": {
    "id": "wh_7e21",
    "url": "https://receiver.example.dev/webhooks",
    "events": ["message.received", "message.delivered", "conversation.updated"],
    "status": "active",
    "signing_secret": "whsec_live_9f2c...",
    "created_at": "2026-08-31T10:10:47Z"
  },
  "meta": {
    "request_id": "req_88b2e0",
    "timestamp": "2026-08-31T10:10:47Z"
  }
}

Delete with DELETE /api/v1/webhooks/{id} when the receiver rotates. A delivery that keeps failing lands in the DLQ — replay one with POST /api/v1/webhooks/dlq/{delivery_id}/replay once the receiver is healthy. Verify signatures per the webhook consumer guide.

Loop in side-conversation participants

Side conversations carry an external_participants array — each entry is a { label, email?, phone?, role? } object, the E.164 phone optional when email is the channel. Create or list the child threads without exposing them to the customer.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/side-conversations \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Carrier trace on a missing shipment",
    "external_participants": [
      {
        "label": "DHL claims desk",
        "email": "claims@dhl.example",
        "role": "vendor"
      }
    ]
  }'

curl "https://api.orbit.devotel.io/api/v1/conversations/conv_8a4/side-conversations" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: side } = await client.conversations.createSideConversation("conv_8a4", {
  subject: "Carrier trace on a missing shipment",
  external_participants: [
    { label: "DHL claims desk", email: "claims@dhl.example", role: "vendor" },
  ],
});
console.log(side.id); // "scv_2f9a"

{
  "data": {
    "id": "scv_2f9a",
    "parent_conversation_id": "conv_8a4",
    "subject": "Carrier trace on a missing shipment",
    "external_participants": [
      { "label": "DHL claims desk", "email": "claims@dhl.example", "role": "vendor" }
    ],
    "status": "open",
    "created_at": "2026-08-31T10:12:31Z"
  },
  "meta": {
    "request_id": "req_a1c482",
    "timestamp": "2026-08-31T10:12:31Z"
  }
}

Reply in the side thread with POST /:id/side-conversations/{sideId}/reply; inbound replies from the external party carry their label as the author. Resolve with .../{sideId}/resolve and reopen within the window with .../{sideId}/reopen.

Work through it end-to-end

Four worked flows a contact-center integration hits almost immediately: reply, handle the WhatsApp window error, call the same flow from the Node SDK, and kick off an AI → human handoff.

1. Reply on the conversation’s channel

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." }'

{
  "data": {
    "id": "msg_9f2c",
    "conversation_id": "conv_abc",
    "channel": "sms",
    "to": "+1553201264",
    "body": "Thanks — I just refunded that order.",
    "status": "queued",
    "provider_response": { "sent_at": "2026-08-25T14:32:10Z" }
  },
  "meta": {
    "request_id": "req_1e4f8d2",
    "timestamp": "2026-08-25T14:32:10Z"
  }
}

The reply goes out on the same channel the conversation is on (SMS, WhatsApp, email, …) unless you pass a channel override.

2. Handle the WhatsApp 24-hour window error

WhatsApp only accepts free-form messages within 24 hours of the contact’s last inbound message. Outside that window the reply returns 422 with a typed error envelope:

{
  "error": {
    "code": "WHATSAPP_OUTSIDE_24H_WINDOW",
    "message": "WhatsApp 24-hour customer-service window has expired. Use a pre-approved template message to re-engage this contact.",
    "status": 422,
    "details": {
      "hours_since_last_inbound": 31
    }
  },
  "meta": {
    "request_id": "req_1e4f8d2",
    "timestamp": "2026-08-25T14:32:10Z"
  }
}

The fix is to re-engage with an approved template through the Messaging API. Once the contact replies, the window is open again and free-form replies succeed.

3. Same flow from the SDKs

conversations is a covered resource in the Node SDK, so you don’t need raw fetch for the flow above:

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const { data: reply } = await client.conversations.reply("conv_abc", {
  body: "Thanks — I just refunded that order.",
});
console.log(reply.id, reply.channel, reply.status);

The SDK also exposes assign, handoff, resolveHandoff, getHandoffQueuePosition, copilotSuggest, updateTags, close, snooze, reopen, and merge with full typings.

4. Kick off an AI → human handoff

Call handoff when an AI-led conversation needs a human. The response returns the handoff packet inline — the clearance status, the auto-generated brief, the matched operators, and the customer’s live queue position — so the human picks up with full context.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_abc/handoff \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer asked for a supervisor",
    "reason_category": "customer_request",
    "target_queue": "tier-2-support",
    "skill_tags": ["billing", "english"]
  }'

{
  "data": {
    "id": "conv_abc",
    "assigned_to": null,
    "status": "pending",
    "needs_human": true,
    "agent_active": false,
    "handoff_reason": "Customer asked for a supervisor",
    "reason_category": "customer_request",
    "skill_tags": ["billing", "english"],
    "handoff_brief": "Customer asked twice about a duplicate charge; refund issued on the prior thread. Wants a supervisor confirmation.",
    "target_queue": "tier-2-support",
    "inbox_team_id": null,
    "matched_operator_count": 1,
    "matched_operators": [
      { "id": "usr_2ab", "name": "Priya N.", "overlap": 2 }
    ],
    "queue_position": 3,
    "est_wait_seconds": 245,
    "queue_length": 7
  },
  "meta": {
    "request_id": "req_7c2a9e1",
    "timestamp": "2026-08-25T14:33:02Z"
  }
}

While the handoff waits, GET /handoff/queue-position returns the live position, GET /handoff/packet returns the full packet again, and POST /handoff/resolve marks it done and closes the AI pause. To let the AI take the thread back, call POST /agent/resume.

Common operations

Four paired bash + Python snippets that cover the highest-traffic operator flows: filter the open inbox, reply and assign in one pass, escalate into a handoff, and read the sentiment timeline with the outcome prediction. All shapes here match the endpoint reference.

1. List the open inbox filtered by channel + sentiment

Filter with status=open, channel=whatsapp, and sentiment=negative — single-value params, no CSV needed.

curl "https://api.orbit.devotel.io/api/v1/conversations?status=open&channel=whatsapp&sentiment=negative" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import os, requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/conversations",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    params={"status": "open", "channel": "whatsapp", "sentiment": "negative"},
)
inbox = resp.json()["data"]

{
  "data": [
    {
      "id": "conv_7d1",
      "contact_id": "ct_99a",
      "channel": "whatsapp",
      "status": "open",
      "sentiment": "negative",
      "last_message_at": "2026-08-25T14:20:41Z"
    },
    {
      "id": "conv_7d2",
      "contact_id": "ct_31b",
      "channel": "whatsapp",
      "status": "open",
      "sentiment": "negative",
      "last_message_at": "2026-08-25T13:58:02Z"
    },
    {
      "id": "conv_7d3",
      "contact_id": "ct_4c2",
      "channel": "whatsapp",
      "status": "open",
      "sentiment": "negative",
      "last_message_at": "2026-08-25T13:11:19Z"
    }
  ],
  "meta": { "request_id": "req_9b71c0", "timestamp": "2026-08-25T14:21:05Z" }
}

2. Reply, then assign the conversation

Post the reply, then write the queue-tag. The two calls are independent — a failed reply should not block assignment.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_7d1/reply \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "I can see the duplicate charge — refunding it now." }'

curl -X PUT https://api.orbit.devotel.io/api/v1/conversations/conv_7d1/tags \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["billing-followup"] }'

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
base = "https://api.orbit.devotel.io/api/v1/conversations/conv_7d1"

reply = requests.post(
    f"{base}/reply",
    headers=headers,
    json={"body": "I can see the duplicate charge — refunding it now."},
)
tagged = requests.put(
    f"{base}/tags",
    headers=headers,
    json={"tags": ["billing-followup"]},
)

{
  "data": {
    "id": "conv_7d1",
    "tags": ["billing-followup"],
    "assigned_to": "usr_2ab"
  },
  "meta": { "request_id": "req_1e4f8d3", "timestamp": "2026-08-25T14:22:30Z" }
}

PUT /tags replaces the whole array, so send the full set. To assign to an agent instead of a tag, post assign with { "agent_id": "usr_2ab" } (or null to unassign).

3. Escalate, then hand off — read the packet before resuming

Escalation notifies your configured recipients; a handoff parks the AI and queues the thread for a human. Read GET /handoff/packet before posting /agent/resume so you hand the thread back with the resolution captured.

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_7d1/escalate \
  -H "X-API-Key: dv_live_sk_your_key_here"

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_7d1/handoff \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Supervisor requested", "reason_category": "customer_request" }'

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
base = "https://api.orbit.devotel.io/api/v1/conversations/conv_7d1"

requests.post(f"{base}/escalate", headers=headers)
handoff = requests.post(
    f"{base}/handoff",
    headers=headers,
    json={"reason": "Supervisor requested", "reason_category": "customer_request"},
)
packet = requests.get(f"{base}/handoff/packet", headers=headers).json()["data"]

{
  "data": {
    "id": "conv_7d1",
    "status": "pending",
    "needs_human": true,
    "agent_active": false,
    "handoff_reason": "Supervisor requested",
    "reason_category": "customer_request",
    "handoff_brief": "Duplicate charge confirmed; refund issued. Customer wants a supervisor sign-off.",
    "target_queue": null,
    "matched_operator_count": 1,
    "matched_operators": [{ "id": "usr_2ab", "name": "Priya N.", "overlap": 2 }],
    "queue_position": 3,
    "est_wait_seconds": 245,
    "queue_length": 7
  },
  "meta": { "request_id": "req_7c2a9e2", "timestamp": "2026-08-25T14:24:11Z" }
}

These packet fields are what a consumer reads before resuming: needs_human gates the resume call, handoff_brief is the human’s working context, and matched_operators / queue_position tell you who can take it and how long the customer waits.

4. Read the sentiment timeline and outcome prediction

Two reads, one conversation id in the path. The timeline returns the per-message trajectory oldest → newest; the prediction scores the live thread — resolution likelihood, escalation risk, and a predicted CSAT before any survey comes back.

curl https://api.orbit.devotel.io/api/v1/conversations/conv_7d1/sentiment-timeline \
  -H "X-API-Key: dv_live_sk_your_key_here"

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
base = "https://api.orbit.devotel.io/api/v1/conversations/conv_7d1"

timeline = requests.get(f"{base}/sentiment-timeline", headers=headers).json()["data"]

{
  "data": {
    "timeline": [
      { "message_id": "msg_9e01", "ts": "2026-08-25T14:18:12Z", "sentiment_score": -0.62, "sentiment_label": "negative" },
      { "message_id": "msg_9e07", "ts": "2026-08-25T14:21:45Z", "sentiment_score": -0.18, "sentiment_label": "negative" },
      { "message_id": "msg_9e12", "ts": "2026-08-25T14:24:03Z", "sentiment_score": 0.41, "sentiment_label": "positive" }
    ],
    "analysis_pending": false
  },
  "meta": { "request_id": "req_5aa1c03", "timestamp": "2026-08-25T14:25:44Z" }
}

curl https://api.orbit.devotel.io/api/v1/conversations/conv_7d1/outcome-prediction \
  -H "X-API-Key: dv_live_sk_your_key_here"

prediction = requests.get(f"{base}/outcome-prediction", headers=headers).json()["data"]

{
  "data": {
    "resolution_likelihood": 0.71,
    "escalation_risk": 0.18,
    "predicted_csat": 3.4,
    "confidence": 0.66,
    "drivers": ["recovering sentiment", "refund issued in-thread"],
    "recommended_action": "monitor"
  },
  "meta": { "request_id": "req_5aa1c04", "timestamp": "2026-08-25T14:25:46Z" }
}

The prediction short-caches for 90s and busts on each new message; ?refresh=1 forces a recompute. recommended_action is one of monitor, coach_agent, proactive_escalate, reassign, or offer_resolution — read it before deciding whether this thread needs a handoff at all.

API Reference

All Endpoints

Conversations API: reply, assign, and hand off threads

Conversations API

Using the SDKs

Read & inspect

Lifecycle

Assignment & routing

AI handoff & copilot

Merge & link

Followers

Side conversations

Worked request/response examples

Reply to a conversation

List the inbox

Hand off to a human

Bulk action across conversations

More worked samples

Page a conversation’s messages

Send a reply with a channel override

Tag and prioritize a conversation

Answer a router offer

Drive the conversation surface from webhooks

Loop in side-conversation participants

Work through it end-to-end

1. Reply on the conversation’s channel

2. Handle the WhatsApp 24-hour window error

3. Same flow from the SDKs

4. Kick off an AI → human handoff

Common operations

1. List the open inbox filtered by channel + sentiment

2. Reply, then assign the conversation

3. Escalate, then hand off — read the packet before resuming

4. Read the sentiment timeline and outcome prediction

See also

​Conversations API

​Using the SDKs

​Read & inspect

​Lifecycle

​Assignment & routing

​AI handoff & copilot

​Custom fields, translation & sharing

​Merge & link

​Followers

​Side conversations

​Worked request/response examples

​Reply to a conversation

​List the inbox

​Hand off to a human

​Bulk action across conversations

​More worked samples

​Page a conversation’s messages

​Send a reply with a channel override

​Tag and prioritize a conversation

​Answer a router offer

​Drive the conversation surface from webhooks

​Loop in side-conversation participants

​Work through it end-to-end

​1. Reply on the conversation’s channel

​2. Handle the WhatsApp 24-hour window error

​3. Same flow from the SDKs

​4. Kick off an AI → human handoff

​Common operations

​1. List the open inbox filtered by channel + sentiment

​2. Reply, then assign the conversation

​3. Escalate, then hand off — read the packet before resuming

​4. Read the sentiment timeline and outcome prediction

​See also

Conversations API

Using the SDKs

Read & inspect

Lifecycle

Assignment & routing

AI handoff & copilot

Custom fields, translation & sharing

Merge & link

Followers

Side conversations

Worked request/response examples

Reply to a conversation

List the inbox

Hand off to a human

Bulk action across conversations

More worked samples

Page a conversation’s messages

Send a reply with a channel override

Tag and prioritize a conversation

Answer a router offer

Drive the conversation surface from webhooks

Loop in side-conversation participants

Work through it end-to-end

1. Reply on the conversation’s channel

2. Handle the WhatsApp 24-hour window error

3. Same flow from the SDKs

4. Kick off an AI → human handoff

Common operations

1. List the open inbox filtered by channel + sentiment

2. Reply, then assign the conversation

3. Escalate, then hand off — read the packet before resuming

4. Read the sentiment timeline and outcome prediction

See also