Pin chat

POST

api

chat

pinChat

:instance

Pin chat

curl --request POST \
  --url https://api.example.com/api/chat/pinChat/:instance \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "<string>",
  "pin": true
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({number: '<string>', pin: true})
};

fetch('https://api.example.com/api/chat/pinChat/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/chat/pinChat/:instance"

payload = {
    "number": "<string>",
    "pin": True
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: yes

Description

Marks a chat as pinned (pin: true) or removes the pin (pin: false).

WhatsApp limits to 3 pinned chats simultaneously. Trying to pin a fourth returns a WhatsMeow error propagated to the response.

Examples

With pin: true, the chat moves to the top of the list. Remember WhatsApp allows at most 3 pinned chats at the same time, trying a fourth returns an error.

curl -X POST "https://ryzeapi.cloud/api/chat/pinChat/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "pin":    true
  }'

await fetch(`https://ryzeapi.cloud/api/chat/pinChat/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    pin:    true
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/pinChat/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "pin":    True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "pin":    true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/pinChat/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Unpin

With pin: false, removes the pin and the chat returns to normal sorting by activity. Frees a slot in the limit of 3 pinned chats.

curl -X POST "https://ryzeapi.cloud/api/chat/pinChat/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "pin":    false
  }'

await fetch(`https://ryzeapi.cloud/api/chat/pinChat/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    pin:    false
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/pinChat/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "pin":    False
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "pin":    false
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/pinChat/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Success response

The response confirms the operation with chat_jid (JID resolved from number) and pinned reflecting the final state. The message changes depending on the value of pin: "Chat pinned successfully" or "Chat unpinned successfully".

200 OK

{
  "success": true,
  "message": "Chat pinned successfully",
  "chat_jid": "5511999999999@s.whatsapp.net",
  "pinned": true
}

Path parameters

string

required

Instance name.

Headers

Name	Required	Example	Description
`Content-Type`	yes	`application/json`	,
`token`	yes (or `Authorization`)	`a1b2c3d4-...`	TokenAccount or TokenInstance.

Request body

string

required

Phone number, private JID (...@s.whatsapp.net or ...@lid), group JID (...@g.us), or newsletter.

boolean

required

true pins, false unpins.

Error responses

HTTP	`error.message`	When it happens
400	`Instance name is required`	,
400	`Invalid request body: <...>`	Malformed JSON.
400	`Number is required`	,
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	,

Error 400

{
  "success": false,
  "error": { "message": "Number is required" }
}

Archive chat

POST /api/chat/archive/:instance

Favorite

POST /api/chat/favorite/:instance

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Pin

Unpin

Success response

Path parameters

Headers

Request body

Error responses

Archive chat

Favorite

​Description

​Examples

​Pin

​Unpin

​Success response

​Path parameters

​Headers

​Request body

​Error responses

​Related

Archive chat

Favorite

Description

Examples

Pin

Unpin

Success response

Path parameters

Headers

Request body

Error responses

Related