​

Continue a conversation on another channel

• From the inbox, with the Continue on another channel control on the conversation header.
• Over the API, with POST /conversations/{id}/resume-channel.

​

When to move a thread

• SMS to email for long-form. A customer texts in with a question that needs a document, a formatted list, or a detailed answer. SMS caps each reply at a few segments; moving the thread to email lets you send the full answer with attachments while the customer keeps one continuous thread.
• Voice to web chat for cobrowse. A caller needs you to walk them through your portal. Continuing onto web chat puts a shareable surface between you and the customer so you can cobrowse or exchange links without staying on the phone.
• RCS to SMS for coverage. A thread started on RCS, but the customer’s handset or carrier drops out of RCS coverage mid-conversation. Moving to SMS keeps the thread deliverable instead of dying on the richer channel.

​

From the inbox

• No identity on file — for example, “no email on file” when you pick Email. The fix is on the contact record, not in this dialog: open the contact, add the missing email address or phone number, then reopen the control. Web chat resolves identity down a chain — the visitor’s widget session id first, then their email, then their phone — so a greyed-out Web Chat means the contact has none of the three.
• Already on this channel — the conversation’s current channel renders greyed out as a no-op guard. If you intended a real change, you are looking at the wrong target; if the thread somehow ended up on the wrong channel earlier, moving it away and back is still allowed.

​

Over the API

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_abc123/resume-channel \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "target_channel": "web_chat",
    "reason": "Customer asked to switch to web chat"
  }'

{
  "data": {
    "id": "conv_abc123",
    "channel": "web_chat",
    "previous_channel": "sms",
    "channels": ["sms", "web_chat"],
    "agent_active": true,
    "agent_id": "agent_42",
    "already_on_channel": false
  }
}

​

What carries over, and what does not

• The conversation id and full transcript carry over. Every prior message — from every channel the thread has touched — stays in the same conversation and keeps loading in the inbox.
• Tags and assignees carry over. The move never re-routes ownership; whoever held the thread keeps it.
• The AI-agent session carries over. If an AI agent was handling the thread, the response’s agent_active: true and agent_id fields come back unchanged: the same agent keeps its session state and everything it already learned about the contact, and it does not re-introduce itself or start from scratch on the new channel.
• The default reply channel changes. Your next reply — and the agent’s next reply — goes out on the new channel without re-picking it each time.
• No message is sent by the move itself. Nothing notifies the customer automatically; if a context note helps, send one as a normal reply.

​

Failure modes and how to handle them

• already_on_channel: true (200, no error). You asked to continue on the channel the conversation is already on. Nothing changed. Detect it from the response body and skip any downstream bookkeeping — do not treat it as a move.
• MISSING_IDENTITY (400). The contact has no usable address for the target channel. error.details.missing_field names exactly what is missing (for example email address, or visitor session id when every web-chat fallback failed). Fix the contact record, then retry.
• CONVERSATION_TERMINAL (422). Closed, archived, or snoozed threads cannot be continued. Reopen the thread first, then move it.
• CHANNEL_NOT_REPLYABLE (422). You passed agent or video as the target. Those are labels for how a thread is viewed, not how a customer is reached, so they are rejected at validation. Stick to the channel enum above.

async function moveConversation(id: string, channel: string) {
  const res = await fetch(`/api/v1/conversations/${id}/resume-channel`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ target_channel: channel }),
  });
  const body = await res.json();

  if (res.ok) {
    return body.data.already_on_channel
      ? { moved: false } // repeat of the same move — nothing changed
      : { moved: true, conversation: body.data };
  }

  const code = body.error?.code;
  if (code === "MISSING_IDENTITY") {
    // body.error.details.missing_field names what to add on the contact
    throw new Error(`Contact is missing ${body.error.details.missing_field}`);
  }
  if (code === "CONVERSATION_TERMINAL") {
    throw new Error("Reopen the conversation before moving it");
  }
  if (code === "CHANNEL_NOT_REPLYABLE") {
    throw new Error(`"${channel}" is an inbox view label, not a reachable channel`);
  }
  throw new Error(body.error?.message ?? "resume-channel failed");
}

​

Patterns worth adopting

• Pre-flight the move from GET /contacts/{id}. The contact record carries phone and email; phone-shaped fields serve every phone-family channel (SMS, WhatsApp, RCS, voice, and the rest), while web chat accepts the email, or phone, or an active widget visitor session. Check before you call — if you are about to target email and the contact’s email is empty, fill it in first instead of catching the 400. This turns the missing-identity error from a runtime failure into a form-level validation in your own UI.
• Resume after voicemail. A caller who left a voicemail often cannot take another call. Move the thread to SMS or email so the follow-up lands on an asynchronous channel the customer actually answers, with the whole call history still attached.
• Restore the original channel when the detour ends. If you moved SMS → email to deliver a document, move back to SMS once it lands. Because a previously used channel stays in channels[], moving back is a normal move, not a special case — and the AI agent’s next automated reply goes back onto the customer’s preferred channel too.