whatsapp-keyword-rules

Update a WhatsApp keyword rule

Changes the reply or the added keywords of a rule you created. Bird's own rules cannot be changed. To replace one, create a rule with the same operation and country and yours takes precedence.

What the rule applies to is fixed once created, so this changes the reply and the keywords only.

patch/v1/whatsapp/keyword-rules/{id}

Request

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

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.

Request body

keywordsstring[]

Replaces the extra keywords this rule matches, on top of the ones Bird ships. Send an empty array to keep Bird's keywords only. Omit to leave the current ones unchanged.

replystring nullable

Replaces the message sent back when a keyword matches. Set it to null to send nothing. Omit to leave it unchanged.

Example request

{
  "keywords": [
    "no more texts"
  ],
  "reply": "You're off the list. ACME Courier won't message you again."
}

Response

The updated rule.

idstring required
scope'system' | 'workspace' required

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.

operationstring required

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.

countrystring nullable

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.

wabastring nullable

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.

keywordsstring[] required

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.

effective_keywordsstring[] required

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.

replystring nullable

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.

created_atstring date-time required

When the rule was created. On one of Bird's own rules this is when Bird last shipped a change to it.

updated_atstring date-time required

When the rule was last changed. On one of Bird's own rules this is when Bird last shipped a change to it.

Example response

{
  "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.