whatsapp-messages

React to a WhatsApp message

Places an emoji reaction on a message this workspace received, the same way tapping and holding a message in WhatsApp does.

You hold at most one reaction per message, so this replaces your existing one rather than adding another. To take a reaction back entirely, delete it.

The 202 means the reaction was accepted, not that WhatsApp applied it. Reactions carry no delivery or read receipt, so the furthest one gets is sent. Read the message's reactions for what currently stands, or List reaction events for a WhatsApp message for what became of each change, including one WhatsApp refused.

Each of these returns a 422:

  • A message this workspace sent. This endpoint places reactions on messages the contact sent; reacting to your own outbound message is not supported.
  • More than one emoji, since WhatsApp takes exactly one.

A message Bird can no longer resolve returns a 404 instead. WhatsApp accepts a reaction on a message up to 30 days old, but Bird keeps the provider id a reaction needs for 15 days, so that is the practical age limit. The message and its reaction log stay readable for 30; only the id a placement needs is gone.

Reacting to a message received in a group addresses the group, so the group's own state applies: a group this workspace no longer holds returns a 404 WhatsAppGroupNotFound, and one that is not active a 409 WhatsAppGroupNotActive.

Reactions are not charged for.

put/v1/whatsapp/messages/{message_id}/reaction

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/whatsapp/messages/{message_id}/reaction
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

message_idstring required
Example:wam_01krdgeqcxet5s7t44vh8rt9mg

ID of the message to react to, as returned in the id field of the message. Must be a message this workspace received.

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

emojistring required

The emoji to place, as the character itself. Replaces your existing reaction on this message if you have one. To take a reaction back entirely, delete it rather than sending an empty value. WhatsApp takes exactly one emoji, so a value carrying more than one is refused with a 422 rather than sent. The length cap is generous because a single joined emoji is many code points: a couple-kissing one carrying two skin tones is ten, which is why the cap alone cannot express the limit.

Example request

{
  "emoji": "👍"
}

Response

Reaction accepted; WhatsApp applies it asynchronously.

idstring required
emojistring required

The emoji as accepted, echoing the one the request carried.

Example response

{
  "id": "war_01krdgeqcxet5s7t44vh8rt9mg",
  "emoji": "👍"
}

Changes

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