Pin & unpin messages

Use Pin a Message to pin or unpin an existing message in a WhatsApp chat. Retrieve chat_id and message_id using List all Chats and List all Chat Messages.

const response = await fetch(
  "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin",
  {
    method: "POST",
    headers: {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pin_status: true,
    }),
  },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.post(
    "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    json={
        "pin_status": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()

curl --request POST \
  --url "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin" \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "pin_status": true
}'

Send the same request with pin_status: false to unpin the message. You can target another participant's message; group permissions may restrict the action.

Choose a pin duration

WhatsApp accepts specifics.pin_duration: 24_hours, 7_days, or 30_days (the default). For example, send {"pin_status": true, "specifics": {"pin_duration": "7_days"}}. WhatsApp automatically unpins the message when this duration expires.

const response = await fetch(
  "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin",
  {
    method: "POST",
    headers: {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pin_status: true,
      specifics: {
        pin_duration: "7_days",
      },
    }),
  },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.post(
    "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    json={
        "pin_status": True,
        "specifics": {
            "pin_duration": '7_days'
        }
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()

curl --request POST \
  --url "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin" \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "pin_status": true,
  "specifics": {
    "pin_duration": "7_days"
  }
}'

Unpin a message and read pin state

The unified message includes is_pinned. There is no dedicated pin or unpin webhook type; do not subscribe to an invented message.pin event. Method availability and realtime event availability are separate: consult Methods & Events availability.

const response = await fetch(
  "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin",
  {
    method: "POST",
    headers: {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pin_status: false,
    }),
  },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.post(
    "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    json={
        "pin_status": False
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()

curl --request POST \
  --url "https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/pin" \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "pin_status": false
}'