Skip to main content
Node.js

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-phone
string

Optional. The phone to scope this request to — in country code + number format with no spaces or special characters (e.g. 919876543210), or the phone_id (phone-xxxxxxxxxxxx). When set, only chats for that phone are returned. When omitted, chats are returned — across all phones your token can access (the phones in your token's scope, or every phone in your organization if the token is unscoped). Passing a phone that is outside your token's scope returns a 401.

Example:

"{{orgPhone}}"

Query Parameters

​
offset
number
  • The offset value for paginating the results
  • Default 0
Example:

"0"

​
limit
number
  • The maximum number of chats to retrieve
  • Default 2000
Example:

"1000"

​
sort_by
enum<string>
default:created_at
  • Value to sort the incoming chats
  • Possible values: created_at, latest_message_timestamp
  • Default created_at
Available options:
created_at,
latest_message_timestamp
Example:

"created_at"

​
sort_order
enum<string>
default:desc
  • Order to sort the results
  • Possible values: asc, desc
  • Default desc
Available options:
asc,
desc
Example:

"desc"

​
chat_id
string
  • Filter to a specific chat by its chat_id (the chat's unique WhatsApp identifier, e.g. a group id ending in @g.us or a contact id ending in @c.us). Returns that single chat, the same way the Get Chat By ID endpoint does.
Example:

"120363392071406466@g.us"

​
chat_type
string
  • Filter chat by type of user, group or business
Example:

"group"

​
label
string
  • Filter all chats that contain a specific label provide
  • You can provide the name of the label or label_id
Example:

"label-kbvlbnvesomvgqpt"

​
start_time
string
  • The start_time to filter the results
Example:

"2025-04-25 or 2025-04-25T00:00:00Z"

​
end_time
string
  • The end_time to filter the results
Example:

"2025-04-31 or 2025-04-31T23:59:59Z"

Response

200 OK

Note: members associated with a chat are not returned. You can fetch a specific chat by calling the Get Chat By ID endpoint

​
from
number

The starting index of the returned chats.

Example:

1

​
to
number

The ending index of the returned chats.

Example:

10

​
count
number

The total count of chats.

Example:

10

​
chats
array

An array of chat objects. Refer to the chat object here