whatsapp-groups

Pin a message in a WhatsApp group

Pins one of the group's messages at the top of its chat, where it stays for the number of days you give, from 1 to 30. Pin the message a conversation keeps coming back to, so a participant joining later does not have to scroll for it.

The message has to be one this group carries: a message in another group, or a one-to-one message, returns a 422 WhatsAppMessageNotInGroup. A message_id naming no message the workspace still holds returns a 404 instead, which is also what an id older than the 30 days messages stay readable for gets. Only an active group can be changed; any other status returns a 409 WhatsAppGroupNotActive.

A group holds 3 pinned messages at once, and pinning a fourth unpins the oldest rather than failing. Pinning an already-pinned message replaces its expiry. What the group currently pins is on the group itself, as pinned_messages.

WhatsApp confirms a pin in its reply rather than on a webhook, so the response is the applied pin and the entry appears in the group's pinned_messages straight away. Nothing about a pin is left in flight, so a pin never blocks the next pin or unpin.

post/v1/whatsapp/groups/{group_id}/pinned-messages

Request

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

Path parameters

group_idstring required
Example:wag_01krdgeqcxet5s7t44vh8rt9mg

ID of the group to pin a message in.

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

message_idstring required
duration_daysinteger

How many days the message stays pinned before WhatsApp unpins it, from 1 to 30.

Example request

{
  "message_id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
  "duration_days": 7
}

Response

The applied pin: the message and when its pin expires.

message_idstring required
pinned_untilstring date-time required

When the pin is due to lapse, projected from the duration_days the pin was asked for. An entry stays listed until it is unpinned, so a time in the past means WhatsApp has already taken the message off the chat.

Example response

{
  "message_id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
  "pinned_until": "2026-09-01T09:14:52Z"
}

Changes

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