Handoffs

Overview

A handoff is a conversation that needs a real person. The queue is every conversation in your tenant whose status is escalated, across WhatsApp, web chat and voice.

A conversation enters the queue when:

• your agent hands off to a human during a conversation (raised_by: "ai", with a reason, and on voice a summary brief);
• a teammate takes a thread over by turning the bot off with POST /api/v1/conversations/{conversation_id}/autoreply and enabled: false (raised_by: "human");
• you set the conversation's status to escalated with PUT /api/v1/conversations/{conversation_id}/status (no reason or raised_by is recorded).

When your agent hands off or a teammate takes over, the bot stops auto-replying on that conversation (ai_autoreply_enabled: false on the conversation). Setting the status to escalated with PUT …/status only puts the conversation in the queue; it does not turn the bot off. Resolving the handoff takes it off the queue and, by default, hands the thread back to the bot.

Handoffs are conversations, so there is no create or delete endpoint here, and the path id is the conversation_id.

Authentication

Authorization: Bearer cm_your_api_key

Enumerations

The handoff object

{
  "conversation_id": "c0ffee00-1111-2222-3333-444455556666",
  "channel": "voice",
  "status": "escalated",
  "external_id": "+919812345678",
  "contact_name": "Asha Rao",
  "reason": "Customer wants to dispute a charge",
  "summary": "Caller was double-charged on order A-4419 and wants a refund. Identity verified.",
  "voice_session_id": "5e6f…",
  "can_callback": true,
  "raised_by": "ai",
  "escalated_at": "2026-08-17T06:10:00Z",
  "assignee": { "id": "b1f2…", "name": "Ravi Kumar" },
  "last_message": "Can I talk to a person please?",
  "last_message_at": "2026-08-17T06:09:41Z",
  "bot_id": "7a8b…"
}

GET /api/v1/handoffs

Returns an array of handoff objects, ordered by the conversation's last update, newest first.

curl "https://api.callmissed.com/api/v1/handoffs?scope=open&limit=100" \
  -H "Authorization: Bearer cm_your_api_key"

Any scope other than open or all returns 422.

GET /api/v1/handoffs/count

The number of open handoffs (conversations currently escalated).

curl https://api.callmissed.com/api/v1/handoffs/count \
  -H "Authorization: Bearer cm_your_api_key"

{ "count": 3 }

POST /api/v1/handoffs/{conversation_id}/assign

Give a handoff an owner, or send it back to the unclaimed pool.

A JSON body is required; send {} to unassign.

curl -X POST https://api.callmissed.com/api/v1/handoffs/c0ffee00-1111-2222-3333-444455556666/assign \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "assignee_id": "b1f2c3d4-1111-2222-3333-444455556666" }'

Returns the updated handoff object.

The claim conflict applies only to a signed-in teammate assigning a handoff to themselves. A request made with an API key is treated as a deliberate reassignment and replaces any current assignee.

POST /api/v1/handoffs/{conversation_id}/resolve

Take the conversation off the queue. Its status becomes active (the conversation can carry on), the assignee is cleared, and the handoff record is kept and marked resolved, so it still shows under scope=all.

A JSON body is required; send {} to accept the default.

curl -X POST https://api.callmissed.com/api/v1/handoffs/c0ffee00-1111-2222-3333-444455556666/resolve \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "resume_ai": true }'

Returns the updated handoff object. 404 Conversation not found.

This endpoint does not check that the conversation is currently escalated: calling it on any conversation in your tenant sets that conversation to active.

POST /api/v1/handoffs/{conversation_id}/callback

One-click call-back for a voice handoff. CallMissed dials your operator phone first, then the customer, and connects the two directly — no AI on the call. Both legs are placed from one of your own active numbers. No request body.

Before calling it, check can_callback on the handoff. The preconditions are:

• the handoff is on the voice channel and a customer phone number was captured for it;
• an operator phone number is set for your workspace in the console (Settings);
• your workspace has at least one active CallMissed number to call from.

curl -X POST https://api.callmissed.com/api/v1/handoffs/c0ffee00-1111-2222-3333-444455556666/callback \
  -H "Authorization: Bearer cm_your_api_key"

{
  "status": "calling",
  "room_name": "bridge-…",
  "operator_call_id": "0d1e…",
  "caller_call_id": "2f3a…"
}

This endpoint spends credits. Each leg is an outbound call billed like any other telephony call: credits are reserved for both legs before dialling and settled to the real cost after the calls end. If either leg fails to dial, both reservations are refunded.

A failure while dialling returns an error status with a message that is safe to show to your operator.

Errors

Only /callback consumes credits; nothing else on this page does.