Transfer a call

Voicecall transfer

Move a live caller to another number or address.

Also called blind call transfer, SIP URI transfer, route a call to Vapi, Retell or ElevenLabs over SIP

transfer

The claim

connect is the transfer verb. Its to can be a phone number, a sip: URI or a Resource address such as /public/support. Execution pauses while the two legs are bridged; when the far end hangs up, the verbs after connect run. That is the return path, and it is where the caller can be offered something else. transfer_after_bridge: "true" makes the transfer permanent instead.

How it works

- answer: {}
- play: { url: "say:Please hold while I connect you." }
- connect: { to: "+1555...", timeout: 20, ringback: ["ring:us"] }
- play: { url: "say:The other party has left the call. Thank you for calling." }   # return path
- hangup: {}

The sip section is the SIP variant: the same connect with a sip: URI and headers, which SignalWire stamps onto the INVITE so your PBX can route on them.

- connect:
    to: "sip:support@pbx.example.com"
    headers:
      - { name: "X-Account-Id", value: "acct-1234" }

To try several destinations in order or ring them at once, replace to with serial or parallel. See try-destinations-in-order. To brief the person before the bridge completes, add confirm. See brief-the-human-before-the-bridge-completes.

What to change first

Change to to a Resource address (/public/<name>) and route the call into a SWML script, an AI agent or a subscriber’s browser instead of a phone.

Where this sits

Before this

Answer an inbound call

Whisper a summary to the agent before connecting the caller

Transfer a call without losing context

Seen in a build

One of 7 recipes composed by IVR navigator: an AI agent that works through phone menus to reach a human.

python/app.py

"""Transfer a call.

`connect` bridges the live call to a phone number, a SIP URI or a Resource
address. When the far end hangs up, execution continues with the verbs after
`connect` - the return path. Set transfer_after_bridge to make it permanent.

Written against signalwire-sdk 3.0.1 (SWMLService).
"""
import os

from dotenv import load_dotenv
from signalwire import SWMLService

# the SDK does not read .env for you
load_dotenv()

DEST = os.getenv("TRANSFER_TO", "+15550100001")
SIP_DEST = os.getenv("SIP_TRANSFER_TO", "sip:support@pbx.example.com")
PERMANENT = os.getenv("PERMANENT", "false").lower() == "true"


def build(service=None):
    service = service or SWMLService(name="transfer", route="/transfer")
    service.reset_document()

    service.add_verb("answer", {})
    service.add_verb("play", {"url": "say:Please hold while I connect you."})
    connect = {"to": DEST, "timeout": 20, "ringback": ["ring:us"]}
    if PERMANENT:
        connect["transfer_after_bridge"] = "true"
    service.add_verb("connect", connect)
    # Reached only when the bridge ends and the transfer was not permanent.
    service.add_verb("play", {
        "url": "say:The other party has left the call. Thank you for calling."})
    service.add_verb("hangup", {})

    # Variant: a SIP destination with custom headers on the INVITE.
    service.add_section("sip")
    service.add_verb_to_section("sip", "answer", {})
    service.add_verb_to_section("sip", "connect", {
        "to": SIP_DEST,
        "headers": [
            {"name": "X-Account-Id", "value": os.getenv("ACCOUNT_ID", "acct-1234")},
            {"name": "X-Source", "value": "signalwire-recipes"},
        ],
    })
    service.add_verb_to_section("sip", "hangup", {})
    return service


if __name__ == "__main__":
    build().serve(port=int(os.getenv("PORT", "8080")))

# Transfer a call - bridge the live call to a number, and take it back when the
# far end hangs up. Verbs after `connect` run only when the bridge ends: that is
# the return path. To make the transfer permanent, add
# `transfer_after_bridge: "true"` to connect.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - play: { url: "say:Please hold while I connect you." }
    - connect:
        to: "+15550100001"
        timeout: 20
        ringback: ["ring:us"]
    - play: { url: "say:The other party has left the call. Thank you for calling." }
    - hangup: {}
  # Variant: bridge to a SIP URI and stamp custom headers on the INVITE.
  sip:
    - answer: {}
    - connect:
        to: "sip:support@pbx.example.com"
        headers:
          - { name: "X-Account-Id", value: "acct-1234" }
          - { name: "X-Source", value: "signalwire-recipes" }
    - hangup: {}

Run it

Markup only: paste swml/agent.yaml into a SWML Script, replace the destinations, assign a phone number.

Python:

cd python
pip install -r requirements.txt
TRANSFER_TO=+1555... python app.py            # temporary: the call comes back
PERMANENT=true TRANSFER_TO=+1555... python app.py

Point a phone number’s SWML webhook at https://<user>:<password>@<your-host>/transfer/.

Verify it

python verify.py          # from the recipe folder, not python/

Both surfaces validate against the SWML schema. The verifier asserts connect is followed by a return path, that PERMANENT=true adds transfer_after_bridge, and that the SIP variant carries the custom headers.

Report an issue