Reject callers on a blocklist before answering

Voicecall blocking and screening (blocklist)

Read the caller's number when SignalWire fetches your call document, and decline a listed number before the call is answered while everyone else is connected.

swmlwebhooksscreening

The claim

Call screening does not need a feature. SignalWire fetches your document with the inbound call webhook, and that request carries the caller’s number, so your handler is the place where the decision lives. The list is yours, kept wherever you keep things, and the platform never sees it.

Why it holds

Two facts carry the claim.

The vendored REST spec documents the inbound call webhook payload. Its call object requires from, “the number/URI that initiated this call”, and that is what the handler reads.
The bundled SWML schema’s hangup verb takes an optional reason whose values are exactly hangup, busy and decline. A document that starts with hangup and never says answer refuses the call rather than picking it up and dropping it.

Numbers are compared by digits, so +1 (555) 555-0101 on the list still catches 15555550101 on the wire. An absent caller id is not on any list and is connected.

How it works

def is_blocked(caller):
    d = digits(caller)
    return bool(d) and d in BLOCKED

def document(caller):
    service = SWMLService(name="screen", route="/swml")
    if is_blocked(caller):
        service.add_verb("hangup", {"reason": REASON})
    else:
        service.add_verb("answer", {})
        service.add_verb("connect", {"to": DESTINATION})
    return json.loads(service.render_document())

What a listed caller’s request gets back:

{"version": "1.0.0", "sections": {"main": [{"hangup": {"reason": "decline"}}]}}

decline tells the network the call was refused. busy makes the line look engaged instead, which a persistent dialler reads as a dead end. Both are in the schema; REJECT_REASON picks one.

The route sits behind the basic auth you put in the webhook URL, as every document-serving recipe here does. Nobody but SignalWire reads your routing.

Limitations

The verifier proves the documents, not what a blocked caller hears. What decline and busy sound like on the far end depends on the caller’s carrier.

call.from is what the network delivered. A caller who withholds their number arrives with none, and this recipe connects them; screening anonymous callers is a policy you add, not a default.

What to change first

Add "+14155550123" to BLOCKLIST and run the verifier. The allowed caller’s assertion fails on a hangup, which is the point: the list is the whole decision, and it is yours.

Where this sits

Route calls by dialed number or time Look up a caller's carrier and name End or transfer a live call over REST

python/app.py

"""Reject callers on a blocklist before answering.

SignalWire fetches your document with the inbound call webhook, whose body
carries `call.from`. Your handler reads it and decides. A number on the list
gets a one-verb document, `hangup` with a reason, and no `answer` before it, so
the call is refused rather than picked up. Everyone else gets `answer` and
`connect`. The list is yours; the platform never sees it.

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

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

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

# where allowed callers end up; swap for your queue or agent
DESTINATION = os.getenv("DESTINATION", "+15550100001")

# the numbers to refuse, in any format; compared by digits. Swap for your table
BLOCKLIST = {"+15555550100", "+1 (555) 555-0101"}

# the schema's reasons are hangup, busy and decline; decline tells the far end
# the call was refused, busy makes it look like a busy line
REASON = os.getenv("REJECT_REASON", "decline")

# 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 digits(number):
    """+1 (555) 555-0101 and 15555550101 are the same caller."""
    return re.sub(r"\D", "", number or "")


BLOCKED = {digits(n) for n in BLOCKLIST}


def is_blocked(caller):
    """True for a listed number. An absent caller id is not on any list."""
    d = digits(caller)
    return bool(d) and d in BLOCKED


def document(caller):
    """The SWML for this caller: refused before answering, or answered and connected."""
    service = SWMLService(name="screen", route="/swml")
    if is_blocked(caller):
        # no answer verb: the call is declined, not picked up and dropped
        service.add_verb("hangup", {"reason": REASON})
    else:
        service.add_verb("answer", {})
        service.add_verb("connect", {"to": DESTINATION})
    # 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")))

/**
 * Reject callers on a blocklist before answering.
 *
 * SignalWire fetches your document with the inbound call webhook, whose body
 * carries `call.from`. Your handler reads it and decides. A number on the list
 * gets a one-verb document, `hangup` with a reason, and no `answer` before it,
 * so the call is refused rather than picked up. Everyone else gets `answer` and
 * `connect`. The list is yours; the platform never sees it.
 *
 * 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";

// where allowed callers end up; swap for your queue or agent
export const DESTINATION = process.env["DESTINATION"] ?? "+15550100001";

// the numbers to refuse, in any format; compared by digits. Swap for your table
export const BLOCKLIST = ["+15555550100", "+1 (555) 555-0101"];

// the schema's reasons are hangup, busy and decline; decline tells the far end
// the call was refused, busy makes it look like a busy line
export const REASON = process.env["REJECT_REASON"] ?? "decline";

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

/** +1 (555) 555-0101 and 15555550101 are the same caller. */
export const digits = (number: string | undefined) => (number ?? "").replace(/\D/g, "");

const BLOCKED = new Set(BLOCKLIST.map(digits));

/** True for a listed number. An absent caller id is not on any list. */
export function isBlocked(caller: string | undefined): boolean {
  const d = digits(caller);
  return d.length > 0 && BLOCKED.has(d);
}

/** The SWML for this caller: refused before answering, or answered and connected. */
export function document(caller: string | undefined): Record<string, unknown> {
  const service = new SWMLService({ name: "screen", route: "/swml" });
  if (isBlocked(caller)) {
    // no answer verb: the call is declined, not picked up and dropped
    service.addVerb("hangup", { reason: REASON });
  } else {
    service.addVerb("answer", {});
    service.addVerb("connect", { to: DESTINATION });
  }
  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, DESTINATION
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 a number’s call handler at https://user:pass@your-host/swml and call it from a listed number and from another. Edit BLOCKLIST for your own.

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 sample payload carries every field the spec requires on call, and no field the spec does not know
a listed number, and the same number in a different format, each get a document of exactly one verb, hangup with reason: decline, and it validates
an allowed number, and a request with no caller id, each get answer then connect to the destination, and it validates
the schema’s hangup.reason allows exactly hangup, busy and decline, and the recipe’s reason is one of them
a request without credentials is a 401
the TypeScript surface, on a real port, returns the same four documents and the same 401

Report an issue