Skip to main content
POST
/
api
/
chat
/
pinMessage
/
:instance
Pin message
curl --request POST \
  --url https://api.example.com/api/chat/pinMessage/:instance \
  --header 'Content-Type: application/json' \
  --data '
{
  "pin": true,
  "messageId": "<string>",
  "duration": "<string>"
}
'
Auth: TokenAccount or TokenInstance • Rate-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. 
curl -X POST "https://ryzeapi.cloud/api/chat/pinMessage/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "pin":       true,
    "messageId": "3EB0XXXXXXXXXXXXXXXX",
    "duration":  "7d"
  }'

​
Unpin

With pin: false, the message is unpinned. The duration field is ignored.
cURL
curl -X POST "https://ryzeapi.cloud/api/chat/pinMessage/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "pin":       false,
    "messageId": "3EB0XXXXXXXXXXXXXXXX"
  }'

​
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
{
  "success": true,
  "message": "Message pinned successfully",
  "chat_jid": "5511999999999@s.whatsapp.net",
  "message_id": "3EB0XXXXXXXXXXXXXXXX",
  "pinned": true,
  "duration": "7d"
}

​
Path parameters

​
instance
string
required
Instance name.

​
Headers

NameRequiredExampleDescription
Content-Typeyesapplication/json,
tokenyes (or Authorization)a1b2c3d4-...TokenAccount or TokenInstance.

​
Request body

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

​
Error responses

HTTPerror.messageWhen it happens
400Instance name is required,
400Invalid request body: <...>Malformed JSON.
400messageId is required,
401Invalid token,
404Instance not found,
500message with ID <...> not foundMessage does not exist in the instance database.
500invalid duration "<...>": use "24h", "7d" or "30d"Invalid duration value.
500WhatsApp client is not connectedInstance disconnected.
Error 400
{
  "success": false,
  "error": { "message": "messageId is required" }
}

Pin chat

POST /api/chat/pinChat/:instance

Favorite

POST /api/chat/favorite/:instance