Forward calls to a phone and keep the caller's number

Voicecall forwarding with caller ID pass-through

Forward every call on a number to a phone, and show that phone the original caller's number instead of your own.

Also called call forwarding, forward calls to a cell phone, caller ID pass-through

swmlforwardingcaller-id

The claim

Plain forwarding has one flaw: the phone that rings sees the forwarding number, so every call looks the same and callback means checking a log. This document forwards with the caller’s own number as the caller ID, so the mobile shows the customer.

Why it holds

Two facts carry the claim.

The vendored REST spec documents the inbound call webhook SignalWire sends when it fetches your document, and its call object requires from, “the number/URI that initiated this call”.
The bundled SWML schema’s connect device takes from, described as “the caller ID to use when dialing the number”, and a timeout that defaults to 60 seconds.

The handler reads call.from and writes it back into connect.from. Nothing is templated, so there is no question of which substitution syntax the platform expands; the number the platform sent is the number the platform gets.

How it works

def document(caller):
    service = SWMLService(name="forward", route="/swml")
    connect = {"to": FORWARD_TO, "timeout": RING_FOR}
    if caller:
        connect["from"] = caller
    service.add_verb("connect", connect)
    return json.loads(service.render_document())

What a call from +1 415 555 0123 gets back:

{"version": "1.0.0",
 "sections": {"main": [{"connect": {"to": "+15550100001",
                                    "timeout": 25,
                                    "from": "+14155550123"}}]}}

There is no answer verb. connect bridges the caller to the ringing phone when it picks up, so the caller hears ringing rather than a picked-up line with silence behind it. A call with no caller id leaves from out, and the platform presents its own default rather than an empty string.

Passing a caller’s number through as your caller ID is subject to the rules of the country and carrier the call leaves through. The recipe shows the mechanism. Whether your numbers may present it is a question for your carrier agreement.

Limitations

The verifier proves the document, not the display. Whether the mobile shows the caller’s number depends on the carriers between the platform and that phone.

The forwarding target is one number. Ringing several, in order or at once, is [Dial destinations in order or all at once](../try-destinations-in-order/). The from shown here applies to each of its devices.

What to change first

Change connect["from"] = caller to connect["from"] = FORWARD_TO and run the verifier. The document validates and the assertion fails, which is the point. The schema accepts any caller ID; only the verifier says it must be the caller’s.

Where this sits

Transfer a call Dial destinations in order or all at once, with a failure path Route calls by dialed number or time Reject callers on a blocklist before answering

python/app.py

"""Forward calls to a phone and keep the caller's number.

A forwarded call usually shows the forwarding number on the phone that rings,
so whoever answers cannot see who is really calling. `connect` takes a `from`,
which the bundled schema describes as "the caller ID to use when dialing the
number". Set it to the inbound `call.from` and the forwarded phone shows the
original caller.

SignalWire fetches this document with the inbound call webhook, whose body
carries `call.from`, so the handler reads the caller and writes it back into
the `connect`. Nothing is templated; the number the platform sent is the
number the platform gets.

Written against signalwire-sdk 3.0.1 (SWMLService) and Flask.

    python app.py            # serves POST /swml
"""
import json
import os

from dotenv import load_dotenv
from flask import Flask, Response, jsonify, request
from signalwire import SWMLService

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

# the phone that should ring; swap for your on-call rota
FORWARD_TO = os.getenv("FORWARD_TO", "+15550100001")
RING_FOR = int(os.getenv("RING_FOR", "25"))

# The webhook serves a routing document to whoever asks; SignalWire fetches it
# with the credentials in the URL you give it, so the route wants them too.
AUTH_USER = os.getenv("SWML_BASIC_AUTH_USER")
AUTH_PASSWORD = os.getenv("SWML_BASIC_AUTH_PASSWORD")
if not (AUTH_USER and AUTH_PASSWORD):
    raise SystemExit("SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD are required; "
                     "see .env.example")


def document(caller):
    """Connect to the forwarding target, presenting the caller's own number."""
    service = SWMLService(name="forward", route="/swml")
    connect = {"to": FORWARD_TO, "timeout": RING_FOR}
    if caller:
        # the caller ID the ringing phone displays. Without a caller id the
        # platform picks, so the key is left out rather than set to nothing
        connect["from"] = caller
    service.add_verb("connect", connect)
    # 3.0.1 renders the document as a JSON string
    return json.loads(service.render_document())


