Dial number

Calls out to a single phone number or SIP address and connects them with the caller. If the destination doesn't answer, the flow continues so you can fall…

What it does

Originates an outbound call leg to a single destination — either a phone number in E.164 form or a sip: URI — and bridges it to the caller as soon as the destination picks up. Unlike Transfer, the platform stays on the call after the bridge: any On agent answered / On callee answered trigger chains fire, recording can start automatically, and the flow follows the dial node's outgoing transitions on call.bridged and call.hangup.

While we're waiting for the destination to ring, you can play optional ringback or hold music to the caller (ringbackAudioUrl). Telnyx auto- replaces that playback with the bridged audio the moment the leg connects. If the destination doesn't answer within timeoutSecs, no one picks up, or the originate request itself fails, the flow follows on['call.hangup'] — that's where you wire your voicemail or fallback step. The dialed leg's control id is stamped onto state.bridgeLegCallControlIds so downstream nodes (whisper prompts, screen pops, recording controls) can target it.

When to use it

• Forward an inbound number to an external answering service or on-call cell phone with a voicemail fallback when no one picks up
• Reach a single SIP endpoint (a desk phone in a remote office, a paging speaker, a third-party IVR) — paste the sip: URI directly
• Loop in a supervisor by name with a custom caller-ID display so they see the original caller's number, not yours
• Build "warm transfer" flows where you need to keep control after the bridge — e.g. record the conversation, run an agent-whisper, or end the call programmatically. Use Transfer instead if you just want to hand off and walk away
• Implement a try-this-number-first fallback before falling through to Ring extensions

Configuration

Calls out to a single phone number or SIP address and connects them with the caller. If the destination doesn't answer, the flow continues so you can fall back to voicemail.

Outgoing events: call.bridged, call.hangup

Examples

Forward to an external number, fall back to voicemail

The classic "ring my cell, take a message if I miss it" pattern. The dial node is the body of the flow; the call.hangup edge is the safety net.

{
  "id": "ring-cell",
  "type": "dial",
  "config": {
    "to": "+15555550199",
    "from": "{{event.to}}",
    "timeoutSecs": 30,
    "ringbackAudioUrl": "https://cdn.example.com/ringback.mp3"
  },
  "on": { "call.bridged": "end", "call.hangup": "voicemail" }
}

Reach a SIP endpoint with custom caller-ID name

Pass through the inbound caller's number as the caller-ID so the desk phone's screen shows who's actually calling, not the platform DID.

{
  "id": "reception",
  "type": "dial",
  "config": {
    "to": "sip:reception@office.acme.com",
    "from": "{{event.from}}",
    "fromDisplayName": "External Caller",
    "timeoutSecs": 20
  },
  "on": { "call.bridged": "end", "call.hangup": "voicemail" }
}

Gotchas

• call.bridged: 'end' is a sentinel, not a hangup. Wiring the bridge edge to end tells the worker "this is the happy path — let the conversation run until a real hangup." It does not end the call when the bridge happens. The call is torn down by Telnyx when either party hangs up, and only then does the flow finish.
• Originate failures look like a hangup. If Telnyx rejects the originate (bad SIP URI, blocked country, no trunk capacity), no leg gets created and the flow follows on['call.hangup'] like a normal no-answer. Check the worker log for the underlying error.
• Ringback audio must be publicly reachable. Telnyx fetches the file server-side. Private URLs, expired signed links, or anything behind auth will fail silently and the caller hears dead air until the bridge takes over.
• The leg counts as a "callee", not an "agent". Because there's no extension binding for a raw to number, the bridge fires the onCalleeAnswered trigger chain rather than onAgentAnswered. Wire screen pops and CRM lookups to the right one.
• Templating renders once, at originate time. {{vars.x}} in to, from, or fromDisplayName is resolved when the dial node is entered. Mutating those vars later has no effect on a leg that's already ringing.