Relay calls and texts through a proxy number

Voicephone number masking (call and text by proxy)

Pair two people on one number of yours so calls and texts between them are relayed with your number showing, and neither ever sees the other's.

swmlwebhooksmasking

The claim

Number masking is two lookups and two verbs. Your handler keeps a session that says, on proxy P, participant A reaches B and B reaches A. When either of them calls or texts P, the inbound webhook carries from and to, and the session gives the other party. The document then relays the call or the text with P as the visible number.

Why it holds

Three facts carry the claim.

The inbound call webhook’s call and the inbound message webhook’s message both require from and to, which is all the lookup needs.
The bundled schema describes connect.from as “the caller ID to use when dialing the number”, so the called party’s phone shows the proxy.
reply is the Messaging SWML method that sends a message. Its to defaults to the sender and its from to the number that received the text, so naming both relays the text with the proxy on it.

A stranger who calls the proxy hears that the number is not active and the call ends. A stranger who texts it gets an empty document: nothing sent, nothing kept. Pairing two numbers is a decision about who can reach whom, so /pair is behind a key the server holds and your systems present as X-Proxy-Key.

How it works

def call_document(caller, proxy):
    service = SWMLService(name="proxy-call", route="/call")
    other = other_party(proxy, caller)
    if other:
        service.add_verb("connect", {"to": other, "from": proxy})
    else:
        service.add_verb("answer", {})
        service.add_verb("play", {"url": f"say:{NOT_ACTIVE}"})
        service.add_verb("hangup", {})
    return json.loads(service.render_document())

def message_document(sender, proxy, body):
    other = other_party(proxy, sender)
    steps = []
    if other:
        steps.append({"reply": {"to": other, "from": proxy, "body": body or ""}})
    return {"version": "1.0.0", "sections": {"main": steps}}

What the buyer’s call to the proxy gets back:

{"version": "1.0.0",
 "sections": {"main": [{"connect": {"to": "+13105550199", "from": "+15550001111"}}]}}

The session store is a file keyed by proxy and participant, with both directions written at once. In your app it is a table with an expiry, because a masked pairing should end when the transaction does. The webhooks and the pairing are different requests, which is why the store is not a dictionary.

Both webhook routes sit behind the basic auth you put in the handler URLs, as every document-serving recipe here does.

Limitations

A participant is in one pairing at a time on a given proxy. Pairing A with C removes B’s route back to A, or B could keep reaching A while A’s replies went to C. Two pairings for one person need two proxy numbers.

The verifier proves the documents, not the display. Whether a phone shows the proxy number depends on the carriers between the platform and that phone.

Sessions here never expire. A real pairing has a lifetime, and the table that replaces the file should carry one.

Presenting a number you own as the caller ID for a relayed call is the normal case here; the proxy is yours. Relaying a text from a 10DLC number is A2P traffic and needs a registered campaign.

What to change first

Change "from": proxy to "from": caller in call_document and run the verifier. The document validates and the assertion fails, which is the point: that one field is the difference between a relay and a leak.

Where this sits

Before this

Buy a number and point it at your app Forward calls to a phone and keep the caller's number

Reply to an inbound SMS Text the caller during the call Send an SMS

python/app.py

"""Relay calls and texts through a proxy number.

Two people share one number of yours and never learn each other's. Your
handler pairs them: a session says that on proxy P, participant A talks to B
and B talks to A. A call from A to P becomes `connect` to B with `from` set to
P, so B's phone shows the proxy; a text from A to P becomes a `reply` to B
from P. The schema calls `connect.from` "the caller ID to use when dialing the
number"; `reply` is the Messaging method, whose `to` defaults to the sender.

The inbound call and inbound message webhooks both carry `from` and `to`, which
is all the lookup needs. Sessions live in a file here, keyed by proxy and
participant, because the pairing and the two webhooks are different requests.

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

    python app.py            # serves POST /call, POST /message, POST /pair
"""
import json
import os
import re
from pathlib import Path

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

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

# the number both parties see. Buy it first; buy-a-number-and-point-it-at-your-app
PROXY = os.getenv("PROXY_NUMBER", "+15550001111")

