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
string
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