# Pin a message in a WhatsApp group

`POST /v1/whatsapp/groups/{group_id}/pinned-messages`

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.

## Code samples

**TypeScript**

```ts
const pin = await bird.whatsapp.groups.pins.create("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  message_id: "wam_01kya19eknftrs2s6p82asmvnh",
});
console.log(pin.pinned_until);
```

Examples: [TypeScript](/docs/api/reference/create-whatsapp-group-pinned-message.ts.md) · [Python](/docs/api/reference/create-whatsapp-group-pinned-message.py.md) · [Go](/docs/api/reference/create-whatsapp-group-pinned-message.go.md) · [PHP](/docs/api/reference/create-whatsapp-group-pinned-message.php.md) · [CLI](/docs/api/reference/create-whatsapp-group-pinned-message.cli.md) · [MCP](/docs/api/reference/create-whatsapp-group-pinned-message.mcp.md) · [cURL](/docs/api/reference/create-whatsapp-group-pinned-message.curl.md)

## Example response `200`

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

## Path parameters

- `group_id` (string): ID of the group to pin a message in.

## Request body

- `message_id` (string, required): The message to pin. It has to be one this group carries: a message in another group, or a one-to-one message, returns a `422` `WhatsAppMessageNotInGroup`.
- `duration_days` (integer): How many days the message stays pinned before WhatsApp unpins it, from 1 to 30.

## Response body

- `message_id` (string, required): The pinned message, as returned in the send response's `id`.
- `pinned_until` (string, 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.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)