End or transfer a live call over REST

VoiceREST call control (hangup and transfer)

Hang up a live call with a reason, send it to a new destination, or unbridge it from its peer, each with one REST command addressed to the call id.

rest

The claim

POST /api/calling/calls takes a command, the call id at the top level, and a params object. Any process that holds a call id can steer the call, whether or not it placed the call. The id arrives in an AI agent’s tool webhook, in a status callback, or in the response to a dial. The vendored REST spec, tools/openapi/rest.json, documents three commands for ending or moving a call.

Why it holds

calling.end takes a reason: one of hangup, cancel, busy, noAnswer, decline or error. The recipe refuses any other value before it is sent.
calling.transfer requires dest, which the spec describes as “a SIP URI, phone number, SWML URL, or an inline Calling SWML document”.
calling.disconnect has no params. The spec’s command table describes it as “Disconnect bridged calls without hanging up either leg”, so it separates two connected calls and ends neither.

The verifier proves the three requests. The spec is the authority for what the platform does with them.

How it works

client = RestClient()

def hang_up(call_id, reason="hangup"):
    if reason not in END_REASONS:
        raise ValueError(...)
    return client.calling.end(call_id, reason=reason)

def transfer(call_id, dest):
    return client.calling.transfer(call_id, dest=dest)

def unbridge(call_id):
    return client.calling.disconnect(call_id)

What the platform receives for transfer:

{"command": "calling.transfer",
 "id": "6d3f4a0e-2b1c-4e7a-9f0d-1c2b3a4d5e6f",
 "params": {"dest": "sip:tier2@pbx.example.com"}}

The SDK’s calling namespace, rest/namespaces/calling.py, sends every call command to that one path and puts the call id in id. The TypeScript SDK, @signalwire/sdk, does the same: client.calling.end(callId, { reason }) produces the body above, which is what the verifier checks. The spec marks command, id and params required on all three commands. dest accepts a string or an object. An object carries an inline SWML document, for when the new leg needs a document of its own.

A transfer over REST is different from connect inside a SWML document. The document bridges a call it is already running. The REST command moves a call from outside, which is what a supervisor console or a CRM needs.

Limitations

The verifier proves the request, not the call’s fate. Whether a dest answers, and what the far end hears for each reason, are live behaviour.

calling.disconnect presumes a bridge exists. On a call with no peer leg the platform’s response, not the recipe, says what happens.

What to change first

Change "busy" in the verifier’s first helper call to "rejected". The recipe raises before the request, which is the point. The six reasons are the whole vocabulary, and the check sits in your code rather than in a 400.

Where this sits

Before this

Place an outbound call

Inject a message into a live AI call Transfer a call Play a prompt and collect digits or speech over REST Pause and resume a call recording over REST

Seen in a build

One of 8 recipes composed by Order status desk: one omnichannel AI agent for web chat and phone.

python/app.py

"""End or transfer a live call over REST.

Three call commands, each one POST to /api/calling/calls addressed to a call id:
`calling.end` hangs up with a reason, `calling.transfer` moves the call to a new
destination, and `calling.disconnect` unbridges two connected calls.

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

    python app.py end <call_id> [reason]
    python app.py transfer <call_id> <dest>
    python app.py disconnect <call_id>
"""
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 spec's enum for calling.end; anything else is refused before it is sent
END_REASONS = ("hangup", "cancel", "busy", "noAnswer", "decline", "error")


def hang_up(call_id, reason="hangup"):
    """End the call. `reason` is what the far end and the logs see."""
    if reason not in END_REASONS:
        raise ValueError(f"reason must be one of {END_REASONS}, not {reason!r}")
    return client.calling.end(call_id, reason=reason)


def transfer(call_id, dest):
    """Send the call somewhere else: a phone number, a SIP URI or a SWML URL."""
    return client.calling.transfer(call_id, dest=dest)


def unbridge(call_id):
    """Separate this call from its peer. The spec hangs up neither leg."""
    return client.calling.disconnect(call_id)


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:
        print(__doc__)
    elif cmd == "end":
        print(hang_up(call_id, *rest))
    elif cmd == "transfer":
        print(transfer(call_id, rest[0]))
    elif cmd == "disconnect":
        print(unbridge(call_id))
    else:
        print(__doc__)

/**
 * End or transfer a live call over REST.
 *
 * Three call commands, each one POST to /api/calling/calls addressed to a call
 * id: `calling.end` hangs up with a reason, `calling.transfer` moves the call to
 * a new destination, and `calling.disconnect` unbridges two connected calls.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient.calling).
 *
 *     npm start end <call_id> [reason]
 *     npm start transfer <call_id> <dest>
 *     npm start disconnect <call_id>
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

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

// the spec's enum for calling.end; anything else is refused before it is sent
export const END_REASONS = [
  "hangup", "cancel", "busy", "noAnswer", "decline", "error",
] as const;
export type EndReason = (typeof END_REASONS)[number];

/** End the call. `reason` is what the far end and the logs see. */
export function hangUp(callId: string, reason: EndReason = "hangup") {
  if (!END_REASONS.includes(reason)) {
    throw new Error(`reason must be one of ${END_REASONS.join(", ")}, not ${reason}`);
  }
  return client.calling.end(callId, { reason });
}

/**
 * Send the call somewhere else. The spec's `dest` is a string or an object, so
 * a phone number, a SIP URI, a SWML URL or an inline SWML document all fit.
 */
export type Dest = string | Record<string, unknown>;

export function transfer(callId: string, dest: Dest) {
  return client.calling.transfer(callId, { dest });
}

/** Separate this call from its peer. The spec hangs up neither leg. */
export function unbridge(callId: string) {
  return client.calling.disconnect(callId);
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, callId, ...rest] = process.argv.slice(2);
  if (!callId) {
    console.log("usage: npm start <end|transfer|disconnect> <call_id> [reason|dest]");
  } else if (cmd === "end") {
    console.log(await hangUp(callId, (rest[0] as EndReason) ?? "hangup"));
  } else if (cmd === "transfer") {
    console.log(await transfer(callId, rest[0]));
  } else if (cmd === "disconnect") {
    console.log(await unbridge(callId));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py end <call_id> busy
python app.py transfer <call_id> sip:tier2@pbx.example.com
python app.py disconnect <call_id>

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

cd typescript
npm ci
cp ../.env.example .env
npm start end <call_id> busy

Take the call id from a tool webhook, a status callback, or the dial response. There is no server to expose; the script speaks to the REST API and exits.

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, calls the three helpers, and asserts the following.

a reason outside the enum raises before any request is made
each helper adds exactly one POST to the documented calling path
the spec marks command, id and params required on each of the three commands
the calling.end reason enum is exactly the six values, and the recipe’s own list matches it
each of the six reasons reaches the wire, and the default is hangup
the spec’s command table row for each of the three commands says what the README says it says
calling.transfer requires dest, and the spec accepts a string or an object for it
calling.disconnect documents no params, and the sent params are empty
each body equals the expected {"command", "id", "params"} shape, and every param is a documented property
the TypeScript surface, driven through the same recorder seam, sends those same three bodies, refuses the same undocumented reason, and puts all six reasons on the wire

Report an issue