---
title: "Pin a message in a WhatsApp group"
method: POST
path: "/v1/whatsapp/groups/{group_id}/pinned-messages"
tags: ["whatsapp-groups"]
---

# Pin a message in a WhatsApp group

`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`

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.

## Path parameters

- `group_id` string, required

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- WhatsAppGroupPinnedMessageCreate: A message to pin at the top of the group's chat.
  - `message_id` string, required
  - `duration_days` integer: How many days the message stays pinned before WhatsApp unpins it, from 1 to 30.

## Response `200`

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

- WhatsAppGroupPinnedMessage: A message pinned at the top of a group's chat.
  - `message_id` string, required
  - `pinned_until` string, 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.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)