How to handle WhatsApp STOP and opt-outs in your app
A customer replied STOP on WhatsApp. What must your app do? Honour the opt-out everywhere, block the next send, log it, and let people opt back in, with a tested webhook handler and the exact error to expect.
November 19, 2026 · 8 min read
Someone replies "STOP" to your WhatsApp message. Within minutes, a cron job, a drip sequence or a teammate's bulk send may message them again. This guide is about making sure that does not happen: what the opt-out rule says, what your app has to do, and a small webhook handler you can run and test before you rely on it.
SendFromChat is an independent product and is not affiliated with Meta or WhatsApp. The policy wording below comes from the WhatsApp Business Messaging Policy, read on 19 Nov 2026 through a fetch tool that returns excerpts (see Sources). This is not legal advice. If you message people in the EU or UK, ask a lawyer how consent and marketing rules apply to your case.
What was tested. The handler below was run locally on Node v24 and exercised with curl-style requests: a correctly signed contact.opted_out (200, number blocked), a missing signature (401), a wrong secret (401), and a signed contact.opted_in (200, number allowed again). It was not run against a live SendFromChat account or a live WhatsApp number. The event names, headers and error type come from our REST API reference.
The short version
- Meta's policy says to respect opt-outs. The WhatsApp Business Messaging Policy says you "must respect all requests (either on or off WhatsApp) by a person to block, discontinue, or otherwise opt out".
- Treat STOP as a request, not a keyword. Apply it to every channel of yours that sends WhatsApp messages: bulk sends, sequences, scripts, and people.
- Store it in one place and check it before every send, not only before marketing sends.
- Confirm it with one short message, then stay quiet.
- Let people opt back in on their own words, such as START.
- Tell people how to opt out in your first message, before they have to hunt for a block button.
What the policy asks of you
Two parts of the policy matter here. On opt-in, it says you may only contact people on WhatsApp if they have given you their number and given opt-in permission "confirming that they wish to receive subsequent messages or calls from you". On opt-out, the sentence above applies, and the policy's best-practice section also suggests giving "clear instructions for how people can opt out of receiving specific categories of messages or calls" and honouring those requests.
Two details are easy to miss:
- The wording covers requests made on or off WhatsApp. An email saying "please stop messaging me on WhatsApp" is a request too.
- A person can also block you inside WhatsApp. This guide covers the replies and requests you can see; a block is something you may only notice as sends that stop being delivered. Check delivery status (see tracking sent, delivered and read) rather than assuming.
How Meta treats complaints and quality is a separate topic: see sending in bulk without getting banned and WhatsApp opt-in.
Step 1: decide which words count
Pick a small, written list and show it to people. A common starting point is STOP, UNSUBSCRIBE and OPT OUT. Two choices to make deliberately:
- Whole message or contains? Matching only a message that is exactly the word avoids opting someone out because they wrote "please don't stop the delivery". Matching "contains" catches more real requests but opts out the wrong people. Whichever you pick, a human should still read anything that looks like an opt-out request but did not match.
- Case and spacing. Treat "stop", "Stop " and "STOP" the same.
SendFromChat's inbox does this for you and it is always on: a message that is exactly STOP, STOP ALL, UNSUBSCRIBE or OPT OUT marks the person opted out and sends your confirmation text, and START, SUBSCRIBE or UNSTOP opts them back in (inbox and auto-replies docs). Our reading of the code (lib/optout.ts) is that the list also includes OPT-OUT and OPTOUT; the docs list the first four.
Step 2: one source of truth
Keep one table or set of opted-out numbers, in E.164 format (+14155550132), and read it everywhere a message can be sent. A typical way this goes wrong is two systems that each keep their own list: the support tool honours STOP, and the nightly script never hears about it.
If you use SendFromChat, the opt-out is stored on the contact. Opted-out numbers are skipped by bulk sends and never enrolled in sequences, and skipped numbers are not charged against your allowance (contacts and bulk sends docs).
Step 3: block the send, and know what your tool does not block
Through the REST API, a template send to an opted-out number is refused with HTTP 422 and this error:
{ "error": { "type": "opted_out", "message": "…" } }
Handle opted_out as a normal outcome, not a crash: mark the job as skipped, not failed, and do not retry it. A retry loop on a refused send is the same mistake as the original send.
One detail to know. Our reading of the code (lib/services/messages.ts:123) is that only template sends are checked against the opt-out. The docs say the same ("Template sends to opted-out numbers are refused", sending messages). A free-form reply that a person triggers by writing to you is a different situation: if the 24-hour window is open and they have just messaged you, replying is normal. Your own scripts should still not start new conversations with someone who asked to stop, so check your own list too. For the window rules, see the 24-hour window.
Step 4: listen for the opt-out event
If your app has its own database, subscribe to the contact.opted_out and contact.opted_in webhook events and mirror them. Each carries phone and at. Every request body looks like { "id": "evt_…", "type": "…", "created": "…", "data": { … } }, and deliveries can repeat, so handling the same event twice must be harmless. Adding a number to a set twice is.
The handler below verifies the SendFromChat-Signature header (an HMAC-SHA256 over <t>.<raw body>, with a five-minute timestamp limit), answers 200 first, and then updates the set. Replace the in-memory set with a database table.
import http from "node:http";
import crypto from "node:crypto";
const SECRET = process.env.WEBHOOK_SECRET; // shown once when you create the endpoint
const optedOut = new Set(); // use a database table in real life
function verify(raw, header) {
const parts = Object.fromEntries((header ?? "").split(",").map((p) => p.split("=")));
if (!parts.t || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac("sha256", SECRET).update(`${parts.t}.${raw}`).digest("hex");
const a = Buffer.from(expected), b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
export const server = http.createServer((req, res) => {
let raw = "";
req.on("data", (c) => (raw += c));
req.on("end", () => {
if (!verify(raw, req.headers["sendfromchat-signature"])) { res.writeHead(401).end(); return; }
res.writeHead(200).end(); // answer first, work after
const event = JSON.parse(raw);
if (event.type === "contact.opted_out") optedOut.add(event.data.phone);
if (event.type === "contact.opted_in") optedOut.delete(event.data.phone);
});
});
export const canMessage = (phone) => !optedOut.has(phone);
Call canMessage(phone) at the top of every job that sends. To start the server, add server.listen(3000). To check your own copy, send it a signed body yourself (compute the v1 value the same way) and confirm that a wrong secret or a missing header returns 401. For more on webhook problems, see WhatsApp webhook not working.
Step 5: confirm once, then stay quiet
Reply to a STOP with one short message that says it worked and how to come back. For example:
You're unsubscribed and won't get more messages from us. Reply START any time to subscribe again.
No discount offer, no "are you sure". Keep it to one message. In SendFromChat, the text is yours to edit under Auto-replies (or update_auto_replies from your assistant).
Step 6: opt-in again, and tell people about STOP up front
If someone replies START, record the new opt-in with the date. Keep the date of the opt-out too: if a complaint arrives later, "they opted out on this date and we sent nothing after it" is a sentence you want to be able to say.
Put the instruction in your first template or in the welcome message ("Reply STOP to opt out"). It costs a few words and is exactly the "clear instructions" the policy suggests. Sequences that stop on reply help in a related way: with stop-on-reply on, a person who answers leaves the sequence, and a person who replies STOP is marked as stopped for that reason (drip sequences docs).
A checklist before your next send
- The opt-out list lives in one place, and every sender reads it.
- Your first message says how to stop.
-
opted_outerrors are treated as "skip", not "retry". - Requests made by email, phone or support chat reach the same list.
- You keep the date of each opt-out and opt-in.
- Someone reads messages that look like opt-outs but did not match your words.
Using SendFromChat for this
SendFromChat handles the STOP and START words, blocks template sends, skips opted-out numbers in bulk sends and sequences, and sends the contact.opted_out event to your app. Every feature is on every plan. Plans differ in numbers, seats and messages you start. The 30-day free trial needs no card, and a $9/month founding offer for 12 months is available with a personal 1:1 onboarding from the founder. Start the free trial or read the REST API reference.
Sources
Policy pages read on 19 Nov 2026 through a fetch tool that returns excerpts; we have not compared them against the primary text by eye, so check anything critical on the page.
- WhatsApp, WhatsApp Business Messaging Policy: opt-in permission wording, "must respect all requests (either on or off WhatsApp) by a person to block, discontinue, or otherwise opt out", best practice on opt-out instructions.
- SendFromChat docs: inbox and auto-replies (STOP and START), REST API (events, signature,
opted_out), sending messages, contacts and bulk sends, drip sequences. - SendFromChat code, our reading:
lib/optout.ts,lib/services/messages.ts:123.
Do this from your AI assistant
SendFromChat connects Claude, ChatGPT, Cursor or any MCP client to the WhatsApp Business API — templates, bulk sends, inbox, chatbots and sequences, just by asking. 30 days free, no card.
Start freeMore guides
WhatsApp Cloud API webhook not working? A step-by-step checklist
Meta's WhatsApp webhook won't verify, or verifies but sends nothing? Work through six checks in order (verify token, public HTTPS, subscribed field, overrides, signature, 200 reply) with a tested Node receiver and curl commands.
Retry WhatsApp API sends without double-sending: idempotency keys, timeouts and 429s
How to retry a failed WhatsApp send safely. An Idempotency-Key example in Node, what the API does on a replay, a timeout, a 409 or a 429, and which errors you should never retry. Tested against a local mock.
Send a WhatsApp message with cURL: copy-paste commands
Send a WhatsApp template message from the command line with cURL. Check your key, send with a test key first, retry without double-sending, read the status, and a short shell script that handles the errors.
WhatsApp template variables: how to fill the parameters from the API (and why a send says missing_variables)
How to fill {{1}}, {{2}} and {{3}} in a WhatsApp template from code, with curl and Node examples, a check that counts the values before you send, and what the 132000 and 132012 errors mean when a send does reach Meta.