{"slug":"swml-connect-verb","title":"SWML connect — Bridge to PSTN, SIP, or AI Platforms","tags":["signalwire","swml","connect","sip","byo-trunk"],"agent_summary":"The `connect` verb bridges the active call to a destination — PSTN, SIP URI, or AI platform endpoint. Covers basic forwarding, simultaneous and sequential dialing, whisper, answer_on_bridge, and SIP URI patterns for BYO trunks.","trigger_phrases":["SWML connect verb","bridge call to PSTN","forward call SIP","ring multiple numbers","answer_on_bridge","whisper before connect","BYO trunk SIP URI"],"runnable":true,"markdown":"\n# SWML `connect` Verb\n\n`connect` bridges the active call to one or more destinations. Destinations can be PSTN numbers (E.164), SIP URIs, or a mix. This is the verb that powers call forwarding, hunt groups, ring-all groups, and every BYO SIP integration.\n\n## Simplest case — forward to a phone\n\n```yaml\nversion: 1.0.0\nsections:\n main:\n - connect:\n to: \"+15555551234\"\n```\n\nInbound call is answered (implicitly) and bridged to `+15555551234`. The caller stays on the line until the destination hangs up.\n\n## Preserving caller ID\n\nBy default the inbound caller's number is forwarded. To override (for example to spoof your own DID), set `from`:\n\n```yaml\n- connect:\n from: \"+15559876543\"\n to: \"+15555551234\"\n```\n\nCaller ID rules apply: `from` must be a verified or owned number on your project.\n\n## Sequential dialing (hunt group)\n\nPass an array of destinations. The list is dialed in order, top to bottom, until one answers.\n\n```yaml\n- connect:\n to:\n - \"+15555550101\"\n - \"+15555550102\"\n - \"+15555550103\"\n timeout: 20 # seconds per destination\n```\n\nTotal ring time is `timeout * len(to)`. Use a short `timeout` (15-20s) to avoid making the caller wait through three full timeouts.\n\n## Simultaneous dialing (ring all)\n\nWrap each leg in a `[ ... ]` inner array. All inner items ring at the same time; first to answer wins.\n\n```yaml\n- connect:\n to:\n - [\"+15555550101\", \"+15555550102\", \"+15555550103\"]\n timeout: 25\n```\n\nThe outer list is sequential, the inner list is parallel. So `[[a, b], c]` means \"ring a and b together; if neither answers in `timeout`, ring c.\"\n\n## SIP URI destinations\n\nA SIP destination uses the `sip:` prefix.\n\n```yaml\n- connect:\n to: \"sip:agent42@your-pbx.example.com\"\n```\n\nAdd `;transport=tcp` or `;transport=tls` when required by the receiving endpoint.\n\n```yaml\n- connect:\n to: \"sip:%{call.to}@your-livekit-domain.com;transport=tcp\"\n```\n\n`%{call.to}` substitutes the dialed DID so the receiving platform can route by called-number.\n\n## `answer_on_bridge` — delay answer until callee picks up\n\nDefault behaviour is to answer the inbound call immediately. With `answer_on_bridge: true`, SignalWire keeps the inbound leg ringing on the caller's side until the callee answers, then bridges. The caller hears ringing instead of dead air, and billing starts only when the callee picks up.\n\n```yaml\n- connect:\n answer_on_bridge: true\n from: \"+15559876543\"\n to: \"+15555551234\"\n```\n\nUse it for any plain forwarding scenario. Required for clean outbound-from-AI-platform setups where the receiving side expects ringback.\n\n## Whisper — play audio to the callee before they hear the caller\n\n`whisper` makes SignalWire play a private prompt or SWML script to the answering party before the bridge completes. Useful for screening, recording warnings, or announcing the source of the call.\n\n```yaml\n- connect:\n to: \"+15555551234\"\n whisper:\n url: \"say:Incoming call from a new lead. Press 1 to accept.\"\n```\n\n`whisper.url` can be a hosted audio file, a `say:` TTS string, or another SWML document URL.\n\n## `confirm` — secondary SWML before bridging\n\n`confirm` runs a separate SWML doc against the callee leg before the bridge. Common pattern: start recording, log to your CRM, or whisper a prompt.\n\n```yaml\n# record-helper.yaml\nversion: 1.0.0\nsections:\n main:\n - record_call: { stereo: true, format: mp3 }\n\n# main.yaml\nversion: 1.0.0\nsections:\n main:\n - connect:\n answer_on_bridge: true\n from: \"+15559876543\"\n to: \"+15555551234\"\n confirm: \"https://your.api/record-helper.yaml\"\n```\n\n## BYO-trunk patterns\n\nTwo patterns dominate BYO integration setups (VAPI, LiveKit, Bland, Retell):\n\n### Inbound: PSTN → AI platform\n\n```yaml\nversion: 1.0.0\nsections:\n main:\n - connect:\n to: \"sip:%{call.to}@your-credential-id.sip.vapi.ai\"\n```\n\n### Outbound: AI platform → PSTN (assigned to a SIP Address)\n\n```yaml\nversion: 1.0.0\nsections:\n main:\n - connect:\n answer_on_bridge: true\n from: \"+15555551234\"\n to: \"%{call.to.replace(/^sip:/i, '').replace(/@.*/, '')}\"\n```\n\nThe `to` expression strips the `sip:` prefix and `@domain` suffix so the value is clean E.164. Full BYO setup details: [VAPI BYO](/topic/byo-sip-trunk-vapi) and [LiveKit BYO](/topic/byo-sip-trunk-livekit).\n\n## `connect` parameters reference\n\n| Parameter | Notes |\n|---|---|\n| `to` | string or array — destination(s). Required. |\n| `from` | string — override outbound caller ID. |\n| `timeout` | int — seconds to ring each destination. Default 30. |\n| `answer_on_bridge` | bool — keep ringback to inbound caller until bridge. |\n| `confirm` | string — URL of secondary SWML to run against callee. |\n| `whisper` | object — `url` (audio/say:/SWML URL) and optional `terminators`. |\n| `headers` | object — custom SIP headers (SIP destinations only). |\n| `codecs` | string — comma-separated codec preference list (G.722, G.711, Opus). |\n| `webrtc_media` | bool — force WebRTC media path. |\n| `session_timeout` | int — max bridge duration in seconds. |\n\n## Anti-patterns\n\n- Forgetting `answer_on_bridge: true` on outbound BYO trunk scripts — caller hears dead air.\n- Hardcoding internal IPs as SIP destinations — always use a hostname so SignalWire's resolver finds the right edge.\n- Long `timeout` (60s+) on sequential dialing — multiplies the caller's wait.\n- Using one giant SIP URI string instead of headers — custom headers go in `headers`, not appended to the URI.\n- Connecting to a SIP URI without `;transport=tcp` when the receiver requires it (LiveKit inbound especially).\n\n## See also\n\n- [VAPI BYO SIP trunk](/topic/byo-sip-trunk-vapi)\n- [LiveKit BYO SIP trunk](/topic/byo-sip-trunk-livekit)\n- [SWML overview](/topic/swml-overview)\n- [Call Flow Builder — Forward to Phone node](/topic/signalwire-call-flow-builder)\n","html":"

SWML connect Verb

\n

connect bridges the active call to one or more destinations. Destinations can be PSTN numbers (E.164), SIP URIs, or a mix. This is the verb that powers call forwarding, hunt groups, ring-all groups, and every BYO SIP integration.

\n

Simplest case — forward to a phone

\n
version: 1.0.0\nsections:\n  main:\n    - connect:\n        to: \"+15555551234\"\n
\n

Inbound call is answered (implicitly) and bridged to +15555551234. The caller stays on the line until the destination hangs up.

\n

Preserving caller ID

\n

By default the inbound caller's number is forwarded. To override (for example to spoof your own DID), set from:

\n
- connect:\n    from: \"+15559876543\"\n    to: \"+15555551234\"\n
\n

Caller ID rules apply: from must be a verified or owned number on your project.

\n

Sequential dialing (hunt group)

\n

Pass an array of destinations. The list is dialed in order, top to bottom, until one answers.

\n
- connect:\n    to:\n      - \"+15555550101\"\n      - \"+15555550102\"\n      - \"+15555550103\"\n    timeout: 20   # seconds per destination\n
\n

Total ring time is timeout * len(to). Use a short timeout (15-20s) to avoid making the caller wait through three full timeouts.

\n

Simultaneous dialing (ring all)

\n

Wrap each leg in a [ ... ] inner array. All inner items ring at the same time; first to answer wins.

\n
- connect:\n    to:\n      - [\"+15555550101\", \"+15555550102\", \"+15555550103\"]\n    timeout: 25\n
\n

The outer list is sequential, the inner list is parallel. So [[a, b], c] means \"ring a and b together; if neither answers in timeout, ring c.\"

\n

SIP URI destinations

\n

A SIP destination uses the sip: prefix.

\n
- connect:\n    to: \"sip:agent42@your-pbx.example.com\"\n
\n

Add ;transport=tcp or ;transport=tls when required by the receiving endpoint.

\n
- connect:\n    to: \"sip:%{call.to}@your-livekit-domain.com;transport=tcp\"\n
\n

%{call.to} substitutes the dialed DID so the receiving platform can route by called-number.

\n

answer_on_bridge — delay answer until callee picks up

\n

Default behaviour is to answer the inbound call immediately. With answer_on_bridge: true, SignalWire keeps the inbound leg ringing on the caller's side until the callee answers, then bridges. The caller hears ringing instead of dead air, and billing starts only when the callee picks up.

\n
- connect:\n    answer_on_bridge: true\n    from: \"+15559876543\"\n    to: \"+15555551234\"\n
\n

Use it for any plain forwarding scenario. Required for clean outbound-from-AI-platform setups where the receiving side expects ringback.

\n

Whisper — play audio to the callee before they hear the caller

\n

whisper makes SignalWire play a private prompt or SWML script to the answering party before the bridge completes. Useful for screening, recording warnings, or announcing the source of the call.

\n
- connect:\n    to: \"+15555551234\"\n    whisper:\n      url: \"say:Incoming call from a new lead. Press 1 to accept.\"\n
\n

whisper.url can be a hosted audio file, a say: TTS string, or another SWML document URL.

\n

confirm — secondary SWML before bridging

\n

confirm runs a separate SWML doc against the callee leg before the bridge. Common pattern: start recording, log to your CRM, or whisper a prompt.

\n
# record-helper.yaml\nversion: 1.0.0\nsections:\n  main:\n    - record_call: { stereo: true, format: mp3 }\n\n# main.yaml\nversion: 1.0.0\nsections:\n  main:\n    - connect:\n        answer_on_bridge: true\n        from: \"+15559876543\"\n        to: \"+15555551234\"\n        confirm: \"https://your.api/record-helper.yaml\"\n
\n

BYO-trunk patterns

\n

Two patterns dominate BYO integration setups (VAPI, LiveKit, Bland, Retell):

\n

Inbound: PSTN → AI platform

\n
version: 1.0.0\nsections:\n  main:\n    - connect:\n        to: \"sip:%{call.to}@your-credential-id.sip.vapi.ai\"\n
\n

Outbound: AI platform → PSTN (assigned to a SIP Address)

\n
version: 1.0.0\nsections:\n  main:\n    - connect:\n        answer_on_bridge: true\n        from: \"+15555551234\"\n        to: \"%{call.to.replace(/^sip:/i, '').replace(/@.*/, '')}\"\n
\n

The to expression strips the sip: prefix and @domain suffix so the value is clean E.164. Full BYO setup details: VAPI BYO and LiveKit BYO.

\n

connect parameters reference

\n

| Parameter | Notes |\n|---|---|\n| to | string or array — destination(s). Required. |\n| from | string — override outbound caller ID. |\n| timeout | int — seconds to ring each destination. Default 30. |\n| answer_on_bridge | bool — keep ringback to inbound caller until bridge. |\n| confirm | string — URL of secondary SWML to run against callee. |\n| whisper | object — url (audio/say:/SWML URL) and optional terminators. |\n| headers | object — custom SIP headers (SIP destinations only). |\n| codecs | string — comma-separated codec preference list (G.722, G.711, Opus). |\n| webrtc_media | bool — force WebRTC media path. |\n| session_timeout | int — max bridge duration in seconds. |

\n

Anti-patterns

\n\n

See also

\n\n"}