List SMS keyword rules
GET
/v1/sms/keyword-rules
const rules = await bird.smsKeywordRules.list({ country: "NL" });
for (const rule of rules.data) {
console.log(rule.operation, rule.keywords);
}rules = client.sms_keyword_rules.list(country="NL")
for rule in rules.data:
print(rule.operation, rule.keywords)rules, err := client.SmsKeywordRules.List(context.Background(), bird.SmsKeywordRulesListParams{
Country: "NL", // omit for every country Bird's catalogue covers, plus your own rules
})
if err != nil {
log.Fatal(err)
}
for _, rule := range rules.Data {
fmt.Println(rule.Operation, rule.Keywords)
}$rules = $bird->smsKeywordRules->list(['country' => 'NL']);
foreach ($rules->getData() ?? [] as $rule) {
echo $rule->getOperation(), ' ', implode(',', $rule->getKeywords() ?? []), PHP_EOL;
}bird sms keyword-rules listcurl -X GET "https://us1.platform.bird.com/v1/sms/keyword-rules" \
-H "Authorization: Bearer $TOKEN"Response200
{
"data": [
{
"id": "skw_01krdgeqcxet5s7t44vh8rt9mg",
"scope": "system",
"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"
}
]
}
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.
Query Parameters
country
string
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.
number
string
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.
from_country
string
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.
operation
string
Keep only rules for this operation. Omit for all of them.
Possible values (may grow over time): stop, start, help, custom
scope
string
Keep only default rules (system) or only the rules you created (workspace). Omit for both.
Possible values: system, workspace
Response Payload
data
array of object
required
The keyword rules that apply to your workspace, Bird's defaults included. Ordered most specific first, so the first rule whose keywords match an inbound message is the one that runs. The set is small and returned in full; this list is not paginated.
Show child attributes
data.id
string
required
Identifier of a keyword rule. An sks_ id is one of Bird's defaults, which you can read but not change; an skw_ id is a rule your workspace created.
data.scope
string
required
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.
Possible values: system, workspace
data.operation
string
required
Action taken when an inbound message matches the rule. stop unsubscribes the sender, start resubscribes them, help sends your support information, and custom sends the reply you configured. Built-in compliance rules fix the operation for stop, start, and help. This is an open enum. Accept unrecognized values.
Possible values (may grow over time): stop, start, help, custom
data.country
nullable string
The country the rule applies in, as an ISO 3166-1 alpha-2 code. A rule for NL covers messages received on your Dutch numbers, and messages from a subscriber whose own number is Dutch whichever of your numbers they text. Rules for the country a message arrives in always outrank rules for the country its sender is in; within each, your rule wins over Bird's keywords for that country. number confines a rule to one number. Null means the rule applies worldwide, which is allowed for custom operations only.
data.language
nullable string
The language this rule covers, in countries where Bird ships keywords in more than one. Canada has separate English and French rules, so a Canadian rule names which one it replaces and the other keeps Bird's reply. Null in countries with a single set.
data.number
nullable string
Narrows the rule to one of your numbers in E.164 format, instead of every number you hold in the country. Null means it applies to all of them.
data.keywords
array of string
required
The keywords this rule adds. For one of Bird's defaults this is the full set Bird ships. For a rule you created it is only what you added on top. It never restates or removes Bird's keywords, so effective_keywords is what actually matches.
data.effective_keywords
array of string
required
Every keyword that matches this rule: Bird's keywords for the same operation, country and language, plus the ones you added. This is what an inbound message is compared against. Keywords Bird adds later join it without you changing anything.
data.reply
nullable string
The message sent back when one of the keywords matches, except on a confirm rule, which never sends one. Null when the auto-reply is switched off, which reply_disabled_at distinguishes from a rule that has not been given one.
data.reply_suffix
nullable string
Text appended to your reply that you cannot change: the rates and opt-out wording carriers require on a help response. Your reply is sent in front of it, and both count against the length a single message allows. Null when the operation carries none.
data.reply_disabled_at
nullable string
When the auto-reply for this rule was switched off, or null if it is on. Switching it off records that you send this reply from your own system, which is what Bird points to if a carrier asks why no reply went out.
data.mandatory
boolean
required
Whether what this operation does is fixed. When true you can change the reply but not the behavior. An opt-out keyword always unsubscribes the sender, whichever rule matched it, because carriers and regulators require it.
data.created_at
string
required
When the rule was created.
data.updated_at
string
required
When the rule was last changed. On one of Bird's defaults this is when Bird last changed the keywords or the reply for that country.