Forward an inbound SMS to other numbers

MessagingSMS forwarding to a group

Send every text that arrives on your number on to a list of other numbers with the Messaging reply method, prefixed with the sender, without replying to the sender.

Also called SMS forwarding, text message forwarding, forward texts to a cell phone, SMS to group

swmlwebhooksforwarding

The claim

The inbound message webhook carries from, to and body, and the spec requires all three. The handler answers with a Messaging SWML document holding one reply for every recipient on the list. to is the recipient, from is the number the text arrived on, and the body is the sender’s number, a colon, and their words.

Why it holds

reply is the method that sends a message from a messaging document. Its to defaults to message.from and its from to message.to, so a reply with no to answers the sender. Naming to sends it somewhere else, which is why the reference’s own example of this carries the heading “Forward an inbound message to another number”.

Three rules keep it a forwarder rather than a loop. The sender is left out, so the team can talk on the same line. The receiving number is left out, because texting the line that fired this webhook fires it again. A repeated entry in the list sends one copy, not two.

How it works

def forward_document(sender, received_on, body, recipients=None):
    steps = []
    if keyword(body) not in STOP_WORDS:
        for recipient in targets(sender, received_on, recipients):
            # `to` is what makes this a forward rather than a reply
            steps.append({"reply": {"to": recipient, "from": received_on,
                                    "body": forwarded_body(sender, body)}})
    return {"version": "1.0.0", "sections": {"main": steps}}

What a customer’s text renders, with two people on shift:

{"version": "1.0.0", "sections": {"main": [
  {"reply": {"to": "+15550100001", "from": "+15550001111",
             "body": "+14155550123: Is my bike ready?"}},
  {"reply": {"to": "+15550100002", "from": "+15550001111",
             "body": "+14155550123: Is my bike ready?"}}]}}

Two limits shape the body. An SMS body maxes out at 1600 characters, and the sender prefix counts, so a full-length inbound is truncated to leave room. A STOP is not forwarded at all. The carrier keywords are an opt-out from you, not a message for the team, and handle-opt-outs-yourself is where they go. The match is the trimmed, lowercased word with trailing punctuation removed, so STOP. counts and stop please does not.

The Messaging method set is reply, receive, execute, return, transfer, goto, label, switch and request. send_sms is not in it; that is the Calling method for texting from inside a call, which text-the-caller-during-the-call uses.

Limitations

The verifier proves the document, not delivery. A forwarded text from a 10DLC number is A2P traffic and needs a registered campaign, and the receiving line must be messaging-enabled to be a from.

Two forwarders pointed at each other stop, because each one drops the sender. A ring of three does not: every hop’s sender is the previous line, never the next one. Do not point one of these at another.

Media is dropped. An inbound MMS carries media URLs in the payload, and reply takes a media list of up to eight attachments. Carrying them over is the first extension; the URLs are platform-hosted and unguessable.

Recipients are a list in the environment. A roster that changes by shift is a lookup in targets, which is the one function that decides who gets a copy.

What to change first

Delete "to": recipient from the reply and run the verifier. The document is still a valid Messaging document and the assertion fails. That is the point: without to, reply answers the sender, and the forwarder becomes an echo.

Where this sits

Before this

Reply to an inbound SMS

Relay calls and texts through a proxy number Handle SMS STOP and START in your own code Send an SMS

python/app.py

"""Forward an inbound SMS to other numbers.

A text arriving on your number goes on to a list of recipients, prefixed with
the sender, and the sender gets no reply. `reply` is the Messaging SWML method
that sends a message; its `to` defaults to the sender, so naming `to` is what
turns a reply into a forward. The reference's own example is headed "Forward an
inbound message to another number".

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

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

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

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

# who gets the copies, comma separated, E.164
RECIPIENTS = [n.strip() for n in os.getenv("FORWARD_TO", "+15550100001,+15550100002")
              .split(",") if n.strip()]

# SignalWire fetches the document 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")

# the carrier keywords; see handle-opt-outs-yourself for what to do with them
STOP_WORDS = {"stop", "stopall", "unsubscribe", "cancel", "end", "quit"}
# the platform's maximum SMS body, which the sender prefix eats into
MAX_BODY = 1600


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


def keyword(body):
    """The bare word a phone sent, with the punctuation people add."""
    return (body or "").strip().strip(".!? ").lower()


def targets(sender, received_on, recipients=None):
    """Everyone on the list once, except the sender and the receiving line.

    Leaving the receiving line in would text the number that just fired this
    webhook, which fires it again and forwards a second copy to everyone.
    """
    skip = {digits(sender), digits(received_on)}
    out = []
    for r in (RECIPIENTS if recipients is None else recipients):
        if digits(r) not in skip:
            skip.add(digits(r))          # a repeated entry is still one copy
            out.append(r)
    return out


def forwarded_body(sender, body):
    """The sender, then their words, inside the platform's body limit."""
    prefix = f"{sender}: "
    return prefix + (body or "")[:MAX_BODY - len(prefix)]


def forward_document(sender, received_on, body, recipients=None):
    """One reply per recipient, from the number that received the text."""
    steps = []
    if keyword(body) not in STOP_WORDS:
        for recipient in targets(sender, received_on, recipients):
            # `to` is what makes this a forward rather than a reply
            steps.append({"reply": {"to": recipient, "from": received_on,
                                    "body": forwarded_body(sender, body)}})
    # an opt-out is for you, not for the team; an empty document sends nothing
    return {"version": "1.0.0", "sections": {"main": steps}}


app = Flask(__name__)


@app.before_request
def gate():
    auth = request.authorization
    if not (auth and auth.username == AUTH_USER and auth.password == AUTH_PASSWORD):
        abort(Response(status=401, headers={"WWW-Authenticate": 'Basic realm="forward"'}))


