Manage the WhatsApp stop-list on BSG

A "stop-list" (or suppression list) holds recipients you should not message. With BSG's WhatsApp channel there are two separate stop-lists, and they work differently — one you manage, one is managed by Meta. This guide explains both, how each affects sending, and an important caveat about SMS fallback.

The two stop-lists at a glance

1. The BSG platform stop-list (you manage it)

This is BSG's own suppression list, shared across channels. Each entry is a phone number flagged for one or more types: sms, viber, rcs, whatsapp, telegram, voice. A number can be suppressed on some channels and not others — include whatsapp in the types to suppress it for WhatsApp.

You manage it through the OneAPI stop-list methods — each page has the full request format, parameters, and examples:

• Add numbers — Add Contacts to Stop List. Pass the phone numbers and the channel types (include whatsapp).
• Remove numbers — Remove Contacts from Stop List. Detach a contact from one or more types.
• View the list — Get Blacklisted Contacts. Filter by type to see your WhatsApp entries.
• Search a number — Search Contacts in Stop Lists. The result shows a per-channel flag, so you can see whether a number is suppressed for WhatsApp specifically.

You can also try any of these calls in the Swagger explorer.

How it affects sending: the campaign send (Send WhatsApp campaign) has a stop-list check that is on by default — BSG skips any recipient found on your platform stop-list. Turn it off only if you deliberately want to ignore the list.

Single sends don't check it. The Send Single WhatsApp Message method has no stop-list check, so single sends aren't filtered against the platform stop-list — enforce suppression yourself if you send that way.

2. Meta's WhatsApp stop-list (read-only)

This list reflects opt-outs recorded on Meta's side — for example when a recipient taps "Stop promotions" / the opt-out button on a marketing message. You can view it but not edit it, via List of WhatsApp stop list contacts.

Each entry identifies the recipient, the WABA, and when the opt-out was added. Meta enforces this list at delivery — a send to an opted-out user simply isn't delivered, surfacing as the marketing opt-out error 131050. Because it's Meta-managed, there's no add/remove method; BSG gives you read-only visibility.

⚠️ Important: SMS fallback can bypass a WhatsApp opt-out or block

If you attach an SMS fallback (the alternative-channel option) to a send, it fires whenever the WhatsApp message comes back undeliverable. Blocking your sender on WhatsApp — or being opted out on WhatsApp — is one of the things that makes a message undeliverable. So:

A contact who blocked you on WhatsApp (or opted out there) can still receive your SMS fallback, because the WhatsApp stop-list/opt-out does not suppress SMS.

There's no separate SMS stop-list — SMS is governed by the same global BSG platform stop-list, but the fallback is checked only against its sms type. So a number flagged only for whatsapp isn't suppressed for SMS.

To honor an opt-out across every channel, add the number to the platform stop-list for all relevant types (whatsapp, sms, and any other fallback channel) in a single Add Contacts to Stop List call. That way the WhatsApp send is skipped and, if it ever reaches the fallback, the SMS is skipped too.

Best practices

• Keep the campaign stop-list check on (its default) so your platform list is always honored.
• When a contact opts out, suppress them on every channel you might reach them on — add both whatsapp and sms (and any other fallback types) in one call. Don't rely on the WhatsApp opt-out alone if you use SMS fallback.
• Treat the Meta WhatsApp stop-list as the source of truth for WhatsApp opt-outs — reconcile it into your own suppression logic (and your platform stop-list) so you don't repeatedly attempt opted-out users.
• For single sends, apply your own stop-list check before calling the API, since the method doesn't do it for you.

Related guides

• BSG WhatsApp API Overview — sending, SMS fallback, and delivery statuses.
• Common WhatsApp API errors — including the opt-out error 131050.
• Getting started with 1-way WhatsApp on BSG — connecting your account and configuring sends.