Warm transfer to a human

A warm transfer moves a live caller from the agent to a real person, after the agent has gathered who is calling and why. Use it when a request is out of scope, the caller is frustrated, or a rule says a human must take over. The agent stays in control right up to the moment it connects the call. All paths are relative to https://builder.flowyte.com/api/v1.

Authenticate with Authorization: Bearer flowyte_sk_…. Destination numbers are saved in E.164 (e.g. +14155550100); a 10-digit US number is normalized on save.

There are two pieces, and most agents use both:

Handoff config on the agent — a default destination plus a “transfer by context” table that routes described situations to specific numbers.
A transfer skill — a tool the agent calls mid-conversation to move the caller to a fixed number, which you can gate with a spoken confirmation.

What you’ll use

Action	Endpoint	Scope
Set default + by-context handoff	`PATCH /agents/{id}`	`agents:write`
Add a transfer skill	`POST /agents/{id}/skills`	`skills:write`
List an agent’s skills	`GET /agents/{id}/skills`	`skills:read`
Publish the change	`POST /agents/{id}/publish`	`agents:write`

Set the handoff config

The agent’s handoffConfig holds a default transferDestination and a transferRules table. Each rule has a plain-language when the agent matches against, plus a destination. Set warm: true so the agent summarizes the caller and the reason before connecting, rather than a silent hand-off.

curl -X PATCH https://builder.flowyte.com/api/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handoffConfig": {
      "warm": true,
      "transferDestination": "+14155550100",
      "transferRules": [
        { "label": "Billing", "when": "caller asks about an invoice, charge, or refund", "destination": "+14155550111" },
        { "label": "Spanish line", "when": "caller prefers Spanish", "destination": "+14155550122" }
      ]
    }
  }'

await fetch(`https://builder.flowyte.com/api/v1/agents/${agentId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.FLOWYTE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    handoffConfig: {
      warm: true,
      transferDestination: "+14155550100",
      transferRules: [
        { label: "Billing", when: "caller asks about an invoice, charge, or refund", destination: "+14155550111" },
      ],
    },
  }),
});

The default transferDestination is used whenever a transfer is needed and no rule matches.

Add a transfer skill for explicit handoffs

A transfer skill is a tool the agent can call on demand. Its description is what the agent reads to decide when to use it — write it as the condition. Set requiresConfirmation so the agent confirms before transferring, and stakes to tune that gate.

curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/skills \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transfer to billing",
    "description": "Transfer the caller to a billing specialist when they ask about an invoice, charge, or refund.",
    "skillType": "transfer",
    "executionConfig": { "destination": "+14155550111" },
    "requiresConfirmation": true,
    "stakes": "medium"
  }'

A data-lookup skill can pass a dynamic destination at call time (e.g. route to the rep who owns the account), instead of a fixed number — useful for franchises and large rosters.

Publish

Edits change the draft. Phone and chat serve the last published version, so publish to make the transfer behavior live.

curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/publish \
  -H "Authorization: Bearer $FLOWYTE_API_KEY"

Choosing when a transfer fires

By context — the when text on each rule and the description on a transfer skill are how the agent decides; keep them specific.
On silence — set callControl.onNoResponseAction to transfer so an unresponsive caller is routed to a person instead of being ended.
After hours — by default the agent does not transfer to a live person when closed. Set afterHours.allowHumanTransfer and a number to allow it. See After hours.

The call is transferred off-net over the carrier (a blind SIP REFER), with the original caller ID passed through. Verify the destination number is one you control and is staffed during the hours the rule can fire.

Related: Skills · Draft vs published

Get started

Concepts

Channels

Integrations

Guides

Trust & Security

Warm transfer to a human

What you’ll use

Choosing when a transfer fires

​What you’ll use

​Choosing when a transfer fires

What you’ll use

Choosing when a transfer fires