# where the pairings live; swap for your database
SESSIONS_PATH = Path(os.getenv("SESSIONS_PATH", "proxy-sessions.json"))

# /pair creates sessions and so decides who can reach whom; it wants a key the
# server holds and your own systems present as X-Proxy-Key
ADMIN_KEY = os.getenv("PROXY_ADMIN_KEY")

# both webhooks serve documents to whoever asks; SignalWire fetches them with
# the credentials in the URLs you give it, so the routes want 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")

NOT_ACTIVE = "This number is not active for your call."


def digits(number):
    return re.sub(r"\D", "", number or "")


def _key(proxy, participant):
    return f"{digits(proxy)}|{digits(participant)}"


def _load():
    if not SESSIONS_PATH.exists():
        return {}
    return json.loads(SESSIONS_PATH.read_text(encoding="utf-8"))


def _save(sessions):
    tmp = SESSIONS_PATH.with_suffix(".tmp")
    tmp.write_text(json.dumps(sessions, indent=2), encoding="utf-8")
    os.replace(tmp, SESSIONS_PATH)


def pair(a, b, proxy=PROXY):
    """On this proxy, A reaches B and B reaches A. Returns the two keys written."""
    sessions = _load()
    # a participant is in one pairing at a time: drop the old partner's
    # route back, or the old partner could still reach them
    for participant in (a, b):
        old = sessions.pop(_key(proxy, participant), None)
        back = sessions.get(_key(proxy, old), "") if old else ""
        if old and _key(proxy, back) == _key(proxy, participant):
            del sessions[_key(proxy, old)]
    sessions[_key(proxy, a)] = b
    sessions[_key(proxy, b)] = a
    _save(sessions)
    return [_key(proxy, a), _key(proxy, b)]


def other_party(proxy, participant):
    """Who this participant reaches on this proxy, or None."""
    return _load().get(_key(proxy, participant))


def _render(service):
    # 3.0.1 renders the document as a JSON string
    return json.loads(service.render_document())


def call_document(caller, proxy):
    """A call to the proxy becomes a call to the other party, from the proxy."""
    service = SWMLService(name="proxy-call", route="/call")
    other = other_party(proxy, caller)
    if other:
        service.add_verb("connect", {"to": other, "from": proxy})
    else:
        service.add_verb("answer", {})
        service.add_verb("play", {"url": f"say:{NOT_ACTIVE}"})
        service.add_verb("hangup", {})
    return _render(service)


def message_document(sender, proxy, body):
    """A text to the proxy becomes a text to the other party, from the proxy.

    `reply` is the Messaging SWML method, and its `to` defaults to the sender,
    so naming `to` is what relays the text. SWMLService validates against the
    bundled Calling schema, which has no messaging methods, so the document is
    built as a dict, the way reply-to-an-inbound-sms builds its own.
    """
    other = other_party(proxy, sender)
    steps = []
    if other:
        steps.append({"reply": {"to": other, "from": proxy, "body": body or ""}})
    # an unknown sender gets an empty document: nothing sent, nothing kept
    return {"version": "1.0.0", "sections": {"main": steps}}


app = Flask(__name__)


@app.before_request
def gate():
    if request.path in ("/call", "/message"):
        auth = request.authorization
        if not (auth and auth.username == AUTH_USER and auth.password == AUTH_PASSWORD):
            challenge = {"WWW-Authenticate": 'Basic realm="proxy"'}
            abort(Response(status=401, headers=challenge))
    if request.path == "/pair":
        if not ADMIN_KEY or request.headers.get("X-Proxy-Key") != ADMIN_KEY:
            abort(403)


@app.post("/call")
def call():
    c = request.get_json(force=True).get("call") or {}
    return jsonify(call_document(c.get("from"), c.get("to") or PROXY))


@app.post("/message")
def message():
    m = request.get_json(force=True).get("message") or {}
    return jsonify(message_document(m.get("from"), m.get("to") or PROXY, m.get("body")))


@app.post("/pair")
def pair_route():
    body = request.get_json(force=True)
    return jsonify({"keys": pair(body["a"], body["b"], body.get("proxy", PROXY))})


