Opt-outs and keywords

When someone texts one of your numbers, Bird checks the message against a catalog of keywords before you receive it. A recognized stop keyword suppresses future messages from that sender to the subscriber, a start keyword ends the suppression, and help replies with support information. Supported countries need no setup for this behavior.

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:

Recognizes it against the keyword catalog 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. It does not cover your whole workspace. Someone who opts out of one of your numbers still hears from the others, so they can stop marketing messages while keeping delivery notifications. To stop every sender in the workspace at once, see Opting out of every sender below.

The confirmation is exempt from the suppression it records. Bird can answer the inbound message even though the new suppression blocks later outbound sends.

Coverage is per country

Bird's catalog covers a subset of countries. Where a country is covered, Bird handles opt-out, opt-in, and help keywords by default. Where it is not, Bird recognizes no keyword, sends no reply, and records no opt-out. If you send to an uncovered country, you must honor opt-outs yourself.

Check what a country has before you rely on it:

Exemplo de código

bird sms keyword-rules list --country NL

An empty result means the country has no coverage. You can add your own custom keywords there, but every other operation replaces something Bird ships, so you can create one only for a country in Bird's catalog.

Seeing what applies

GET /v1/sms/keyword-rules answers "what happens when someone replies to my numbers". Unfiltered, it returns Bird's whole catalog alongside any rules you have created; narrow it with country, number, operation, or scope:

scope=system returns only Bird's catalog, including the default a workspace rule replaced.
scope=workspace returns only your own rules.
number=+18005551234 returns the rules that apply to one of your numbers, in the order they are applied to an inbound message; add from_country to see what a sender messaging from elsewhere gets, which can differ.

Rules come back most specific first, and each carries effective_keywords: Bird's set for that operation and country plus anything you added.

The list returns two operations beyond stop, start, and help:

info replies with your program information and behaves exactly as help does. It is separate so a country whose INFO answer must differ from its HELP answer can carry both; where Bird ships no info rule for a country, INFO is one of that country's help keywords and answers with the help reply.
confirm marks a double opt-in reply, such as JOIN or YES. It sends nothing today, so answer it from your own handler. Bird holds those keywords so a custom rule cannot claim them.

Changing the reply

Bird's default replies are correct but generic. To answer in your own name, create a rule for that country and operation:

Exemplo de código

bird sms keyword-rules create \
  --operation stop \
  --country NL \
  --reply "You are unsubscribed from MyBrand. Reply START to resume."

Your rule replaces Bird's default reply for that country and keeps Bird's keywords unless you add more. It also inherits keywords Bird adds later. You cannot change the operation assigned to an opt-out or opt-in keyword; Bird rejects a rule that tries to bind STOP to another operation.

Where Bird ships a country's keywords in more than one language, each language has its own rule, so a create must name the language it replaces. Canada is that country today: its stop, start, and help rules come in en and fr. language is required there and rejected for a country Bird stocks in a single language.

Exemplo de código

bird sms keyword-rules create \
  --operation stop \
  --country CA \
  --language fr \
  --reply "Vous etes desabonne de MyBrand. Repondez DEBUT pour reprendre."

Listing a country's rules shows whether the split applies and which languages are available.

To confine a rule to one number rather than every number you hold in the country, set number instead of relying on the country alone.

If you answer these messages from your own system rather than through Bird, set reply to null together with confirmed_self_managed. That switches Bird's auto-reply off for the rule while the suppression itself keeps working.

Campaign keywords

custom rules carry no built-in behavior. They match keywords you choose and send the reply you write, which supports campaign keywords such as PIZZA. A custom rule inherits no keywords, so it needs at least one of its own, and it may omit country to apply everywhere you send.

A keyword Bird has bound to a compliance operation cannot be reused as a custom one.

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 to honor an opt-out a customer gave you on the phone:

Exemplo de código

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.

Opting out of every sender

A stop keyword, and the manual suppressions above, both stop one sender. Some subscribers want out of every sender in the workspace at once, for example someone who tells your support team to stop all texts rather than reply to each number individually.

That's a stated preference rather than a suppression, so it lives on the Preferences tab of SMS > Suppressions, not in the list above. Open the tab and record an opt-out with Every sender in the workspace: the number stops receiving SMS from every sender in the workspace, including senders you add later. An opt-out recorded on this tab covers all messages, authentication texts included; to record one that stops only marketing, use the workspace-wide Contacts > Preferences page, whose dialog offers the coverage choice.

Bird checks the suppressions in this guide first, so a plain keyword stop still rejects with E12077 as before. A send to a number with a workspace-wide opt-out on file is rejected with E25000 PreferenceRevoked instead. To resume sending once the subscriber asks you to, remove the entry from the Preferences tab (you recorded it, so you can remove it), or record an opt-in on the workspace-wide Contacts > Preferences page.

Next steps

Sending SMS: review categories, senders, and rejection conditions.
Events: handle the sms.* events for sends and replies.
SMS log: inspect a message, including a rejected send.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Understand the conceptHow do I collect SMS opt-ins?Explore the capabilitySMS compliance Follow the learning pathOperate messaging reliably

Get an implementation brief