Skip to main content
POST
Pin message
Auth: TokenAccount or TokenInstanceRate-limit: Global (100/min) • Idempotent: yes

Description

Pins (pin: true) or unpins (pin: false) a message inside a chat. The chat, the message author and the direction (fromMe) are resolved automatically from messageId, you only need to provide the message.
Unlike favoriting (which is private and silent), pinning a message is an action visible to everyone in the conversation: WhatsApp shows “pinned a message”. The protocol only offers “pin for all”, there is no pin-for-me-only.
The message must exist in the instance database (it must have been received/sent by it). Otherwise the API returns message with ID ... not found.

Examples

Pin

With pin: true, the message is pinned to the top of the chat for the time set in duration.

Unpin

With pin: false, the message is unpinned. The duration field is ignored.
cURL

Success response

chat_jid is resolved from messageId, pinned reflects the final state and duration is echoed only when pinning. The message changes with pin: "Message pinned successfully" or "Message unpinned successfully".
200 OK

Path parameters

string
required
Instance name.

Headers

Request body

boolean
required
true pins, false unpins.
string
required
ID of the message to pin/unpin. The chat and author are resolved automatically from it.
string
default:"7d"
How long the message stays pinned: "24h", "7d" or "30d". Used only when pin: true; ignored when unpinning.

Error responses

Error 400

Pin chat

POST /api/chat/pinChat/:instance

Favorite

POST /api/chat/favorite/:instance