Transfer

The transfer operation hands a phone caller to a person at a fixed phone number. Put it at the end of a tool the model calls when the caller needs a human. To move the call to another agent, use a handoff instead.

{
  "kind": "transfer",
  "config": { "destination": "+14155550101", "mode": "cold" }
}

Phone calls only. On a web call, text conversation or media stream the operation fails with transfer is only available on phone calls; on a WhatsApp call it fails with “calls on WhatsApp can’t be transferred to a phone number”. Publishing does not catch this, because the same tool can be attached to a phone agent and a chat agent.

A complete transfer tool

One argument-free tool per destination: a say, then the transfer, with disable_interruptions on.

curl -X POST https://api.talqing.com/v1/tools \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "transfer_to_billing",
    "description": "Put the caller through to a person on the billing team. Use only after you have tried to answer yourself and the caller has asked for a person, or the question is about a charge you cannot see. Do not use it for delivery or returns questions.",
    "json_schema": {},
    "disable_interruptions": true,
    "operations": [
      { "kind": "say", "config": { "text": "Putting you through to billing now — one moment." } },
      {
        "kind": "transfer",
        "config": {
          "destination": "+14155550101",
          "mode": "cold",
          "ringing_timeout": 30,
          "on_failure": "continue"
        }
      }
    ]
  }'

const tool = await talqing.tools.create({
  createToolRequest: {
    name: "transfer_to_billing",
    description:
      "Put the caller through to a person on the billing team. Use only after you have tried to answer yourself and the caller has asked for a person, or the question is about a charge you cannot see. Do not use it for delivery or returns questions.",
    json_schema: {},
    disable_interruptions: true,
    operations: [
      { kind: "say", config: { text: "Putting you through to billing now — one moment." } },
      {
        kind: "transfer",
        config: {
          destination: "+14155550101",
          mode: "cold",
          ringing_timeout: 30,
          on_failure: "continue",
        },
      },
    ],
  },
});

await talqing.tools.publish({
  tool_id: tool.id,
  publishToolRequest: { changelog: "Billing escalation" },
});

tool = talqing.tools.create(
    name="transfer_to_billing",
    description=(
        "Put the caller through to a person on the billing team. Use only after "
        "you have tried to answer yourself and the caller has asked for a person, "
        "or the question is about a charge you cannot see. Do not use it for "
        "delivery or returns questions."
    ),
    json_schema={},
    disable_interruptions=True,
    operations=[
        {"kind": "say", "config": {"text": "Putting you through to billing now — one moment."}},
        {
            "kind": "transfer",
            "config": {
                "destination": "+14155550101",
                "mode": "cold",
                "ringing_timeout": 30,
                "on_failure": "continue",
            },
        },
    ],
)

talqing.tools.publish(tool["id"], changelog="Billing escalation")

Publish the tool, attach it to the agent, and publish the agent.

Configuration

Field	Type	Default	Meaning
`destination`	string, required	—	A literal number in full international format, e.g. `+14155550101`.
`mode`	`cold` \| `warm`	`cold`	`cold` connects the caller straight away; `warm` has the agent brief the person first.
`ringing_timeout`	number, 5–120	`30`	Seconds the destination may ring before the attempt fails.
`on_failure`	`continue` \| `end_call`	`continue`	What happens when the transfer does not connect.

destination is frozen into the published tool version. It is never templated and never chosen by the model, so a caller cannot talk the agent into dialling a premium-rate number. {{args.number}} is refused at save, and so is a number that is not already canonical: 4155550101 is refused with the +1… form we think you meant. For several destinations, build one tool per destination.

Cold and warm

	`cold`	`warm`
Caller hears	Hold music while the destination rings, then the person	Hold music through the ring and the briefing, then the person
Person answering gets	The caller, with no introduction	The agent first: who is calling and why, and can ask questions
Person can refuse	No	Yes — the caller comes back to the agent
Extra cost	None	The briefing is a second STT + LLM + TTS conversation on your provider keys, billed to this call

