Handling WhatsApp STOP Replies: Opt-In, Opt-Out Webhook, CRM
A customer replies "STOP" to your WhatsApp message. What happens next — and what's still left for you to do? With TextMeFlow: nothing, because the opt-out is handled automatically at the API level. But if your CRM or ticketing system isn't listening, that person stays on your own lists as if nothing happened. This article explains how the opt-in/opt-out mechanism works and how to connect it to your own systems.
Note: this is general information about how our pipeline works, not legal advice on your obligations under the GDPR or ePrivacy rules — consult a lawyer for that.
The opt-in preamble: automatic unless you turn it off
On the very first message to a new recipient, TextMeFlow automatically adds a short line in front of your message:
Hi! You're receiving these messages from {sender}. Reply STOP to stop.
That (account, recipient) pair is remembered for 90 days — after that, later messages go through unchanged. This preamble is the cheapest insurance against a Meta ban there is, and it is on by default. You can turn it off per account in the portal, for example for booking flows where the recipient already gave explicit consent on your own form and the STOP text feels redundant. Note: turning off the preamble does not turn off the underlying new-contact count — that keeps running for the risk score. You can read more about that score and what makes it climb in our explanation of the risk score.
Which words trigger an opt-out
TextMeFlow recognizes several variants, not just the English "STOP": STOP, STOPP, ARRÊT, BASTA, STOPPEN and UNSUBSCRIBE are all treated as an opt-out request, regardless of the language you send in yourself. You don't need to build any keyword matching for this — it happens at message level before the message ever reaches your own webhook.
What happens after a STOP
As soon as a recipient sends back one of those words, TextMeFlow registers an opt-out for that specific (account, recipient) pair. From that moment on, all later sends to that number are rejected with the error code recipient_opted_out — even if you accidentally try again from a script or a bulk import. That is a hard block at API level, not something you still have to check before sending a message. If you try anyway, that also counts toward your risk score (+50 points) — one more reason to keep your own system in sync instead of continuing to send blindly.
The opt_out webhook: keeping your CRM in sync
Blocking the send is your safety net, but you don't want to wait for every send to fail to know who has unsubscribed. That's why TextMeFlow sends a webhook event of type opt_out (configurable) at the moment of the opt-out itself. A minimal handler looks like this:
app.post('/webhooks/textmeflow', (req, res) => {
const { event, data } = req.body;
if (event === 'opt_out') {
crm.markUnsubscribed(data.recipient, {
channel: 'whatsapp',
optedOutAt: data.timestamp,
});
}
res.sendStatus(200);
});
For the full list of events and how to verify the HMAC signature of each call, see our guide to webhooks. Without this link, your own CRM or email tool risks showing someone as an "active customer" while WhatsApp has been closed for that person for months — confusing for support, and an unnecessary obstacle if the customer later gives consent again and you need a fresh opt-in moment.
In practice: what this means for you
- Don't build your own STOP detection — it's already in the pipeline, for several languages at once.
- Don't rely only on the error code when sending; subscribe to
opt_outso your CRM is up to date immediately, not only at the next failed send. - Leave the opt-in preamble on unless you're sure your recipients already went through your own consent form.
- Test it yourself: send yourself a message, reply STOP, and check that your
opt_outwebhook comes in and that a second send to that same number is indeed rejected withrecipient_opted_out.
Want to know more about how the full anti-spam pipeline fits together, including rate limits and quiet hours? See the full anti-spam policy. Want to try it yourself? Start free with 50 messages a month, forever — no credit card needed.
Want to send WhatsApp messages via API yourself?
Free forever up to 50 messages/month. Scan a QR and send your first message within 5 minutes.
Free forever