Transfer

What it does

Moves the caller to another destination and leaves this flow. Destination accepts every routing-target kind: a person's extension, a call queue (or a ring-group queue), another call flow, the AI receptionist, a voicemail box, an outside phone number, or hangup. Each part of the destination (kind / id / number) may itself be a template, so the target can be decided at call time (e.g. {{vars.transferTargetKind}} / {{vars.transferTarget}}).

Internal destinations (extension, queue, flow, receptionist, voicemail, hangup) have no outgoing edge — the call leaves this flow entirely and is routed exactly as if the caller had dialed that destination themselves: presence, ring order, forwards, voicemail, and the destination's own Call experience all apply, and the call can be transferred again from there. This also starts a new hop in the call's history — its own segment in the call's timeline, separate from whatever led into this node.

An outside number works differently: the platform dials it from here. If it answers, the platform's job is done. If it doesn't answer, is busy, refuses the call, or the dial policy rejects it, the flow continues on Failed — wire that to a voicemail box or another fallback. callerId controls what the outside number sees: the number the caller dialed (business, default), the original caller's number presented as a forwarded call (original), or one specific number of yours (number, paired with callerIdNumber).

When to use it

• Hand a caller to a specific person, queue, or the receptionist, and let everything downstream (voicemail, after-hours, forwards) behave exactly like a normal call to that destination
• Forward an after-hours line to an outside answering service, with Failed wired to a voicemail box so a missed transfer still gets a message
• Build a "press 9 for the operator" express path — wire destination to an extension or queue and you're done; there's nothing wired coming out of it
• Let an earlier node (an IVR menu, a Custom script, the AI receptionist) decide the destination at call time by templating destination off vars
• Re-present the original caller's number when forwarding to a partner or an on-call cell, instead of the business number

Configuration

Moves the caller to another destination and leaves this flow: a person's extension, a call queue (or ring group), another call flow, the AI receptionist, a voicemail box, or an outside number. An internal destination takes the call exactly as if the caller had dialed it — presence, ring order, voicemail and the Call experience all apply — and the transfer can happen again from there. A transfer to an extension hands the call to that extension: it runs however the extension is set up — its own ring, hold music, greeting and voicemail, or the call flow the extension is routed to. This flow's ring time, music and no-answer path do not apply; to ring someone and keep control of what happens if they don't answer, use Request agent instead. An outside number is dialed from here; if it does not answer, is busy or fails, the flow continues on the Failed edge (wire it to voicemail). Starts a new hop in the call's history.

Outgoing events: failed, call.hangup

Examples

Transfer to an extension

No outgoing edge needed — the call leaves the flow and rings the extension exactly as if dialed directly (ring order, Away, voicemail fallback, and so on).

{
  "id": "to-billing",
  "type": "transfer",
  "config": {
    "destination": { "kind": "extension", "id": "{{config.extensionId}}" }
  }
}

Forward to an outside number, fall back to voicemail on Failed

{
  "id": "after-hours-forward",
  "type": "transfer",
  "config": {
    "destination": { "kind": "number", "number": "+18005551234" },
    "callerId": "business",
    "timeoutSecs": "30"
  },
  "on": { "failed": "voicemail", "call.hangup": "end" }
}

Destination decided at call time

An earlier node stamps vars.transferTargetKind / vars.transferTarget (a queue id, say); the Transfer node just renders them.

{
  "id": "route-by-vars",
  "type": "transfer",
  "config": {
    "destination": {
      "kind": "{{vars.transferTargetKind}}",
      "id": "{{vars.transferTarget}}"
    }
  },
  "on": { "failed": "voicemail", "call.hangup": "end" }
}

Present the original caller's number to an on-call cell

{
  "id": "ring-my-cell",
  "type": "transfer",
  "config": {
    "destination": { "kind": "number", "number": "+15555550133" },
    "callerId": "original",
    "timeoutSecs": "20"
  },
  "on": { "failed": "voicemail", "call.hangup": "end" }
}

Gotchas

• Internal destinations have no outgoing edge. Extension, queue, flow, receptionist, voicemail, and hangup all leave the flow for good — don't expect a next or call.bridged handle to fire. failed and call.hangup only make sense for the outside-number case (failed never fires for an internal destination).
• callerIdNumber only matters when callerId is number. Leave it blank for business or original — it's ignored either way.
• The original caller's number is presented as a forwarded call, not a spoofed one — the destination's carrier sees it as a diversion, the same way any legitimate call-forwarding service does it.
• A transfer is a new hop, not a continuation. It shows up as its own segment in the call's history/reporting — useful for telling "caller reached agent A, then A transferred to B" apart from one long call.
• This node is status: beta. The shape above is final (docs/plans/call-routing-build/CONTRACT.md §9.4), but the walker runtime that implements the route redirect and the outside-number dial/failed edge lands in a later wave — treat flows built against it as not yet runnable until that ships.