How to get chats and messages via API

Chats and messages via the API are read in two requests: first the list of bot chats, then the messages of the specific chat. This is the same as opening the bot in the application and tapping on a co

Updated November 2, 20265 min

This article covers how to get a list of chats, paginate, find a specific chat, read the conversation, and convert operator, tag, and field IDs into readable names.

What you will need

API key with the Space viewer role or higher. Which role to choose — in the article API Key Permissions: Which Role to Assign.

Bot ID. How to find it — in the article First API request in 5 minutes.

Get the list of bot chats

The list of bot chats is returned by POST /chats/v1/search with bot_id in the body. Chats with the most recent messages come first:

POST

https://api.chatterfy.ai/public-api/chats/v1/search

List of bot chats

curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"bot_id": "ID_БОТА", "limit": 50}'

Field	Required	Description
`bot_id`	Yes	Bot ID
`limit`	No	Number of chats per page: from 1 to 100; default is 25
`sort`	No	`desc` — newest messages first (default), `asc` — reverse order
`filter`	No	Filter conditions: status, tags, dates, and others. More details in the article Chat filters in the API
`cursor`	No	The next page token from the previous response

Paginate through the chat list

One page of the chat list contains no more than 100 chats. Subsequent pages are requested using cursor and has_more:

Check pagination

If the response contains has_more: true, there are more chats. next_cursor contains the next page token.

Repeat the request with a cursor

Send the same request and add the cursor field with the value of next_cursor. Do not change other fields.

{
  "bot_id": "ID_БОТА",
  "limit": 50,
  "cursor": "ЗНАЧЕНИЕ_NEXT_CURSOR"
}

Stop on the last page

On the last page, has_more: false, and next_cursor is missing.

Search retrieves up to 10,000 chats

Beyond the 10,000th chat, the API will return a cursor_out_of_range error. To retrieve more, use export — How to export all chats via API.

The list changes while you are reading it: a chat with a new message moves to the top. If you are collecting chats into a table, remove duplicates by id.

Find a specific chat by name, username, or id

To find a chat by customer name, username, or Telegram id, pass the query filter:

{
  "bot_id": "ID_БОТА",
  "filter": { "field": "query", "value": "Анна" }
}

The chat list is taken from the search index, which lags behind the real state by a second or two. To get the chat exactly in its current state, request it by id via GET /chats/v1/{chat_id}:

GET

https://api.chatterfy.ai/public-api/chats/v1/{chat_id}

A single chat by id

curl 'https://api.chatterfy.ai/public-api/chats/v1/ID_ЧАТА' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Chat fields in the API response

What is returned in each chat from POST /chats/v1/search and GET /chats/v1/{chat_id}:

Field	Meaning
`id`	Chat id
`name`, `username`	Client name and username in Telegram. Without the `chat.contacts.read` permission, they arrive hidden
`external_id`	Client ID in Telegram
`status`	Chat status: `ai` — Auto, `manual` — Manual, as well as `waiting`, `ignore`, `blocked`, `error`, `stopped`, `finished`. What they mean is in the article Chat Status — conversation statuses
`assign_id`	Assignee ID. Name — in the Space member list, below
`tags`	Chat tag IDs
`custom_fields`	Chat fields: field `id`, its `key`, and `value`
`last_message`	Last message with all fields
`read_state.incoming_unread_count`	Number of unread client messages
`lead`	Where the client came from: campaign and Tracker tags. Learn more — Analytics and Tracker via API
`created_at`	When the chat was created

Read chat messages

Messages for a single chat are retrieved via POST /messages/v1/search with chat_id in the body. Without the type field, both messages and system events will be returned:

POST

https://api.chatterfy.ai/public-api/messages/v1/search

Messages of a single chat

curl -X POST 'https://api.chatterfy.ai/public-api/messages/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"chat_id": "ID_ЧАТА", "limit": 50, "order": "desc", "type": "message"}'

Field	What it means
`chat_id`	Chat ID. Required field
`limit`	Number of messages per page: up to 100, default is 25
`order`	`desc` — newest first (default), `asc` — oldest first
`type`	`message` — messages only, `event` — system events only (like tag or status changes). If omitted, both will be returned
`cursor`	Next page marker

Message pages are navigated the same way as chat pages: using cursor and has_more.

Message fields in the API response

What is returned in each message from POST /messages/v1/search:

{
  "id": "e1a7c3d9-4b2f-4e8a-9c6d-0f5b2a7e3c18",
  "chat_id": "9d4e1b27-3c8a-4f6e-b2d1-7a5c0e8f3b62",
  "type": "message",
  "status": "ready",
  "content": "Здравствуйте! Сколько стоит доставка?",
  "sender_type": "incoming",
  "read": true,
  "files": [],
  "created_at": "2026-10-28T09:15:42Z"
}

Field	Meaning
`content`	Message text
`sender_type`	`incoming` — from the client, `outcoming` — from your side
`sender`	ID of the operator who sent the message. Empty if sent by a bot
`status`	`ready` — sent, `waiting` — sending, `schedule` — scheduled, `failed` — failed to send, reason is in `error`
`files`	Attachments: type (`photo`, `document`, etc.) and `url`
`reply_message_id`	ID of the message to which this message is a reply
`is_mailing`	`true` if the message came from a mailing list
`edited_at`	When the message was edited

Convert operator, tag, and field IDs into names

People, tags, and fields in chats and messages are identified by ID. To show names, request the directories:

Space members — POST /spaces/v1/{space_id}/members/search. space_id is available in the bot data. The response contains two lists: accounts — employees and service_accounts — service accounts.

Bot tags — GET /bots/v1/{bot_id}/tags: id, name, and color of each tag.

Bot fields — GET /bots/v1/{bot_id}/custom-fields: id, key, name, and type of each field.

curl -X POST 'https://api.chatterfy.ai/public-api/spaces/v1/ID_SPACE/members/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Directories change rarely. Request them once and store them locally, rather than before each chat.

FAQ

Chat filters in the API

Chat filters are conditions used by the API to select chats: for example, 'unread', 'with the tag Paid', or 'came from Google'. The same filter works in search, counting, exporting, and event subscrip

How to send a message to a client via API

Sending a message via the API is how you respond to a client on behalf of your integration. The message reaches the client in their chat with the bot, just like an operator's response from the applica

How to update a chat via API: status, tags, assignee, fields

Modifying a chat via API is the same as editing a client card in the app: changing the status, assignee, tags, and fields. Everything is done with a single PATCH request, in which you pass only what y

How to export all chats via API

Chat export is a way to retrieve all of a bot's chats at once: into a spreadsheet, your CRM, or a database. It reads a snapshot of the chats at the moment of initiation, so it doesn't skip or repeat a

Was this article helpful?

How to get chats and messages via API

What you will need

Get the list of bot chats

Paginate through the chat list

Check pagination

Repeat the request with a cursor

Stop on the last page

Find a specific chat by name, username, or id

Chat fields in the API response

Read chat messages

Message fields in the API response

Convert operator, tag, and field IDs into names

FAQ

Why did the new chat not appear in the list immediately?

Why is the chat list empty?

How to find a chat by the client's Telegram ID?

Is it possible to get messages for all chats with one request?

How to get only unread chats?

Related