@app.post("/inbound")
def inbound():
    payload = request.get_json(force=True, silent=True) or {}
    m = payload.get("message") or {}
    # the webhook's schema requires both; without them there is nothing to do
    if not (m.get("from") and m.get("to")):
        return jsonify({"error": "message.from and message.to are required"}), 400
    return jsonify(forward_document(m["from"], m["to"], m.get("body")))


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

/**
 * Forward an inbound SMS to other numbers.
 *
 * A text arriving on your number goes on to a list of recipients, prefixed
 * with the sender, and the sender gets no reply. `reply` is the Messaging SWML
 * method that sends a message; its `to` defaults to the sender, so naming `to`
 * is what turns a reply into a forward. The reference's own example is headed
 * "Forward an inbound message to another number".
 *
 * Written against @signalwire/sdk 2.0.5 and node:http.
 *
 *     npm start            # serves POST /inbound
 */
import "dotenv/config";
import { createServer, type IncomingMessage } from "node:http";

// who gets the copies, comma separated, E.164
export const RECIPIENTS = (process.env["FORWARD_TO"] ?? "+15550100001,+15550100002")
  .split(",").map((n) => n.trim()).filter(Boolean);
const AUTH_USER = process.env["SWML_BASIC_AUTH_USER"] ?? "";
const AUTH_PASSWORD = process.env["SWML_BASIC_AUTH_PASSWORD"] ?? "";

// the carrier keywords; see handle-opt-outs-yourself for what to do with them
const STOP_WORDS = new Set(["stop", "stopall", "unsubscribe", "cancel", "end", "quit"]);
// the platform's maximum SMS body, which the sender prefix eats into
const MAX_BODY = 1600;

const digits = (n: string | undefined) => (n ?? "").replace(/\D/g, "");

/** The bare word a phone sent, with the punctuation people add. */
const keyword = (body: string | undefined) =>
  (body ?? "").trim().replace(/^[.!? ]+|[.!? ]+$/g, "").toLowerCase();

/**
 * Everyone on the list once, except the sender and the receiving line.
 * Leaving the receiving line in would text the number that just fired this
 * webhook, which fires it again and forwards a second copy to everyone.
 */
export function targets(sender: string | undefined, receivedOn: string | undefined,
                        recipients = RECIPIENTS) {
  const skip = new Set([digits(sender), digits(receivedOn)]);
  const out: string[] = [];
  for (const r of recipients) {
    if (!skip.has(digits(r))) {
      skip.add(digits(r));               // a repeated entry is still one copy
      out.push(r);
    }
  }
  return out;
}

/** The sender, then their words, inside the platform's body limit. */
export function forwardedBody(sender: string, body: string | undefined) {
  const prefix = `${sender}: `;
  return prefix + (body ?? "").slice(0, MAX_BODY - prefix.length);
}

/** One reply per recipient, from the number that received the text. */
export function forwardDocument(sender: string, receivedOn: string,
                                body: string | undefined, recipients = RECIPIENTS) {
  const steps: Record<string, unknown>[] = [];
  if (!STOP_WORDS.has(keyword(body))) {
    for (const recipient of targets(sender, receivedOn, recipients)) {
      // `to` is what makes this a forward rather than a reply
      steps.push({ reply: { to: recipient, from: receivedOn,
                            body: forwardedBody(sender, body) } });
    }
  }
  // an opt-out is for you, not for the team; an empty document sends nothing
  return { version: "1.0.0", sections: { main: steps } };
}

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

/** POST /inbound, behind the basic auth in the URL you give SignalWire. */
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 send = (status: number, body: unknown,
                  headers: Record<string, string> = {}) => {
      res.writeHead(status, { "content-type": "application/json", ...headers });
      res.end(JSON.stringify(body));
    };
    // the credentials decide before the body is read
    if (!AUTH_USER || req.headers.authorization !== expected) {
      return send(401, {}, { "www-authenticate": 'Basic realm="forward"' });
    }
    if (req.method !== "POST" || req.url !== "/inbound") return send(404, {});
    const raw = await readBody(req);
    let payload: { message?: Record<string, string> } = {};
    try { payload = JSON.parse(raw); } catch { return send(400, { error: "bad json" }); }
    const m = payload.message ?? {};
    // the webhook's schema requires both; without them there is nothing to do
    if (!m["from"] || !m["to"]) {
      return send(400, { error: "message.from and message.to are required" });
    }
    send(200, forwardDocument(m["from"], m["to"], m["body"]));
  }).listen(port);
}

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

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # basic auth and FORWARD_TO, comma separated
python app.py                    # serves POST /inbound on :8080

The TypeScript surface is the same handler on node:http, on Node 20.18.1 or newer:

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

Point the number’s message handler at https://user:pass@your-host/inbound and text it.

Verify it

No network, no account.

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

The verifier drives the route with payloads shaped like the spec’s inbound message webhook. The configured list carries a repeat and the receiving line, so the ordinary rows exercise both guards. It asserts the following.

every document is checked against the documented Messaging method set, not the bundled schema, which is the Calling one and would accept the wrong method
a customer’s text renders one reply per recipient with to, from the receiving line, and the prefixed body
the sender, the receiving line and the repeated entry are each left out, so two people on shift get one copy each
a text from one recipient renders one reply, to the other
a 1600 character body is truncated so the whole message is exactly 1600 with the prefix
a media-only text forwards the prefix and nothing more
“STOP.“ with stray spaces renders an empty document
the payload carries every field the spec requires, and the spec requires from, to and body
a payload missing from or to is a 400, and a post without credentials is a 401
the TypeScript surface renders the same five documents and the same two refusals

Report an issue