Skip to Content
Wazend

Chats

Manage WhatsApp chats with Wazend: list, archive, delete, mark as read, pin messages and more.

Methods to manage WhatsApp chats and messages.

  • {session} — your session name (shown in the Dashboard, for example S0001).
  • {chatId} — chat ID in the format 123123123123@c.us (direct) or 123123123123@g.us (group).

Get all chats

GET /api/{session}/chats

Query parameters:

GET /api/{session}/chats?limit=100&offset=0&sortBy=messageTimestamp&sortOrder=desc
  • limit=100 — limits the number of chats to return.
  • offset=0 — skips N chats from the start.
  • sortBy — sort by field: messageTimestamp (last message), id or name.
  • sortOrder — desc (newest first) or asc(oldest first).

Tip

If you see timeout or the request takes too long, use limit to fetch the objects in smaller chunks.

Get chats overview

The API almost every chat UI client needs.

GET /api/{session}/chats/overview?limit=20&offset=0
  • limit / offset — pagination.
  • ids=11111&ids=9999@c.us — filter by ID or phone number.

Use POST if you have many chats (>400) in the idsfilter:

POST /api/{session}/chats/overview
Body
{
  "pagination": { "limit": 20, "offset": 0 },
  "filter": { "ids": ["5215551234567@c.us"] }
}
Response
[
  {
    "id": "5215551234567@c.us",
    "name": "Juan Pérez",
    "picture": "https://ejemplo.com/foto.jpg",
    "lastMessage": {
      "id": "true_5215551234567@c.us_AAAA",
      "timestamp": 1667561485,
      "from": "5215551234567@c.us",
      "fromMe": true,
      "body": "Hello"
    }
  }
]

Get chat picture

GET /api/{session}/chats/{chatId}/picture?refresh=true
Response
{ "url": "https://ejemplo.com/foto.jpg" }

url can be null if the chat has no picture. refresh=true forces a refresh (cached for 24 h).

Archive / unarchive chat

POST /api/{session}/chats/{chatId}/archive
POST /api/{session}/chats/{chatId}/unarchive

Mark chat as unread

POST /api/{session}/chats/{chatId}/unread

Delete chat

DELETE /api/{session}/chats/{chatId}

Mark messages as read

Mark all unread messages in the chat as read (double blue check).

POST /api/{session}/chats/{chatId}/messages/read
Body
{ "messages": 30, "days": 7 }
Body
{
  "ids": [
    "false_5215551234567@c.us_AAAA",
    "true_5215551234567@c.us_BBBB"
  ]
}
  • messages — how many messages to read (default 30 in direct chats, 100 in groups).
  • days — how many days to read (default 7).

Get messages

GET /api/{session}/chats/{chatId}/messages?limit=10

Available parameters:

  • downloadMedia=true — download media files.
  • limit / offset pagination.
  • filter.timestamp.gte / filter.timestamp.lte — filter by timestamp.
  • filter.fromMe=false — exclude your own messages.
  • filter.ack — filter by acknowledgment status: ERROR (-1), PENDING (0), SERVER (1), DEVICE (2), READ (3), PLAYED (4).
Response
[
  {
    "id": "false_5215551234567@c.us_AAAAAA",
    "timestamp": 1727745026,
    "from": "5215551234567@c.us",
    "fromMe": false,
    "body": "Hello!",
    "hasMedia": false,
    "ack": 3,
    "ackName": "READ",
    "replyTo": null
  }
]

Get message by id

GET /api/{session}/chats/{chatId}/messages/{messageId}?downloadMedia=true

Pin / unpin message

POST /api/{session}/chats/{chatId}/messages/{messageId}/pin
Body
{
  "duration": 86400
}

Duration: 24 hours = 86400, 7 days = 604800, 30 days = 2592000.

POST /api/{session}/chats/{chatId}/messages/{messageId}/unpin

Edit message

PUT /api/{session}/chats/{chatId}/messages/{messageId}
Body
{ "text": "Edited message" }

Info

Remember to escape @ with %40 in chatId and messageId.

Delete message

DELETE /api/{session}/chats/{chatId}/messages/{messageId}

Delete all messages

DELETE /api/{session}/chats/{chatId}/messages

Events

Receive chat events through Events. The chat.archive event fires when a chat is archived or unarchived (see the payload details on the Events page).