app = Flask(__name__)


@app.post("/swml")
def swml():
    auth = request.authorization
    if not (auth and auth.username == AUTH_USER and auth.password == AUTH_PASSWORD):
        return Response(status=401, headers={"WWW-Authenticate": 'Basic realm="swml"'})
    payload = request.get_json(force=True)
    return jsonify(document((payload.get("call") or {}).get("from")))


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

/**
 * Forward calls to a phone and keep the caller's number.
 *
 * A forwarded call usually shows the forwarding number on the phone that rings,
 * so whoever answers cannot see who is really calling. `connect` takes a `from`,
 * which the bundled schema describes as "the caller ID to use when dialing the
 * number". Set it to the inbound `call.from` and the forwarded phone shows the
 * original caller.
 *
 * Written against @signalwire/sdk 2.0.5 (SWMLService) and node:http.
 *
 *     npm start            # serves POST /swml
 */
import "dotenv/config";
import { createServer, type IncomingMessage } from "node:http";
import { SWMLService } from "@signalwire/sdk";

// the phone that should ring; swap for your on-call rota
export const FORWARD_TO = process.env["FORWARD_TO"] ?? "+15550100001";
export const RING_FOR = Number(process.env["RING_FOR"] ?? 25);

const AUTH_USER = process.env["SWML_BASIC_AUTH_USER"] ?? "";
const AUTH_PASSWORD = process.env["SWML_BASIC_AUTH_PASSWORD"] ?? "";

/** Connect to the forwarding target, presenting the caller's own number. */
export function document(caller: string | undefined): Record<string, unknown> {
  const service = new SWMLService({ name: "forward", route: "/swml" });
  const connect: Record<string, unknown> = { to: FORWARD_TO, timeout: RING_FOR };
  if (caller) {
    // the caller ID the ringing phone displays. Without a caller id the
    // platform picks, so the key is left out rather than set to nothing
    connect["from"] = caller;
  }
  service.addVerb("connect", connect);
  return JSON.parse(service.renderDocument());
}

function readBody(req: IncomingMessage): Promise<string> {
  return new Promise((resolve) => {
    const chunks: Buffer[] = [];
    req.on("data", (c: Buffer) => chunks.push(c));
    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
  });
}

/** POST /swml, behind the basic auth SignalWire is given in the webhook URL. */
export function serve(port: number) {
  const pair = Buffer.from(`${AUTH_USER}:${AUTH_PASSWORD}`).toString("base64");
  const expected = `Basic ${pair}`;
  return createServer(async (req, res) => {
    const raw = await readBody(req);
    if (req.method !== "POST" || !req.url?.startsWith("/swml")) {
      res.writeHead(404);
      return res.end();
    }
    if (!AUTH_USER || req.headers.authorization !== expected) {
      res.writeHead(401, { "www-authenticate": 'Basic realm="swml"' });
      return res.end();
    }
    let payload: { call?: { from?: string } } = {};
    try { payload = JSON.parse(raw); } catch { /* no call, no caller */ }
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify(document(payload.call?.from)));
  }).listen(port);
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  if (!AUTH_USER || !AUTH_PASSWORD) {
    throw new Error("SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD are required; "
                    + "see .env.example");
  }
  serve(Number(process.env["PORT"] ?? 8080));
  console.log("listening: POST /swml");
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space, basic auth, FORWARD_TO
python app.py                    # serves POST /swml on :8080

The TypeScript surface is the same handler on @signalwire/sdk’s SWMLService with node:http, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start

Point the business number’s call handler at https://user:pass@your-host/swml, set FORWARD_TO to the mobile, and call the business number.

Verify it

No network, no account.

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

The verifier drives the Flask route with payloads shaped like the spec’s inbound call webhook and asserts the following.

the spec requires from on the inbound call, and the sample payload carries every required field
a call from a number renders exactly one connect, with to the forwarding target, from that number and the ring timeout, and it validates
a request with no caller id renders the same connect with no from key at all
the schema describes connect.from as the caller ID to use when dialing, and defaults timeout to 60
a request without credentials is a 401
the TypeScript surface, on a real port, returns the same two documents and the same 401

Report an issue