SMS consent, STOP and one send gate

I was about to hand a project over to the client's new developer when I made one last test call. The agent found a property, asked whether I wanted it by text, and I said yes. "I just sent you a text," it said. I waited. Nothing arrived.

I checked the telephony logs. Not a failed message, not a blocked one. No message at all. The text had never been sent, because the code that sends it had never been called. The agent had logged my lead, skipped the send, and then described, fluently and confidently, an action it hadn't taken.

The model was a small, fast one, and the instruction to send the text lived only in the prompt. That is exactly the kind of instruction a fast model drops under pressure. Nothing in the system could tell the difference between the model saying a text was sent and a text being sent. So that became the design principle of the library on this page: the only trustworthy statement about a send is the provider's own answer.

Why texting is its own problem

Phoning someone back is easy. Texting them is regulated. In the United States, businesses that text customers register their campaigns with the carriers, and the people they text must have agreed, must be able to stop with a single word, and shouldn't be messaged at 3 a.m. Getting my client approved took real work, and once it was approved, the code had to behave as the registration promised.

The flow I built is a double opt-in. During the call, the caller agrees out loud to get a text. The first text only asks them to reply YES. Only a YES releases the property link. If they ask about several listings before replying, the properties queue up, and one YES delivers all of them. The first version of the code stored this as a pending record per phone number, with a timer so an old question couldn't be answered by a stray YES hours later.

Consent is a state, not a checkbox

Writing it out, consent has four states per phone number: no record, asked and waiting, opted in, and opted out. Everything else is an event that moves between them. Seeing it as a small state machine makes the rules obvious. STOP works from anywhere. Repeating STOP changes nothing. A YES from someone we never asked is ignored, because it isn't an answer to anything.

People don't type the keyword

A text message is not a form field. The same intent arrives as "STOP", "stop pls 🙏", "parar", or with an invisible character in the middle. The classifier lowercases, strips accents and punctuation, drops emoji and zero-width characters, understands English and Spanish, and when a message could be read two ways, STOP wins. It deliberately does not treat "ok" or "sure" as YES, because those are too easy to say about something else.

One gate in front of every send

The second half of the design is a single function that every outgoing message passes through, a pure yes-or-no with a reason. It checks, from most to least fundamental: is there any text, did they opt out, do we have consent, does the message tell them how to opt out, and is it quiet hours where they are. It fails closed: no time zone, no send.

import { guardSend } from '@27colab/sms-consent';

guardSend({ status: 'opted_out' }, 'Sale today!', { timeZone: 'America/New_York' });
// { allow: false, reason: 'opted_out',
//   detail: 'Recipient opted out; only START re-enables messaging.' }

The gate has a second job, and it's the one that started this story. The guarded send function calls your provider only if the guard allows it, and it returns sent: true only if the provider call actually resolved. If the provider throws, you get a failure with a reason, not a success. That return value is what you hand back to the model, so the model's next sentence is based on the truth.

await handleInbound({ store, accountId, from: phone, body: 'STOP', replies });  // opted_in -> opted_out
const blocked = await sendGuarded({ ...base, body: 'Sale today! Reply STOP to opt out.' });
console.log(blocked.sent, !blocked.sent && blocked.reason);  // false 'opted_out'

Three smaller lessons

• Consent must survive a deploy. My first version kept it in a file inside the container, so every redeploy forgot who had said YES, and worse, who had said STOP. It now lives on persistent storage, and in the library behind a store interface you choose: in memory for tests, a database in production.
• Don't text what you can't link. If a listing had no public page, the agent shouldn't offer a text at all. A promise you can't keep is a worse experience than no offer.
• Route through the registration. Carrier approval attaches to a messaging service, not just a phone number, so sending through the service is the reliable path once the number is attached.

What this is not

• It is a reference implementation, not legal advice and not a compliance guarantee. Whether your program meets the TCPA, carrier rules or anything else depends on your content, your consent collection and your registration.
• Your phone provider may already intercept STOP, START and HELP on its own. This keeps your ledger in step with what recipients actually sent.
• It decides whether to send and records consent. It is not a provider SDK and it doesn't track delivery.

I built this with Claude as my pair, in the browser chat and later in Claude Code. I wrote the rules, tested against real calls, and decided what shipped.