Reply to an inbound SMS

Messagingtwo-way SMS

Receive a text and answer it in the same thread.

Also called SMS autoresponder, two-way SMS, SMS keyword reply

sms

The claim

Inbound messaging is a webhook that returns a messaging SWML document. The reply verb answers the sender on the number they texted; an inline switch branches the body on a keyword with no server at all. The Python surface does the same branching in code and shows where MMS attachments arrive.

How it works

Markup only: the whole handler is one document.

- reply:
    switch:
      variable: message.body
      transform: lowercase_trim
      case:
        hours: "We are open Monday to Friday, nine to five, Eastern time."
        help:  "Text HOURS for opening hours, or STOP to unsubscribe."
        stop:  "You have been unsubscribed and will receive no more messages."
      default: "Thanks for your message. A person will reply shortly."

Python: SignalWire POSTs the documented inbound-message payload (message.from, message.to, message.body, message.media[] with url and content_type) and executes whatever document the handler returns:

{"version": "1.0.0", "sections": {"main": [{"reply": {"body": "..."}}]}}

Attachments on an MMS are URLs in message.media; download them from the handler. reply can also attach media to answer with an MMS, and takes a status_url for delivery callbacks (see send-an-sms for handling those).

*STOP is your job.* SignalWire does not manage opt-outs; the handler records the sender so nothing is sent to them later. The full pattern is handle-opt-outs-yourself.

What to change first

Replace the static replies with run-the-same-agent-over-text: forward the body to the AI Chat API and reply with the agent’s answer.

Where this sits

Before this

Buy a number and point it at your app

Send an SMS

Run the same voice AI agent over text chat

python/app.py

"""Reply to an inbound SMS.

SignalWire POSTs the inbound message to this URL and executes the messaging
SWML document it returns. `reply` answers the sender on the same number. The
branching happens in Python here; swml/agent.yaml does the same with an inline
switch and no server at all.

Written against the documented inbound-message webhook payload and messaging
SWML `reply` (docs: swml/reference/messaging/reply).
"""
import os

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

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

app = Flask(__name__)

REPLIES = {
    "hours": "We are open Monday to Friday, nine to five, Eastern time.",
    "help": "Text HOURS for opening hours, or STOP to unsubscribe.",
    "stop": "You have been unsubscribed and will receive no more messages.",
}
DEFAULT = "Thanks for your message. A person will reply shortly."

opted_out = set()
received_media = []


def reply_for(message):
    """Pick the reply body for an inbound message dict (the webhook's `message`)."""
    body = (message.get("body") or "").strip().lower()
    sender = message.get("from")
    for m in message.get("media") or []:
        # MMS attachments arrive as URLs; download them from here.
        received_media.append(
            {"from": sender, "url": m["url"], "content_type": m["content_type"]})
    if body == "stop":
        # SignalWire does not manage STOP for you (see handle-opt-outs-yourself).
        opted_out.add(sender)
    if message.get("media") and not body:
        return "Got your picture, thanks."
    return REPLIES.get(body, DEFAULT)


def swml_reply(text):
    return {"version": "1.0.0", "sections": {"main": [{"reply": {"body": text}}]}}


@app.route("/sms", methods=["POST"])
def inbound():
    payload = request.get_json(force=True, silent=True) or {}
    message = payload.get("message") or {}
    return jsonify(swml_reply(reply_for(message)))


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

# Reply to an inbound SMS - a messaging SWML document, no server.
# Assign this as a number's message handler. `reply` answers the sender; the
# inline switch branches on the message body (lower-cased, trimmed).
version: "1.0.0"
sections:
  main:
    - reply:
        switch:
          variable: message.body
          transform: lowercase_trim
          case:
            hours: "We are open Monday to Friday, nine to five, Eastern time."
            help: "Text HOURS for opening hours, or STOP to unsubscribe."
            stop: "You have been unsubscribed and will receive no more messages."
          default: "Thanks for your message. A person will reply shortly."

Run it

Markup only: paste swml/agent.yaml into a SWML Script and assign it as a phone number’s message handler.

Python:

cd python
pip install -r requirements.txt
python app.py

Set the number’s message handler to https://<your-host>/sms.

Verify it

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

It drives the webhook with the documented payload and asserts:

the returned document is a reply whose body follows the keyword
a media-only MMS records the attachment URL
STOP is recorded
the YAML switch covers the same keywords

Report an issue