whatsapp-keyword-rules

List WhatsApp keyword rules

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.

get/v1/whatsapp/keyword-rules

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/whatsapp/keyword-rules
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Query parameters

countrystring
Example:US

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.

wabastring
Example:102290129340398

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.

operationstring

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.

Example:opt_out

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.

scope'system' | 'workspace'

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.

Example:workspace

Keep only Bird's own rules (system) or only the rules you created (workspace). Omit for both.

Headers

X-Workspace-Idstring

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.

X-Organization-Idstring

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": "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"
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.