While the caller is on hold their microphone and speaker are off, so nothing is transcribed or billed for a “hello?” into the ring. Hold time is inside the call’s duration, recording and bill. On warm, the briefing may run 90 seconds after the person answers. The held caller’s line drops after 120 seconds without audio from them, and the ring and the briefing both count: the default 30 + 90 lands exactly on 120. If you raise ringing_timeout, keep it small or the held caller can be dropped.

The person answering sees your workspace’s number, not the caller’s. The leg to them is dialled from your carrier trunk, which can only present a number you own; this cannot be set per transfer. Use warm, or write the caller’s details where the person will look.

When it does not connect

on_failure: continue brings the caller off hold and back to the agent, which is told one plain-English reason and instructed to say so and keep helping. on_failure: end_call ends the call as an end_call would.

What happened	What the agent is told
Busy	”the line was busy”
Rang out	”nobody answered”
Number not in service	”that number could not be reached”
`warm`: they declined	”they aren’t able to take the call right now”
`warm`: reached voicemail	”the call went through to their voicemail”
Anything else, including trunk or authorization faults on your side	”the transfer could not be completed”

A carrier status code is never spoken. On a declined warm transfer, the person’s own words go to the call timeline, never to the caller.

Writing the tool

Put a say before the transfer. There is no message field. You do not need wait_for_playback: the transfer waits for queued speech before it dials. Word it for the mode — “Putting you through now” for cold, “Let me speak to them first and bring you in” for warm. Promising a briefing before a cold transfer lands the caller on a stranger.
Turn on disable_interruptions. The caller hears only ringback for up to ringing_timeout, and talking into it would otherwise cut off the line that tells them what happened.
One tool per destination. transfer_to_billing, transfer_to_sales and transfer_to_support, each argument-free, beat one tool with a department argument: the model picks a tool more reliably than an enum value, and each destination gets its own description.
The description is the escalation policy. “Transfer to a human” invites the model to escalate at the first difficulty. Say when to use it and when not to, as in the example above.

Where it is refused

Shape	Refused at	Message
A `long_running_task` tool containing a `transfer`	Tool publish	`a long-running task cannot contain a transfer`
A tool containing a `transfer` used as an `on_enter` / `on_exit` / `on_user_turn_completed` hook	Agent publish	`the 'on_enter' hook cannot use tool '…': it contains a transfer`

Both run outside the turn that asked for the transfer, so the agent could not finish speaking before the handover.

After the transfer

Once the transfer connects the agent leaves. Talqing’s platform fee and recording stop there; the caller and the person stay connected on your carrier account, and that time is on your carrier’s invoice until either of them hangs up. A bridged call nobody hangs up is ended at the three-hour cap.

Where	What you see
`close_reason`	`transferred`. A completed call: billed the platform fee and eligible for call analysis.
`session.transfer` on `GET /v1/calls/{session_id}`	`mode`, `destination`, `outcome` (`connected` \| `failed`), `detail` (what the agent was told; null when connected), `sip_status` (the carrier’s raw verdict, for support), `on_failure` (null when connected), `at`.
Call timeline	Hold start and end; on `warm`, a `transfer.briefing` event with everything the agent told the person, and their reason if they declined.
Transcript	Nothing from the briefing — it was a different conversation.

Treat transfer.briefing as a compliance record: it is the only record of what your agent said about a customer to a third party.

Close reasons

Where transferred sits among every way a call can end.

Handoff operation

Moving the call to another agent instead of a person.

Patterns

The escalation recipe and other complete tools.

Get started

Build

Guides

A complete transfer tool

Configuration

Cold and warm

When it does not connect

Writing the tool

Where it is refused

After the transfer

Next

Close reasons

Handoff operation

Patterns

​A complete transfer tool

​Configuration

​Cold and warm

​When it does not connect

​Writing the tool

​Where it is refused

​After the transfer

​Next

Close reasons

Handoff operation

Patterns

A complete transfer tool

Configuration

Cold and warm

When it does not connect

Writing the tool

Where it is refused

After the transfer

Next