GET /api/chats — List Recent WhatsApp Chats by Activity

GET /api/chats fetches all WhatsApp conversations available to the authenticated account and returns the most recent ones sorted by activity. Each chat entry includes display name, group/read-only flags, unread message count, pin and mute status, and a summary of the last message. This is useful for building an inbox view or for discovering the chat IDs you need to pass to /api/messages.

Endpoint

GET /api/chats?limit=20

Query Parameters

limit

integer

default:"20"

Maximum number of chats to return. Must be an integer between 1 and 100. Chats are sorted by timestamp (most recent first) before the limit is applied, so you always receive the freshest conversations.

Response Fields

boolean

required

true on a successful response.

count

integer

required

The number of chat objects returned in the chats array. This may be less than limit if the account has fewer chats than requested.

chats

array

required

An array of chat summary objects, sorted by most recent activity first.

Show Chat object fields

string | null

The serialized WhatsApp chat ID (e.g. "15551234567@c.us" for direct chats or "12345678901-1234567890@g.us" for groups).

name

string | null

The display name of the chat (contact name or group title). null if unavailable.

is_group

boolean

true if this is a group chat.

is_read_only

boolean

true if you cannot send messages to this chat (e.g. broadcast lists, announcement groups).

unread_count

integer

Number of unread messages in this chat. 0 if all messages have been read.

timestamp

integer | null

Unix timestamp (seconds) of the most recent message in the chat. null if no messages exist.

archived

boolean

true if the chat has been archived.

pinned

boolean

true if the chat is pinned to the top of the inbox.

muted

boolean

true if notifications for this chat have been muted.

last_message

object | null

A summary of the most recent message in the chat, using the same shape as messages returned by /api/messages. null if the chat has no messages.

Show last_message fields

string | null

Serialized message ID.

from

string | null

Sender’s WhatsApp ID.

string | null

Recipient’s WhatsApp ID.

author

string | null

Author ID in group chats.

from_me

boolean

true if the message was sent by the authenticated account.

type

string | null

Message type (e.g. "chat", "image", "audio").

body

string

Text content of the message. Empty string for media-only messages.

timestamp

integer | null

Unix timestamp of the message.

has_media

boolean

true if the message contains an attachment.

Example Request

curl "http://127.0.0.1:8790/api/chats?limit=2"

Example Response

{
  "ok": true,
  "count": 2,
  "chats": [
    {
      "id": "15551234567@c.us",
      "name": "Alice",
      "is_group": false,
      "is_read_only": false,
      "unread_count": 3,
      "timestamp": 1717250585,
      "archived": false,
      "pinned": true,
      "muted": false,
      "last_message": {
        "id": "true_15551234567@c.us_3EB0C767D97B2C123456",
        "from": "15551234567@c.us",
        "to": "me@c.us",
        "author": null,
        "from_me": false,
        "type": "chat",
        "body": "Are you free tomorrow?",
        "timestamp": 1717250585,
        "has_media": false
      }
    },
    {
      "id": "15559876543-1609459200@g.us",
      "name": "Team Standup",
      "is_group": true,
      "is_read_only": false,
      "unread_count": 0,
      "timestamp": 1717248000,
      "archived": false,
      "pinned": false,
      "muted": true,
      "last_message": {
        "id": "true_15559876543-1609459200@g.us_ABCDEF1234567890",
        "from": "15557654321@c.us",
        "to": "15559876543-1609459200@g.us",
        "author": "15557654321@c.us",
        "from_me": false,
        "type": "chat",
        "body": "Daily sync at 9am!",
        "timestamp": 1717248000,
        "has_media": false
      }
    }
  ]
}

REST API

MCP Endpoint

GET /api/chats — List Recent WhatsApp Chats by Activity

Endpoint

Query Parameters

Response Fields

Example Request

Example Response

Build docs developers (and LLMs) love

REST API

MCP Endpoint

Documentation Index

​Endpoint

​Query Parameters

​Response Fields

​Example Request

​Example Response

Build docs developers (and LLMs) love

Endpoint

Query Parameters

Response Fields

Example Request

Example Response