An SMS chatbot that works in a demo and one that survives real customers differ mainly in architecture. The production version separates five concerns: receiving messages safely, enforcing opt-out rules, remembering context, running the agent and sending replies (or handing off to a person). Get those boundaries right and you can swap models, providers or channels without rewriting everything.
This guide describes a reference design drawn from Twilio and Meta documentation, CTIA guidance and common patterns in open-source gateways. It assumes you have read our Twilio SMS agent tutorial or built something similar.
What are the layers of an SMS agent?
- Webhook
- Compliance gate
- State store
- Agent loop + tools
- Outbound queue / human handoff
| Layer | Job | Must be deterministic? |
|---|---|---|
| Webhook | Validate signature, dedupe, enqueue | Yes |
| Compliance gate | STOP, HELP, consent checks, quiet hours | Yes |
| State store | History, memory, handoff flag, consent record | Yes |
| Agent loop | LLM call, tool selection, reply drafting | No |
| Outbound | Send, retry, length limits, delivery receipts | Yes |
Only one layer involves the model. Everything that has legal or financial consequences runs in ordinary code.
How should the webhook behave?
Keep it boring and fast.
- Validate the signature. Twilio signs requests with
X-Twilio-Signature(docs); Meta signs WhatsApp payloads withX-Hub-Signature-256. Reject anything that fails. - Deduplicate. Providers retry when they do not get a quick 2xx. Store the message ID (
MessageSidon Twilio) and ignore repeats, or you will send duplicate replies. - Enqueue and return. Push the message to a queue (SQS, Redis, a database table) and return immediately. A worker does the rest.
Why put a compliance gate before the LLM?
Opt-outs are legal records. Under the FCC's 2026 revocation order (FCC 26-67, effective November 25, 2026), if you use reply-text opt-outs you must accept seven words (stop, quit, end, revoke, opt out, cancel, unsubscribe) and honour them within ten business days at most. The CTIA guidelines go further and say natural phrases like "please opt me out" should also be acted on. Neither should depend on a model.
- Normalise textLowercase, trim punctuation and whitespace.
- Match keywordsSTOP family ends messaging; HELP returns a fixed support reply.
- Check consentIs this number opted in for this campaign or business?
- Check windowsQuiet hours for outbound; the 24-hour window on WhatsApp.
- Pass or blockOnly messages that clear every check reach the agent.
A useful refinement: let the LLM flag possible opt-out intent in ambiguous messages ("don't text me about this anymore"), but route those to a deterministic confirmation flow or human review rather than letting the model decide. Our opt-in and opt-out rules guide covers the legal details.
How should state and memory work?
Use the pair (customer number, your number) as the conversation key. Store three kinds of data separately:
- Short-term history. The last 10 to 20 messages, passed to the model on each turn. Trim by tokens, not message count.
- Long-term memory. A compact profile or summary (name, preferences, open orders) updated after each conversation. This keeps prompts small and cheap.
- Control state. Consent status, handoff flag, last inbound timestamp, verification status. This lives in your main database and is never edited by the model directly.
Do not treat the phone number as proof of identity. Numbers can be spoofed and are recycled when people change carriers. Gate anything sensitive behind a verified login link or one-time code; see SMS spoofing and AI agents.
How should the agent loop call tools?
The agent loop is a standard tool-calling loop: system prompt, memory, history and a list of tools. Two rules matter more over SMS than in a web chat:
- Least privilege. Give the model only the tools the use case needs. A booking bot needs
find_slotsandbook_slot, notsend_sms_to_any_number. - Approval for side effects. Reading data can be automatic; changing it (booking, cancelling, charging) should require an explicit "YES" from the verified user, checked in code.
If your tools come from MCP servers, the same rules apply, plus the risk of malicious tool descriptions. Our MCP for SMS agents guide covers that.
How do async replies and handoff work?
Async replies. For tasks that take minutes (checking availability across systems, waiting on a human), send a short acknowledgement ("Checking now, I'll text you back shortly") and follow up from the worker. On WhatsApp, a follow-up outside the 24-hour window must be an approved template, per Meta's pricing docs.
Human handoff. Model it as a state, not a one-off message:
- Triggers: a keyword ("AGENT", "HUMAN"), repeated failed answers, sensitive topics (complaints, medical or legal questions), or low confidence.
- On handoff: set
handoff=true, notify staff (helpdesk ticket, Slack, CRM) with a summary, and stop the bot replying. - On release: staff clear the flag, and the bot resumes with the human's messages included in history.
Managed tools package these pieces. Twilio's Conversation Orchestrator and Conversation Memory reached general availability in May 2026 (changelog), and helpdesk platforms such as Intercom Fin and Zendesk build handoff in. See our AI SMS customer support guide for how businesses use them.
How does this extend to other channels?
The same five layers work for WhatsApp, RCS, iMessage and Telegram. What changes is the webhook adapter and the compliance gate: 10DLC and TCPA for US SMS, the 24-hour window and templates for WhatsApp, PECR for UK marketing texts. The open-source OpenClaw gateway follows this pattern, with per-channel adapters feeding one agent, and treats inbound room content as untrusted. For a channel-by-channel view of consumer agents, see getpersonalaiagents.com's guide to how personal AI agents work.
- Layers in the reference design
- 5
- Layers that involve the LLM
- 1
- Opt-out words to accept (FCC 2026 order)
- 7
- Maximum to honour an opt-out
- 10 business days
Bottom line
Keep the model in a box. Signature checks, deduplication, opt-outs, consent, identity and handoff should all be plain code with tests. The LLM drafts replies and picks from a short list of tools. That split makes the system cheaper to run, easier to audit and much harder for a hostile text to misuse.