if __name__ == "__main__":
    if not ADMIN_KEY:
        raise SystemExit("PROXY_ADMIN_KEY is required; see .env.example")
    app.run(port=int(os.getenv("PORT", "8080")))

/**
 * Relay calls and texts through a proxy number.
 *
 * Two people share one number of yours and never learn each other's. Your
 * handler pairs them: a session says that on proxy P, participant A talks to B
 * and B talks to A. A call from A to P becomes `connect` to B with `from` set
 * to P, so B's phone shows the proxy; a text from A to P becomes a `reply` to
 * B from P.
 *
 * Written against @signalwire/sdk 2.0.5 (SWMLService) and node:http.
 *
 *     npm start            # serves POST /call, POST /message, POST /pair
 */
import "dotenv/config";
import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { createServer, type IncomingMessage } from "node:http";
import { SWMLService } from "@signalwire/sdk";

// the number both parties see. Buy it first; buy-a-number-and-point-it-at-your-app
export const PROXY = process.env["PROXY_NUMBER"] ?? "+15550001111";
// where the pairings live; swap for your database
export const SESSIONS_PATH = process.env["SESSIONS_PATH"] ?? "proxy-sessions.json";
// /pair decides who can reach whom; it wants a key the server holds
const ADMIN_KEY = process.env["PROXY_ADMIN_KEY"] ?? "";
const AUTH_USER = process.env["SWML_BASIC_AUTH_USER"] ?? "";
const AUTH_PASSWORD = process.env["SWML_BASIC_AUTH_PASSWORD"] ?? "";
export const NOT_ACTIVE = "This number is not active for your call.";

const digits = (n: string | undefined) => (n ?? "").replace(/\D/g, "");
const key = (proxy: string, participant: string) =>
  `${digits(proxy)}|${digits(participant)}`;

type Sessions = Record<string, string>;
const load = (): Sessions =>
  existsSync(SESSIONS_PATH) ? JSON.parse(readFileSync(SESSIONS_PATH, "utf-8")) : {};
function save(sessions: Sessions) {
  writeFileSync(`${SESSIONS_PATH}.tmp`, JSON.stringify(sessions, null, 2), "utf-8");
  renameSync(`${SESSIONS_PATH}.tmp`, SESSIONS_PATH);
}

/** On this proxy, A reaches B and B reaches A. Returns the two keys written. */
export function pair(a: string, b: string, proxy = PROXY): string[] {
  const sessions = load();
  // a participant is in one pairing at a time: drop the old partner's
  // route back, or the old partner could still reach them
  for (const participant of [a, b]) {
    const old = sessions[key(proxy, participant)];
    delete sessions[key(proxy, participant)];
    const back = old ? sessions[key(proxy, old)] ?? "" : "";
    if (old && key(proxy, back) === key(proxy, participant)) {
      delete sessions[key(proxy, old)];
    }
  }
  sessions[key(proxy, a)] = b;
  sessions[key(proxy, b)] = a;
  save(sessions);
  return [key(proxy, a), key(proxy, b)];
}

/** Who this participant reaches on this proxy, or undefined. */
export const otherParty = (proxy: string, participant: string | undefined) =>
  participant ? load()[key(proxy, participant)] : undefined;

const render = (s: SWMLService) =>
  JSON.parse(s.renderDocument()) as Record<string, unknown>;

/** A call to the proxy becomes a call to the other party, from the proxy. */
export function callDocument(caller: string | undefined, proxy: string) {
  const service = new SWMLService({ name: "proxy-call", route: "/call" });
  const other = otherParty(proxy, caller);
  if (other) {
    service.addVerb("connect", { to: other, from: proxy });
  } else {
    service.addVerb("answer", {});
    service.addVerb("play", { url: `say:${NOT_ACTIVE}` });
    service.addVerb("hangup", {});
  }
  return render(service);
}

/**
 * A text to the proxy becomes a text to the other party, from the proxy.
 * `reply` is the Messaging SWML method, and its `to` defaults to the sender,
 * so naming `to` is what relays the text. SWMLService validates against the
 * bundled Calling schema, which has no messaging methods, so this one is built
 * as an object.
 */
