Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

List WhatsApp keyword rules

GET
/v1/whatsapp/keyword-rules
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}
Risposta200
{
  "data": [
    {
      "id": "wkr_01krdgeqcxet5s7t44vh8rt9mg",
      "scope": "workspace",
      "operation": "opt_out",
      "country": "US",
      "waba": "102290129340398",
      "keywords": [
        "no more texts",
        "remove me"
      ],
      "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"
    }
  ]
}
Returns the keyword rules that apply to inbound messages, most specific first. Bird's own rules are included, so opt-out and opt-in work on every inbound-capable number before you configure anything.
Use the filters to narrow the full, unpaginated list. Set scope=system for Bird's rules only, or scope=workspace for the ones you created.
Parametri di query
country
string
Keep only rules that apply to someone messaging from this country, as an ISO 3166-1 alpha-2 code. Omit for every rule, whichever country it covers.
waba
string
Keep only the rules that apply to this WhatsApp Business Account of yours, identified by its WhatsApp-issued account ID or by the waa_ ID Bird gives it. Either form finds the same rules.
operation
string
Keep only rules for this operation. Omit for all of them. Open on the same terms as the response, so an operation Bird gains later can be filtered for without a client update; one Bird does not answer matches nothing rather than failing.
Possible values (may grow over time): opt_in, opt_out
scope
string
Keep only Bird's own rules (system) or only the rules you created (workspace). Omit for both.
Possible values: system, workspace
Payload di risposta
data
array of object
obbligatorio
The keyword rules that apply to your workspace, Bird's own 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.
Mostra attributi secondari
data.id
string
obbligatorio
data.scope
string
obbligatorio
Whether 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
data.operation
string
obbligatorio
What Bird does when an inbound message matches the rule.
  • opt_out records 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_in records 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
data.country
nullable string
The 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.
data.waba
nullable string
The 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.
data.keywords
array of string
obbligatorio
The 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 or removes Bird's keywords, so effective_keywords is what actually matches.
data.effective_keywords
array of string
obbligatorio
Every keyword that matches this rule: Bird's keywords for the same operation and country, 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 a sender in a country Bird ships a rule for is answered by that rule and your reply is not used. 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.
data.reply
nullable string
The 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.
data.created_at
string
obbligatorio
When the rule was created. On one of Bird's own rules this is when Bird last shipped a change to it.
data.updated_at
string
obbligatorio
When the rule was last changed. On one of Bird's own rules this is when Bird last shipped a change to it.

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Ottieni un brief di implementazione