Skip to main content
GET
https://api.enviaai.app
/
v1
/
messages
/
chats
List Chats
curl --request GET \
  --url https://api.enviaai.app/v1/messages/chats \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "data": [
    {
      "chatId": "chat_abc123",
      "phone": "5511999999999",
      "contactName": "John Doe",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "lastMessage": {
        "messageId": "msg_xyz789",
        "content": "Thanks for your help!",
        "timestamp": "2026-02-03T12:30:00.000Z",
        "isFromMe": false,
        "type": "text"
      },
      "unreadCount": 2,
      "isGroup": false,
      "createdAt": "2026-01-15T10:00:00.000Z"
    },
    {
      "chatId": "chat_def456",
      "phone": "5521988888888",
      "contactName": "Jane Smith",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "lastMessage": {
        "messageId": "msg_abc456",
        "content": "[Image]",
        "timestamp": "2026-02-03T11:45:00.000Z",
        "isFromMe": true,
        "type": "image"
      },
      "unreadCount": 0,
      "isGroup": false,
      "createdAt": "2026-01-20T14:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Overview

Get a paginated list of all conversations (chats) for a specific WhatsApp instance. Returns chat metadata including the last message, unread count, and contact information.

Query Parameters

instanceId
string
required
The ID of the WhatsApp instance
limit
number
default:"50"
Maximum number of chats to return (1-100)
offset
number
default:"0"
Number of chats to skip for pagination
Search chats by contact name or phone number
unreadOnly
boolean
default:"false"
Only return chats with unread messages
sortBy
string
default:"lastMessageAt"
Sort field: lastMessageAt, unreadCount, or contactName
sortOrder
string
default:"desc"
Sort order: asc or desc

Response

success
boolean
Indicates if the request was successful
data
array
Array of chat objects
data[].chatId
string
Unique identifier for the chat
data[].phone
string
Contact’s phone number in international format
data[].contactName
string
Contact’s name (if saved in the phone)
data[].profilePicUrl
string
URL of the contact’s profile picture
data[].lastMessage
object
The most recent message in the chat
data[].lastMessage.content
string
Message content or media description
data[].lastMessage.timestamp
string
ISO 8601 timestamp of the message
data[].lastMessage.isFromMe
boolean
Whether the message was sent by the instance
data[].unreadCount
number
Number of unread messages in the chat
data[].isGroup
boolean
Whether the chat is a group
pagination
object
Pagination metadata
pagination.total
number
Total number of chats
pagination.limit
number
Number of chats per page
pagination.offset
number
Current offset
pagination.hasMore
boolean
Whether there are more chats to fetch

Examples

Get Recent Chats

const chats = await client.messages.getChats({
  instanceId: 'inst_abc123',
  limit: 20
});

console.log(`Found ${chats.pagination.total} chats`);
chats.data.forEach(chat => {
  console.log(`${chat.contactName}: ${chat.lastMessage.content}`);
});
{
  "success": true,
  "data": [
    {
      "chatId": "chat_abc123",
      "phone": "5511999999999",
      "contactName": "John Doe",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "lastMessage": {
        "messageId": "msg_xyz789",
        "content": "Thanks for your help!",
        "timestamp": "2026-02-03T12:30:00.000Z",
        "isFromMe": false,
        "type": "text"
      },
      "unreadCount": 2,
      "isGroup": false,
      "createdAt": "2026-01-15T10:00:00.000Z"
    },
    {
      "chatId": "chat_def456",
      "phone": "5521988888888",
      "contactName": "Jane Smith",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "lastMessage": {
        "messageId": "msg_abc456",
        "content": "[Image]",
        "timestamp": "2026-02-03T11:45:00.000Z",
        "isFromMe": true,
        "type": "image"
      },
      "unreadCount": 0,
      "isGroup": false,
      "createdAt": "2026-01-20T14:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Search Chats

const chats = await client.messages.getChats({
  instanceId: 'inst_abc123',
  search: 'John'
});

Get Unread Chats

const unreadChats = await client.messages.getChats({
  instanceId: 'inst_abc123',
  unreadOnly: true,
  sortBy: 'unreadCount',
  sortOrder: 'desc'
});

Paginate Through All Chats

let offset = 0;
const limit = 50;
let allChats = [];

while (true) {
  const response = await client.messages.getChats({
    instanceId: 'inst_abc123',
    limit,
    offset
  });

  allChats = allChats.concat(response.data);

  if (!response.pagination.hasMore) break;
  offset += limit;
}

console.log(`Total chats: ${allChats.length}`);

Error Codes

CodeDescription
invalid_instanceThe instance ID is invalid or doesn’t exist
instance_disconnectedThe WhatsApp instance is not connected
invalid_parametersInvalid query parameters