export function messageDocument(sender: string | undefined, proxy: string, body: string) {
  const other = otherParty(proxy, sender);
  const steps: Record<string, unknown>[] = [];
  if (other) steps.push({ reply: { to: other, from: proxy, body: body ?? "" } });
  // an unknown sender gets an empty document: nothing sent, nothing kept
  return { version: "1.0.0", sections: { main: steps } };
}

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()));
  });
}

/** The three routes: SignalWire posts to /call and /message, you post to /pair. */
export function serve(port: number) {
  const pairAuth = Buffer.from(`${AUTH_USER}:${AUTH_PASSWORD}`).toString("base64");
  const expected = `Basic ${pairAuth}`;
  return createServer(async (req, res) => {
    const raw = await readBody(req);
    const send = (status: number, body?: unknown,
                  headers: Record<string, string> = {}) => {
      res.writeHead(status, { "content-type": "application/json", ...headers });
      res.end(body === undefined ? "" : JSON.stringify(body));
    };
    if (req.method !== "POST") return send(404);
    let payload: Record<string, Record<string, string>> = {};
    try { payload = JSON.parse(raw); } catch { /* an empty body has no call */ }
    if (req.url === "/pair") {
      if (!ADMIN_KEY || req.headers["x-proxy-key"] !== ADMIN_KEY) return send(403);
      type PairBody = { a: string; b: string; proxy?: string };
      const { a, b, proxy } = payload as unknown as PairBody;
      return send(200, { keys: pair(a, b, proxy ?? PROXY) });
    }
    if (req.url === "/call" || req.url === "/message") {
      if (!AUTH_USER || req.headers.authorization !== expected) {
        return send(401, undefined, { "www-authenticate": 'Basic realm="proxy"' });
      }
      if (req.url === "/call") {
        const c = payload["call"] ?? {};
        return send(200, callDocument(c["from"], c["to"] ?? PROXY));
      }
      const m = payload["message"] ?? {};
      return send(200, messageDocument(m["from"], m["to"] ?? PROXY, m["body"] ?? ""));
    }
    send(404);
  }).listen(port);
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  for (const [name, value] of Object.entries({ SWML_BASIC_AUTH_USER: AUTH_USER,
      SWML_BASIC_AUTH_PASSWORD: AUTH_PASSWORD, PROXY_ADMIN_KEY: ADMIN_KEY })) {
    if (!value) throw new Error(`${name} is required; see .env.example`);
  }
  serve(Number(process.env["PORT"] ?? 8080));
  console.log("listening: POST /call, POST /message, POST /pair");
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space, proxy number, auth, key
python app.py                    # serves POST /call, POST /message, POST /pair

The TypeScript surface is the same three routes 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

Buy a number and point its call handler at https://user:pass@your-host/call and its message handler at https://user:pass@your-host/message. Then pair two numbers:

curl -X POST https://your-host/pair -H "X-Proxy-Key: $PROXY_ADMIN_KEY" \
  -H "content-type: application/json" -d '{"a": "+14155550123", "b": "+13105550199"}'

Either party calls or texts the proxy and reaches the other.

Verify it

No network, no account.

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

The verifier drives the Flask routes with payloads shaped like the spec’s two inbound webhooks and asserts the following.

/pair refuses a missing and a wrong key with 403 and writes nothing, and with the key writes both directions of the session
after a module reload, a call from either party renders one connect to the other with from the proxy, and a stranger’s call renders answer, a spoken not-active line and hangup
a text from either party renders one reply to the other from the proxy carrying the body, and a stranger’s text renders an empty document
the call documents validate against the bundled schema, and the schema’s description of connect.from is what this README quotes
the message documents are checked against the documented Messaging method set instead, because the bundled schema is the Calling one, and send_sms is not in that set
both webhook payloads carry every field the spec requires, and the spec requires from and to on each
both webhook routes refuse an unauthenticated POST with 401
re-pairing Alice with Carol removes Bob’s route back to her: Bob’s next call hears the not-active line and his text sends nothing
the TypeScript surface, on a real port, pairs behind the same key, renders the same six documents, and returns the same 401s

Report an issue