List Chats

Retrieve a list of chats for a WhatsApp instance with optional filtering and pagination.

POST /chat/findChats/:instanceName

cURL

curl --request POST \
  --url https://api.example.com/chat/findChats/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "limit": 20,
    "offset": 0
  }'

const response = await fetch(
  'https://api.example.com/chat/findChats/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      limit: 20,
      offset: 0
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/chat/findChats/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'limit': 20,
        'offset': 0
    }
)

data = response.json()

200 Success

{
  "chats": [
    {
      "id": "chat_123",
      "remoteJid": "[e-mail]",
      "owner": "my-instance",
      "isGroup": false,
      "name": "John Doe",
      "createdAt": "2024-03-04T10:30:00.000Z",
      "updatedAt": "2024-03-04T12:45:00.000Z"
    },
    {
      "id": "chat_456",
      "remoteJid": "[e-mail]",
      "owner": "my-instance",
      "isGroup": true,
      "name": "Project Team",
      "createdAt": "2024-03-03T15:20:00.000Z",
      "updatedAt": "2024-03-04T11:30:00.000Z"
    }
  ],
  "total": 2
}

{
  "error": "Invalid query parameters",
  "message": "Limit must be a positive number"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Overview

You can fetch all chats from your WhatsApp instance using this endpoint. It supports advanced filtering through query parameters to help you find specific chats based on various criteria.

This endpoint returns both individual and group chats. Use the isGroup field in the response to distinguish between them.

Authentication

This endpoint requires authentication via the apikey header.

header.apikey · string · required

Your Evolution API key for authentication.

Path Parameters

path.instanceName · string · required

The name of your WhatsApp instance.

Request Body

The request body accepts a query object for filtering and pagination:

where · object

Filter criteria for chats.

Show properties

where.remoteJid · string

Filter by remote JID (WhatsApp ID).

where.owner · string

Filter by chat owner.

limit · number · default: "20"

Maximum number of chats to return.

offset · number · default: "0"

Number of chats to skip (for pagination).

sort · object

Sorting configuration.

Show properties

sort.field · string

Field name to sort by (e.g., “createdAt”).

sort.order · string

Sort order: “asc” or “desc”.

Response

chats · array

Array of chat objects.

Show properties

id · string

Unique chat identifier.

remoteJid · string

WhatsApp JID of the chat.

owner · string

Instance owner.

isGroup · boolean

Whether this is a group chat.

name · string

Chat display name.

createdAt · string

ISO 8601 timestamp of when the chat was created.

updatedAt · string

ISO 8601 timestamp of last update.

total · number

Total number of chats matching the query.

cURL

curl --request POST \
  --url https://api.example.com/chat/findChats/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "limit": 20,
    "offset": 0
  }'

const response = await fetch(
  'https://api.example.com/chat/findChats/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      limit: 20,
      offset: 0
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/chat/findChats/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'limit': 20,
        'offset': 0
    }
)

data = response.json()

200 Success

{
  "chats": [
    {
      "id": "chat_123",
      "remoteJid": "[e-mail]",
      "owner": "my-instance",
      "isGroup": false,
      "name": "John Doe",
      "createdAt": "2024-03-04T10:30:00.000Z",
      "updatedAt": "2024-03-04T12:45:00.000Z"
    },
    {
      "id": "chat_456",
      "remoteJid": "[e-mail]",
      "owner": "my-instance",
      "isGroup": true,
      "name": "Project Team",
      "createdAt": "2024-03-03T15:20:00.000Z",
      "updatedAt": "2024-03-04T11:30:00.000Z"
    }
  ],
  "total": 2
}

{
  "error": "Invalid query parameters",
  "message": "Limit must be a positive number"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}