Transfer call

Hands the call off to another phone number or extension. The flow ends as soon as it's connected. Use 'Dial number' instead if you want a voicemail fallba…

What it does

Hands the call off to another phone number or SIP destination using Telnyx's transfer command and removes the platform from the conversation. This is fundamentally different from Dial: a successful dial leaves the platform in the bridge so it can keep observing and acting on the call, while a transfer is a one-way handoff. Once the destination picks up, the flow has nothing left to do — there's no onCalleeAnswered trigger chain, no auto-record, no whisper opportunity, no further node transitions.

Optionally, you can play a one-shot greeting (audioUrl) to the destination the instant they answer — useful for "Connecting transfer from Acme" notices so the receiving party doesn't pick up cold. The caller's from and fromDisplayName show on the destination's caller ID. If the destination doesn't answer within timeoutSecs, the call ends — there is no voicemail fallback, because the platform has already let go of the leg. If you need a fallback path on no-answer, use Dial instead and wire on['call.hangup'] to your voicemail step.

When to use it

• Forward a department line to an external 1-800 answering service during off-hours and let the platform get out of the way
• Hand off a screened call to a personal cell once you've collected who's calling and confirmed they should go through
• Route a SIP call to another carrier or a third-party IVR you don't control, and where you have no use for the bridge afterwards
• Implement a "press 9 to reach the operator" express path where you don't need recording, screen pops, or queue accounting after the handoff
• Pass a call to a partner's PBX over SIP without consuming an agent seat or a queue slot on your side

Configuration

Hands the call off to another phone number or extension. The flow ends as soon as it's connected. Use 'Dial number' instead if you want a voicemail fallback when no one answers.

Outgoing events: call.bridged, call.hangup

Examples

Plain transfer to an external number

The flow ends as soon as Telnyx accepts the transfer command. No voicemail fallback — that's what dial is for.

{
  "id": "after-hours-forward",
  "type": "transfer",
  "config": {
    "to": "+18005551234",
    "from": "{{event.to}}",
    "timeoutSecs": 30
  },
  "on": { "call.hangup": "end" }
}

Transfer with a greeting played to the destination

The destination hears "Connecting a transfer from Acme support" the moment they pick up, before they're connected to the caller.

{
  "id": "warm-handoff",
  "type": "transfer",
  "config": {
    "to": "+15555550133",
    "fromDisplayName": "Acme Support",
    "audioUrl": "https://cdn.example.com/transfer-notice.mp3",
    "timeoutSecs": 25
  },
  "on": { "call.hangup": "end" }
}

Gotchas

• The flow is gone after the transfer. This node is marked terminal: true in the catalog. Once Telnyx accepts the transfer command, the platform is no longer in the conversation — no trigger chains fire, no recording auto-starts, no further node transitions run regardless of what edges you wire. If you need any of those things, use Dial.
• There is no voicemail fallback. If the destination doesn't answer or is busy, the call ends. The legacy "transfer with voicemail on no-answer" pattern is not supported — replace it with dial + on['call.hangup']: 'voicemail'.
• audioUrl plays to the destination, not the caller. The caller hears whatever Telnyx is playing on their leg (silence or ringback) until the bridge happens. The greeting audio fires on the destination leg right after they pick up.
• Caller-ID from defaults to your number, not the original caller's. If you want the destination to see the inbound caller's number, pass "from": "{{event.from}}" explicitly — otherwise they see the platform DID.
• A failed transfer surfaces as a worker log, not a flow event. If Telnyx rejects the transfer (bad SIP URI, blocked country, trunk issue), the error is logged but no call.hangup fires through the flow — the call may stay live with the platform still in the path. Watch the worker logs when developing new transfer destinations.