List SMS keyword rules
Returns the default and workspace keyword rules that apply to inbound messages, most specific first. Where the default catalog covers a country, opt-out, opt-in, and help keywords work without setup.
Use the filters to narrow the full, unpaginated list. Set scope=system for default rules only. Set number for rules in evaluation order, and add from_country to account for the sender's country.
Default coverage varies by country. If a country has no default rules, the service does not recognize keywords, send replies, or record opt-outs there. You can add custom keywords for that country. Opt-out, opt-in, and help rules require default coverage.
Request
- Base URL: https://us1.platform.bird.com
- URL: https://us1.platform.bird.com/v1/sms/keyword-rules
- Auth: one of:
- HTTP bearer
- API key in cookie bird_session
Query parameters
Keep only rules that apply in this country, as an ISO 3166-1 alpha-2 code. Omit for every country the default catalog covers, plus your own rules.
Keep only the rules that apply to this number of yours, in E.164 format or as a short code, ordered the way they are applied to an inbound message.
The country a sender is messaging from, as an ISO 3166-1 alpha-2 code. Use it with number to see what someone in that country gets, which can differ from what a local sender gets. Ignored without number.
What Bird does when an inbound message matches the rule.
- stop unsubscribes the sender from further messages.
- start resubscribes them.
- help replies with your support information.
- info replies with your program information. It behaves exactly as help does and 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. It sends nothing today, so answer it from your own handler.
- custom replies with the text you configured and has no other effect.
Bird's built-in rules fix the operation for stop, start and help; you can change their reply but not what they do. The same holds for info in any country where Bird ships an info rule. This is an open enum. Accept unrecognized values.
Keep only rules for this operation. Omit for all of them.
Whether the rule is one of Bird's defaults (system) or one your workspace created (workspace). A workspace rule takes precedence over Bird's default for the same country, so it is how you replace a reply without losing the keywords Bird ships.
Keep only default rules (system) or only the rules you created (workspace). Omit for both.
Headers
Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.
Response
The keyword rules that apply to your workspace.
Example response
{
"data": [
{
"id": "skw_01krdgeqcxet5s7t44vh8rt9mg",
"operation": "stop",
"country": "NL",
"language": "fr",
"number": "+18005551234",
"keywords": [
"pizza",
"menu"
],
"effective_keywords": [
"stop",
"stoppen",
"afmelden"
],
"reply": "You have been unsubscribed and will receive no further messages.",
"reply_suffix": "Msg&data rates may apply. Reply STOP to unsubscribe.",
"reply_disabled_at": "2026-08-12T09:00:00Z",
"mandatory": true,
"created_at": "2026-08-12T09:00:00Z",
"updated_at": "2026-08-12T09:00:00Z"
}
]
}Changes
No recorded changes to this operation across all 2 revisions of this API.