Send an SMS

Messagingprogrammable SMS

Send an SMS with one REST call, and handle a request that fails.

Also called send a text message, SMS API, programmable SMS

smswebhooks

The claim

Sending a message is trivial. Handling the outcome is the part tutorials skip. A queued message is not a delivered one, and carrier rejections arrive later on a status webhook rather than in the API response.

How it works

RestClient().compat.messages.create(From=..., To=..., Body=..., StatusCallback=...) posts to the Compatibility Messages endpoint (/api/laml/2010-04-01/Accounts/<project>/Messages). It returns as soon as the message is accepted: status is queued. Delivery, failure and carrier filtering arrive afterwards as POSTs to StatusCallback with MessageSid, MessageStatus and, on failure, ErrorCode.

The webhook handler keys on (MessageSid, MessageStatus) and ignores a pair it has already seen, so a carrier retry of delivered runs your side effect once. Idempotency is your handler’s job; the platform does not de-duplicate callbacks for you.

Two other ways to send the same message: SWML send_sms from inside a call (see text-the-caller-during-the-call), and RelayClient.send_message over a RELAY WebSocket. The SDK’s typed RestClient has no native messages namespace in 3.0.x; the Compatibility endpoint is the supported REST path.

Limitations

A 201 means accepted, never delivered. Treat the status webhook as the source of truth, and make the handler idempotent - it can fire more than once for the same message.

What to change first

Send to an invalid number and watch which failure surfaces synchronously versus on the webhook.

Where this sits

Before this

Buy a number and point it at your app

Reply to an inbound SMS Handle call status callbacks

python/app.py

"""Send an SMS, and treat the status callback as the truth.

The send response says "queued" or "accepted". Delivery, undelivered and failed
arrive later on the status callback - and a callback can arrive more than once,
so the handler is idempotent on (sid, status).

Written against signalwire-sdk 3.0.1 (the Compatibility Messages endpoint via
RestClient.compat).
"""
import os

from dotenv import load_dotenv
from flask import Flask, request
from signalwire.rest import RestClient

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

app = Flask(__name__)

# RestClient reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
# from the environment when not passed explicitly.
client = RestClient()

TERMINAL = {"delivered", "undelivered", "failed"}
seen = set()


def send(to, body):
    """Accepted is not delivered. Return the sid and wait for the callback."""
    msg = client.compat.messages.create(
        From=os.environ["SIGNALWIRE_PHONE_NUMBER"],
        To=to,
        Body=body,
        StatusCallback=os.environ["PUBLIC_URL"] + "/sms-status",
    )
    app.logger.info("accepted sid=%s status=%s", msg.get("sid"), msg.get("status"))
    return msg.get("sid")


@app.post("/sms-status")
def sms_status():
    sid = request.form.get("MessageSid")
    status = request.form.get("MessageStatus")
    # Callbacks can repeat. Same (sid, status) twice must do nothing twice.
    key = (sid, status)
    if key in seen:
        return "", 204
    seen.add(key)
    if status in TERMINAL:
        on_terminal(sid, status, request.form.get("ErrorCode"))
    return "", 204


def on_terminal(sid, status, error_code):
    """Runs exactly once per (sid, terminal status). Put your side effects here."""
    app.logger.info("terminal sid=%s status=%s err=%s", sid, status, error_code)


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

Run it

cd python
pip install -r requirements.txt
python app.py
# in another shell, once PUBLIC_URL is reachable from SignalWire:
python -c "import app; print(app.send('+15552223333', 'Your table is ready.'))"

Verify it

No network, no account:

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

It swaps the REST client’s HTTP layer for a recorder, then checks the POST path and fields against tools/openapi/compat.json. It drives the status webhook with duplicate and non-terminal callbacks, and asserts the side effect fires exactly once per terminal status.

Report an issue