Transfer to a Human

Escalate a live call to a person with call.transfer(...). Pass { to } to forward the audio to a phone number over a SIP REFER. Or pass { agent } to re-attach the call to a different, human-backed agent in place. In both cases, the original sid continues to address the call. Recordings, CDRs, and analytics keyed on the sid stay intact. Every snippet assumes a configured Voice client:

TypeScript
Python

import { Voice } from "@clutchcall/sdk/voice";

const v = new Voice({
  baseUrl: "https://engine.clutchcall.dev",
  apiKey:  process.env.CLUTCHCALL_CREDENTIALS!,
  orgId:   "org_abc",
});

import os
from clutchcall.voice import Voice

v = Voice(
    base_url="https://engine.clutchcall.dev",
    api_key=os.environ["CLUTCHCALL_CREDENTIALS"],
    org_id="org_abc",
)

Forward the call to a person’s phone

Transfer to an E.164 number. The SIP gateway issues a REFER toward the target and emits a transferred lifecycle event. The same sid continues.

TypeScript
Python

const call = await v.calls.get({ sid });
await call.transfer({ to: "+15557654321" });   // SIP REFER to a desk phone

call = v.calls.get(sid=sid)
call.transfer(to="+15557654321")   # SIP REFER to a desk phone

call.transfer("+15557654321") (a bare string) is shorthand for { to: "+15557654321" } in the TypeScript SDK.

Hand a bot call to a human queue

When an AI agent decides that it needs a person, re-attach the call to a human-backed agent by id. The engine swaps the audio bridge to the new agent in place, with no off-net forwarding. The caller’s sid is preserved, so the transcript and recording continue on one record.

TypeScript
Python

// call started with agent: "triage-bot"; the bot asks to escalate
await call.transfer({ agent: "human-queue" });

# call started with agent="triage-bot"; the bot asks to escalate
call.transfer(agent="human-queue")

The target agent routes into your ACD skill queue. The ACD offers the call to the first available human agent, on a browser softphone or a registered SIP phone. When the agent accepts, the engine bridges the agent to the caller.

Full bot → human escalation

Originate with a triage bot. Then escalate on the bot’s cue. First try an in-platform human queue. If needed, fall back to forwarding to an on-call phone.

TypeScript
Python

async function escalate(to: string) {
  // 1. start with an AI triage agent
  const call = await v.calls.originate({
    to, from: "+15558675309", trunkId: "trunk_main",
    agent: "triage-bot",
  });

  // 2. bot decides a human is needed → re-attach to the human queue
  await call.transfer({ agent: "human-queue" });

  // 3. or, forward the live audio to an on-call agent's phone
  // await call.transfer({ to: "+15557654321" });

  return call.sid;   // unchanged across the handoff
}

def escalate(to: str) -> str:
    # 1. start with an AI triage agent
    call = v.calls.originate(
        to=to, from_="+15558675309", trunk_id="trunk_main",
        agent="triage-bot",
    )

    # 2. bot decides a human is needed → re-attach to the human queue
    call.transfer(agent="human-queue")

    # 3. or, forward the live audio to an on-call agent's phone
    # call.transfer(to="+15557654321")

    return call.sid   # unchanged across the handoff

Pass exactly one of to or agent. The Python SDK enforces the XOR and raises an error if you pass both or neither. The TypeScript SDK requires at least one.

Routing and accept are wired end-to-end. But the rich warm-handoff context is a product-level payload that you assemble in your app. This is the screen-pop of intent, qualification, and auth that the bot captured before the human hears audio. See AI ↔ human handoff for how the human agent subscribes to the live caller audio.

Confirm the transfer landed

transfer() returns when the control plane accepts the request, not when the target answers. Poll the call, or watch the transferred / cleared lifecycle events, to see how the transfer resolved.

TypeScript
Python

await call.transfer({ to: "+15557654321" });

const c = await v.calls.get({ sid });
console.log("post-transfer status:", c.status);

call.transfer(to="+15557654321")

c = v.calls.get(sid=sid)
print("post-transfer status:", c.status)

AI ↔ human handoff

The full warm-handoff flow: mirroring caller audio to a human agent leg.

Handoffs

How transfers, re-attach, and re-hosting fit the session model.

Call lifecycle

The transferred event and the rest of the CTI stream.

Outbound call

Originate the call that you will transfer.

Overview

Quickstart

Core Concepts

Build Guides

Agent Runtime

Transport to Web & Apps

Transport to Telephony

CTI (CSTA)

High Availability

Comparison & Benchmarks

Migration

Integrations

Observability

SDK Reference

API Reference

Troubleshooting

Cookbooks

Recipes

Forward the call to a person’s phone

Hand a bot call to a human queue

Full bot → human escalation

Confirm the transfer landed

AI ↔ human handoff

Handoffs

Call lifecycle

Outbound call

​Forward the call to a person’s phone

​Hand a bot call to a human queue

​Full bot → human escalation

​Confirm the transfer landed

​Related

AI ↔ human handoff

Handoffs

Call lifecycle

Outbound call

Forward the call to a person’s phone

Hand a bot call to a human queue

Full bot → human escalation

Confirm the transfer landed

Related