Return an escalated call to the AI agent (handback)

​

Prerequisites

• A live, non-terminal call that is currently answered by a human agent (one that was escalated from the AI earlier, or answered by a person directly).
• The call’s conference_id (the escalation creates the conference the human and caller now share).
• The AI agent’s id — optional: if omitted, the handback re-invites the same AI agent that originally escalated, read from the call’s handoff record. Supply ai_agent_id only when a call was human-answered from the start, or when you want a different agent to resume.

​

Hand the call back

curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls/call_9f2c4a/handback \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conference_id": "conf_9d31f2a57c0e4a1b8e6d5c4b3a2f1e0d",
    "reason": "refund approved, returning caller to the assistant",
    "human_participant_call_sid": "CA7f2e9b1d4c4f9a8e6d2b0a1c3e5f7a9b"
  }'

​

Request fields

{
  "data": {
    "call_id": "call_9f2c4a",
    "ai_agent_row_id": "conf_ai_1d2e3f",
    "call_sid": "CA7f2e9b1d4c4f9a8e6d2b0a1c3e5f7a9b",
    "bot_answered": true,
    "human_dropped": true,
    "handback": {
      "reason": "refund approved, returning caller to the assistant",
      "handback_count": 1,
      "resumed_at": "2026-08-21T14:02:11.000Z"
    }
  }
}

​

Node SDK

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

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

const result = await orbit.request(
  "POST",
  "/voice/calls/call_9f2c4a/handback",
  {
    conference_id: "conf_9d31f2a57c0e4a1b8e6d5c4b3a2f1e0d",
    reason: "refund approved, returning caller to the assistant",
    human_participant_call_sid: "CA7f2e9b1d4c4f9a8e6d2b0a1c3e5f7a9b",
  },
);

console.log(result.data.bot_answered, result.data.human_dropped);

​

What the AI agent resumes with

• everything it captured before escalating (collected details like an order number or verified identity), and
• the full merged conversation — the bot leg plus the human leg — so nothing the caller told the human has to be repeated.

​

The human never leaves the caller alone

​

Every handback is recorded

​

Error matrix

​

Edge cases

• Double handback counts up. A call can bounce between AI and human any number of times. Every successful handback appends one round-trip to handback_count, starting at 1.
• Racing a hangup. If the caller hangs up after the request checks pass but before the handback completes, the response is still 202 — the call was live at lookup time. A repeat request once the call has ended fails 409 (CALL_TERMINAL) with the final call state in details.status.
• Monitor-only re-invite. With human_participant_call_sid omitted, the AI rejoins but nothing is dropped — a supervisor can keep listening. The response reports human_dropped: false.
• AI fails to answer. When the re-invited agent does not confirm within the answer window, the human leg is retained and the response carries bot_answered: false, human_dropped: false. Retry the handback — the round-trip counter and audit are written even for a failed answer.
• Empty reason is rejected. A blank reason fails the same 422 path as a malformed conference_id.

​

Cross-references

• Escalate the other way (AI to human) via handoff targets: Handoff Targets
• Voice channel reference: Channels → Voice
• Voice API reference: API → Voice & Numbers