> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

# List Chats

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

## 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.

<Note>
  This endpoint returns both individual and group chats. Use the `isGroup` field in the response to distinguish between them.
</Note>

## Authentication

This endpoint requires authentication via the `apikey` header.

<ParamField path="header.apikey" type="string" required>
  Your Evolution API key for authentication.
</ParamField>

## Path Parameters

<ParamField path="path.instanceName" type="string" required>
  The name of your WhatsApp instance.
</ParamField>

## Request Body

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

<ParamField body="where" type="object">
  Filter criteria for chats.

  <Expandable title="properties">
    <ParamField body="where.remoteJid" type="string">
      Filter by remote JID (WhatsApp ID).
    </ParamField>

    <ParamField body="where.owner" type="string">
      Filter by chat owner.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="limit" type="number" default="20">
  Maximum number of chats to return.
</ParamField>

<ParamField body="offset" type="number" default="0">
  Number of chats to skip (for pagination).
</ParamField>

<ParamField body="sort" type="object">
  Sorting configuration.

  <Expandable title="properties">
    <ParamField body="sort.field" type="string">
      Field name to sort by (e.g., "createdAt").
    </ParamField>

    <ParamField body="sort.order" type="string">
      Sort order: "asc" or "desc".
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="chats" type="array">
  Array of chat objects.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique chat identifier.
    </ResponseField>

    <ResponseField name="remoteJid" type="string">
      WhatsApp JID of the chat.
    </ResponseField>

    <ResponseField name="owner" type="string">
      Instance owner.
    </ResponseField>

    <ResponseField name="isGroup" type="boolean">
      Whether this is a group chat.
    </ResponseField>

    <ResponseField name="name" type="string">
      Chat display name.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the chat was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of last update.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of chats matching the query.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "chats": [
      {
        "id": "chat_123",
        "remoteJid": "5511999999999@s.whatsapp.net",
        "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": "120363123456789@g.us",
        "owner": "my-instance",
        "isGroup": true,
        "name": "Project Team",
        "createdAt": "2024-03-03T15:20:00.000Z",
        "updatedAt": "2024-03-04T11:30:00.000Z"
      }
    ],
    "total": 2
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid query parameters",
    "message": "Limit must be a positive number"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid API key"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Instance not found",
    "message": "The instance 'my-instance' does not exist"
  }
  ```
</ResponseExample>