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.

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:

Codebeispiel

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 you can create stop, start, and help rules 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.

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:

Codebeispiel

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.

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:

Codebeispiel

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: review categories, senders, and rejection conditions.
Events: handle the sms.* events for sends and replies.
SMS log: inspect a message, including a rejected send.