Create a WhatsApp keyword rule
/v1/whatsapp/keyword-rulesconst rule = await bird.whatsapp.keywordRules.create({
operation: "opt_out",
country: "US", // the SENDER's country, from their own number
reply: "You're off the list. ACME Courier won't message you again.",
});
// effective_keywords is Bird's set plus any of your own.
console.log(rule.id, rule.effective_keywords);rule = client.whatsapp.keyword_rules.create(
operation="opt_out",
country="US", # the SENDER's country, from their own number
reply="You're off the list. ACME Courier won't message you again.",
)
# effective_keywords is Bird's set plus any of your own.
print(rule.id, rule.effective_keywords)rule, err := client.Whatsapp.KeywordRules.Create(context.Background(), bird.WhatsappKeywordRulesCreateParams{
Operation: "opt_out",
Country: bird.String("US"), // the SENDER's country, from their own number
Reply: bird.String("You're off the list. ACME Courier won't message you again."),
})
if err != nil {
log.Fatal(err)
}
// EffectiveKeywords is Bird's set plus any of your own.
fmt.Println(rule.Id, rule.EffectiveKeywords)$rule = $bird->whatsapp->keywordRules->create(
(new WhatsAppKeywordRuleCreate())
->setOperation('opt_out')
->setCountry('US')
->setReply("You're off the list. ACME Courier won't message you again."),
);
// getEffectiveKeywords() is Bird's set plus any of your own.
echo $rule->getId(), ' ', implode(',', $rule->getEffectiveKeywords() ?? []);bird whatsapp keyword-rules create \
--country US \
--keywords 'no more texts' \
--keywords 'remove me' \
--operation opt_out \
--reply "You're off the list. ACME Courier won't message you again." \
--waba 102290129340398curl -X POST "https://us1.platform.bird.com/v1/whatsapp/keyword-rules" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"operation": "opt_out",
"country": "US",
"waba": "102290129340398",
"keywords": [
"no more texts",
"remove me"
],
"reply": "You'\''re off the list. ACME Courier won'\''t message you again."
}'{
"id": "wkr_01krdgeqcxet5s7t44vh8rt9mg",
"scope": "workspace",
"operation": "opt_out",
"country": "US",
"waba": "102290129340398",
"keywords": [
"no more texts",
"remove me"
],
"excluded_keywords": [],
"effective_keywords": [
"stop",
"unsubscribe",
"optout",
"no more texts",
"remove me"
],
"reply": "You're off the list. ACME Courier won't message you again.",
"created_at": "2026-09-15T10:04:00Z",
"updated_at": "2026-09-15T10:04:00Z"
}
Creates a keyword rule. Use it to replace the reply Bird sends for opt_out or opt_in, or to add keywords your customers actually type.
Your rule takes precedence over Bird's at the same grain and keeps Bird's keywords, so replacing a reply takes two fields. Set excluded_keywords to remove some of Bird's for the people the rule covers: when this rule is the first to match, a message that is exactly one of them opts no one in or out and gets no reply. A keyword Bird has bound to one operation cannot be reused for the other.
Request Payload
operationWhat Bird does when an inbound message matches the rule.
opt_outrecords that the sender no longer consents to receive any messages from your WhatsApp Business Account, including transactional ones. Typing the word is the person's own statement, so it covers everything, unlike WhatsApp's built-in marketing opt-out control, which stops marketing alone.opt_inrecords that they consent again.
A rule's operation is fixed once created, and a keyword belongs to exactly one operation, so
a keyword Bird ships for opt_out cannot be reused for opt_in.
Closed on the write side: an operation Bird does not answer is rejected here rather than stored as a rule that never fires. The read side is open, because Bird can gain an operation without a new API version.
Possible values: opt_in, opt_out
countryThe country this rule applies in, as an ISO 3166-1 alpha-2 code. It matches the country of the person who messaged you, worked out from their phone number. Omit it to cover everyone, which is what Bird's own rules do.
wabaLimit the rule to one WhatsApp Business Account, identified by its WhatsApp-issued account ID or by the waa_ ID Bird gives it. Either form resolves to the same account, and the rule stores and returns the WhatsApp-issued one. Omit it to cover every account in your workspace. The account must be one of yours.
keywordsExtra keywords to match, on top of the ones Bird already ships for this operation. Omit to keep Bird's keywords and change only the reply, including keywords Bird adds later. Use excluded_keywords to remove one of Bird's. A keyword Bird has bound to the other operation cannot be reused here.
excluded_keywordsBird's keywords to remove for the people this rule covers. Rules are tried most specific first: a more specific rule of yours answers before this one, and with neither country nor waba so does Bird's rule for the sender's country. When this rule answers a message that is exactly an excluded keyword, no one is opted in or out, no reply is sent, and no less specific rule acts on it, so you must honour opt-outs it carries yourself. Without a country, the rule inherits Bird's keywords for each sender's country, so an exclusion covers only senders whose set has that keyword. Exclude every one of Bird's keywords to switch them off where this rule answers; a keyword Bird adds later still matches unless it is already excluded. It changes none of your other rules. A keyword cannot be both added and excluded.
replyThe message to send back when a keyword matches. Omit it to send nothing.
Response Payload
idscopeWhether the rule is one Bird ships (system) or one your workspace created (workspace). Both kinds carry a wkr_ ID and can be read; only a workspace rule can be changed or deleted. A workspace rule takes precedence over Bird's at the same grain, so it is how you replace a reply without losing the keywords Bird ships.
Possible values: system, workspace
operationWhat Bird does when an inbound message matches the rule.
opt_outrecords that the sender no longer consents to receive any messages from your WhatsApp Business Account, including transactional ones. Typing the word is the person's own statement, so it covers everything, unlike WhatsApp's built-in marketing opt-out control, which stops marketing alone.opt_inrecords that they consent again.
A rule's operation is fixed once created, and a keyword belongs to exactly one operation, so
a keyword Bird ships for opt_out cannot be reused for opt_in.
This is an open enum. Accept unrecognized values: SMS already answers help, info, confirm
and custom, and WhatsApp gains an operation without a new API version. Sending one Bird does
not answer yet is refused with E15082.
Possible values (may grow over time): opt_in, opt_out
countryThe country the rule applies in, as an ISO 3166-1 alpha-2 code. It is the country of the person who messaged you, worked out from their phone number, not the country of the account they messaged. Null means the rule applies worldwide, which is what Bird's own rules do. A rule for a country outranks a worldwide rule for the people it covers.
wabaThe WhatsApp Business Account the rule is limited to, identified by its WhatsApp-issued account ID, or null when it covers every account in your workspace. Bird's own rules are always null.
keywordsThe keywords this rule adds. For one of Bird's own rules this is the full set Bird ships. For a rule you created it is only what you added on top: it never restates Bird's keywords, so effective_keywords is what actually matches.
excluded_keywordsBird's keywords this rule removes from the set it inherits. Rules are tried most specific first, and a rule of yours with neither country nor waba comes after Bird's rule for the sender's country, as effective_keywords explains. When this rule answers a message that is exactly an excluded keyword, no one is opted in or out, no reply is sent, and no later rule acts on it, whether Bird's or another of yours that matches the same keyword. A more specific rule that answers first is unaffected. A rule with no country inherits Bird's keywords for each sender's country, so its exclusions apply only to senders whose set has the keyword. Excluding every one of Bird's keywords switches them off where this rule answers, though a keyword Bird adds later still matches unless it is already excluded. It changes no other rule's keywords. Always empty on one of Bird's own rules.
effective_keywordsEvery keyword that matches this rule: Bird's keywords for the same operation and country, minus excluded_keywords, plus the ones you added. This is what an inbound message is compared against, and the whole message has to equal one of them. Keywords Bird adds later join it without you changing anything.
For a rule of yours with no country, this list is not the whole set it matches: such a rule compares against Bird's keywords for the sender's country, which the list cannot show because it does not know who is writing, so it shows Bird's worldwide keywords instead. Which rule answers decides whether that matters. Yours with no country and no waba sits below Bird's own country rule, so when a sender in a country Bird ships a rule for writes one of Bird's keywords, that rule answers and your reply is not used. A keyword you added reaches your rule only when no earlier rule matches it, and for a given sender the matched set can differ from this list in either direction. Yours with a waba and no country sits above it, so those senders match that country's keywords and get your reply, which is more keywords than this list names. Set a country on your own rule to see and extend exactly the set those senders match. A system rule is unaffected: each matches only its own keywords, and the ladder checks Bird's country rules separately from its worldwide one.
replyThe message sent back when one of the keywords matches, or null when no reply is sent. The reply goes out on the conversation the inbound message opened.
created_atWhen the rule was created. On one of Bird's own rules this is when Bird last shipped a change to it.
updated_atWhen the rule was last changed. On one of Bird's own rules this is when Bird last shipped a change to it.
Related resources
Continue with the documentation, guides and examples for this topic.