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

{
  "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"
    }
  }
}

​

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

​

Common errors

• 404 PARTICIPANT_NOT_IN_CONFERENCE — the human_participant_call_sid does not belong to a conference on your account. Re-read the leg id from your own active call.
• 409 CALL_TERMINAL — the call already ended. Handback is only valid on a live call.
• 409 NOT_HUMAN_HANDLED — the call is not currently answered by a human agent; there is nothing to hand back.
• 422 validation error — reason and conference_id are required; conference_id must match conf_ plus 32 hex characters.
• 422 ai_agent_id required — the call has no prior AI-escalation to infer the agent from, so send it explicitly.

​

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