Transfer a SIP call with REFER

VoiceSIP REFER transfer

Hand a SIP call to another endpoint with a REFER, sending the destination URI and, when the far end asks for them, credentials.

restsip

The claim

There are two ways to move a call that came in over SIP. calling.transfer sends it to a new destination through the platform. calling.refer sends a SIP REFER instead, which is the SIP protocol’s own transfer.

Why it holds

The vendored REST spec, tools/openapi/rest.json, is the authority for the shape.

calling.refer requires device, and the device requires both type and params.
The device type enum holds exactly one value, sip.
The SIP params require to, which “must start with sip:”. from is optional and “must start with sip: when provided”.
username and password are there for a far end that challenges the REFER.
status_url “receives refer lifecycle webhooks”.

The recipe checks both URIs itself, so a tel: number or a sips: URI stops in your code rather than at the API.

How it works

def refer(call_id, to, from_uri=None, status_url=None):
    params = {"to": _sip_uri(to, "to")}
    if from_uri:
        params["from"] = _sip_uri(from_uri, "from")
    if SIP_USERNAME and SIP_PASSWORD:
        params["username"] = SIP_USERNAME
        params["password"] = SIP_PASSWORD
    body = {"device": {"type": DEVICE_TYPE, "params": params}}
    if status_url:
        body["status_url"] = status_url
    return client.calling.refer(call_id, **body)

What the platform receives:

{"command": "calling.refer",
 "id": "6d3f4a0e-2b1c-4e7a-9f0d-1c2b3a4d5e6f",
 "params": {"device": {"type": "sip",
                       "params": {"to": "sip:desk-2@pbx.example.com",
                                  "from": "sip:queue@pbx.example.com",
                                  "username": "…",
                                  "password": "…"}},
            "status_url": "https://your-pbx/refer-events"}}

The credentials come from the environment, so they are never literals in the code the page shows. Leave them unset and both keys are absent.

Limitations

The verifier proves the request, not the transfer. Whether the far end accepts a REFER, and what it does with it, belongs to that endpoint and its configuration.

The spec documents no to for a non-SIP destination here. Moving a call to a phone number is calling.transfer, in [End or transfer a live call over REST](../end-or-transfer-a-live-call-over-rest/).

What to change first

Change DEVICE_TYPE to "pstn" and run the verifier. The enum assertion fails, which is the point: the spec documents one device type for a REFER, and a second one would be an invention.

Where this sits

Before this

Connect a PBX with a Domain Application

End or transfer a live call over REST Route SIP calls to AI agents by username Transfer a call

python/app.py

"""Transfer a SIP call with REFER.

The spec's command table describes `calling.refer` as "Transfer a SIP call via
SIP REFER". The command takes a `device`, and the device takes a `type` of
`sip`, the only value the enum holds, and `params` whose `to` must be a `sip:`
URI. Optional credentials go with it when the far end challenges the REFER.

Written against signalwire-sdk 3.0.1 (RestClient.calling).

    python app.py refer <call_id> sip:desk-2@pbx.example.com
"""
import os
import sys

from dotenv import load_dotenv
from signalwire.rest import RestClient

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

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

# the only device type the spec's enum holds
DEVICE_TYPE = "sip"

# credentials for a far end that challenges the REFER
SIP_USERNAME = os.getenv("SIP_REFER_USERNAME", "")
SIP_PASSWORD = os.getenv("SIP_REFER_PASSWORD", "")


def _sip_uri(value, field):
    if not value.startswith("sip:"):
        raise ValueError(f"{field} must be a sip: URI, not {value!r}")
    return value


def refer(call_id, to, from_uri=None, status_url=None):
    """Ask the far SIP end to transfer the call to `to`."""
    params = {"to": _sip_uri(to, "to")}
    if from_uri:
        # the spec: optional, and a sip: URI when it is there
        params["from"] = _sip_uri(from_uri, "from")
    if SIP_USERNAME and SIP_PASSWORD:
        params["username"] = SIP_USERNAME
        params["password"] = SIP_PASSWORD
    body = {"device": {"type": DEVICE_TYPE, "params": params}}
    if status_url:
        # refer lifecycle webhooks land here
        body["status_url"] = status_url
    return client.calling.refer(call_id, **body)


if __name__ == "__main__":
    args = sys.argv[1:]
    cmd = args[0] if args else "help"
    call_id = args[1] if len(args) > 1 else ""
    rest = args[2:]
    if not call_id or cmd != "refer":
        print(__doc__)
    else:
        print(refer(call_id, *rest))

/**
 * Transfer a SIP call with REFER.
 *
 * The spec's command table describes `calling.refer` as "Transfer a SIP call
 * via SIP REFER". The command takes a `device`, and the device takes a `type`
 * of `sip`, the only value the enum holds, and `params` whose `to` must be a
 * `sip:` URI. Optional credentials go with it when the far end challenges the
 * REFER.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient.calling).
 *
 *     npm start refer <call_id> sip:desk-2@pbx.example.com
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

// the only device type the spec's enum holds
export const DEVICE_TYPE = "sip";

// credentials for a far end that challenges the REFER
export const SIP_USERNAME = process.env["SIP_REFER_USERNAME"] ?? "";
export const SIP_PASSWORD = process.env["SIP_REFER_PASSWORD"] ?? "";

function sipUri(value: string, field: string) {
  if (!value.startsWith("sip:")) {
    throw new Error(`${field} must be a sip: URI, not '${value}'`);
  }
  return value;
}

/** Ask the far SIP end to transfer the call to `to`. */
export function refer(callId: string, to: string, fromUri?: string,
                      statusUrl?: string) {
  const params: Record<string, string> = { to: sipUri(to, "to") };
  if (fromUri) {
    // the spec: optional, and a sip: URI when it is there
    params["from"] = sipUri(fromUri, "from");
  }
  if (SIP_USERNAME && SIP_PASSWORD) {
    params["username"] = SIP_USERNAME;
    params["password"] = SIP_PASSWORD;
  }
  const body: Record<string, unknown> = {
    device: { type: DEVICE_TYPE, params },
  };
  if (statusUrl) {
    // refer lifecycle webhooks land here
    body["status_url"] = statusUrl;
  }
  return client.calling.refer(callId, body);
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, callId, to] = process.argv.slice(2);
  if (!callId || cmd !== "refer") {
    console.log("usage: npm start refer <call_id> sip:someone@example.com");
  } else {
    console.log(await refer(callId, to));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py refer <call_id> sip:desk-2@pbx.example.com

The TypeScript surface is the same command on @signalwire/sdk, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start refer <call_id> sip:desk-2@pbx.example.com

The call has to be a SIP call for a REFER to mean anything. Take the call id from a status callback or a tool webhook, and point status_url at a route of yours if you want the lifecycle events.

Verify it

No network, no account.

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

The verifier swaps the SDK’s HTTP layer for a recorder, refers twice, and asserts the following.

a tel: destination and a sips: from both raise before any request is made
calling.refer requires device, and the device requires type and params
the device type enum is exactly ["sip"], and the recipe’s value is in it
the SIP params require to, whose description carries the sip: rule, and from carries the same rule for when it is present
username, password and status_url are documented
the spec’s command table row for calling.refer says what the README says it says
the first body carries the optional from and status_url, the second carries neither, as absent keys
the TypeScript surface sends those same two bodies and refuses the same URIs

Report an issue