Opt-outs

When someone texts one of your numbers, Bird reads the message against a catalogue of keywords and acts on it before you see it. A recognised stop keyword suppresses your future messages to that person, a start keyword releases them again, and help answers with your support information. This happens with no setup on your side, because honouring an opt-out is not something a sender should have to opt into.

This guide covers what Bird does by default, how to see it, and how to change it.

What happens by default

A subscriber texts STOP to one of your numbers. Bird:

Recognises it against the keyword catalogue for that number's country.
Records a suppression on that exact sender-and-subscriber pair.
Confirms it by replying with the opt-out message for that country.

From then on, a send from that sender to that subscriber is refused with E12077 SMSRecipientSuppressed instead of going out. A START ends the suppression and confirms that too, and HELP replies without changing anything.

A suppression covers one sender and one subscriber, not your whole workspace. Someone who opts out of one of your numbers still hears from the others, which is what lets a customer stop your marketing number and keep getting delivery notifications from your transactional one.

The confirmation is exempt from the suppression it concerns. Bird answers a subscriber who just texted you even when you may no longer message them, because a reply to a message someone just sent is not traffic pushed at them.

Coverage is per country

Bird's catalogue covers a subset of countries, not all of them. Where a country is covered, opt-out, opt-in, and help are answered out of the box. Where it is not, no keyword is recognised, nothing is answered, and no opt-out is recorded, so if you send to a country Bird's catalogue does not cover, you are responsible for honouring opt-outs there yourself.

Which countries are covered is visible on the Keyword rules page in the dashboard, filtered by country. A country with no rules there recognises nothing.

Changing what Bird replies

Bird's default replies are correct but generic. To answer in your own name, use the Keyword rules page in the dashboard: that is where you replace the wording for a country and add campaign keywords of your own. What you cannot change is what an opt-out or opt-in keyword does, which is fixed so the guarantee holds however the replies are worded.

Reading and managing suppressions

GET /v1/sms/suppressions lists the pairs your messages are currently stopped for, most recent first. Filter by destination to check one subscriber before sending to them, by originator for one of your senders, or by reason:

keyword_stop: the subscriber texted a stop keyword.
carrier_opted_out: their carrier reported the opt-out.
manual: added through the API or the dashboard.

Suppressions that have ended are not listed, so what you get back is the answer to "who can I not message right now".

You can add one yourself, honouring an opt-out a customer gave you on the phone, say:

Contoh kode

bird sms suppressions add --destination +15550001234 --originator +15557654321

A manual suppression blocks every category, including transactional, and adding is idempotent. Removing one is deliberately narrow: only a manual suppression can be ended this way. A subscriber's own stop keyword and a carrier's opt-out are refused, because those are not yours to reverse.

Next steps

Sending SMS: categories, senders, and what a send is refused for
Events: the sms.* events a send and its outcome emit
SMS log: the per-message view, including refused sends