Conversation history

Returns the message history between the bot and its users — the same content that appears in the Telegram chat: incoming messages from users and outgoing messages sent by the bot. You can look up the conversation with a specific chat, search by message text, and filter by date and direction.

Request

Don't forget to add the authorization header for the request. More details in this section

POST /v1/messages/list

If your API key is tied to a single bot (a regular key from the "My Bots" section), you don't need to specify anything extra.

If you use a key from the «API Keys» section, issued for several bots at once, you must explicitly specify which bot it's for in every request — via the Resource-Key header or the resource_key field in the request body. The value is the bot's public key (the part before the colon in the bot's API key, found in "My Bots").

Pagination parameters

Parameter	Type	Default	Description
limit	int	20	Number of records (max. 500)
offset	int	0	Offset — how many records to skip from the start

Filters

All filters are optional and are passed directly in the request body (no nested object).

Filter	Type	Description
filter_chat_id	int	Show only the conversation with one chat (Telegram chat_id)
filter_way	int	Direction: 1 — incoming (from the user), 2 — outgoing (from the bot)
filter_type	string	Message/method type, e.g. message or sendMessage
filter_search	string	Search by message text (matches a substring)
filter_date_from	string	Start of the period, format YYYY-MM-DD HH:MM:SS
filter_date_to	string	End of the period, format YYYY-MM-DD HH:MM:SS

If you don't specify filter_date_from/filter_date_to, only messages from the last 30 days are returned by default. To get older history, set the period explicitly.

Results are always sorted from newest to oldest — custom sorting isn't supported.

Example request

POST /v1/messages/list
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "limit": 20,
  "offset": 0,
  "filter_chat_id": 123456789,
  "filter_search": "promo code"
}

Response

{
  "ok": true,
  "data": {
    "total": 42,
    "rows": [
      {
        "id": "a1b2c3d4-...",
        "chat_id": 123456789,
        "way": 1,
        "direction": "in",
        "type": "message",
        "date": "2026-07-05 14:30:00",
        "get_date": "2026-07-05 14:30:01",
        "text": "Hi, do I still have a promo code?",
        "data": {
          "message_id": 4821,
          "text": "Hi, do I still have a promo code?"
        }
      }
    ]
  }
}

Response fields

Field	Type	Description
total	int	Total number of messages matching the filters (regardless of limit/offset)
rows	array	List of messages, see the fields below
id	string	Internal message identifier
chat_id	int	Telegram chat_id — who the conversation is with
way	int	Direction: 1 — incoming, 2 — outgoing
direction	string	The same direction as text: in / out
type	string	Message/method type (e.g. message, sendMessage, editmessagetext, etc.)
date	string	Message date and time
get_date	string	Date and time the message was received by the platform (usually the same as date or slightly later)
text	string|null	Message text. null if the message has no text (e.g. a photo without a caption)
data	object	The full raw Telegram message object — may contain media, buttons, and other fields

data is the raw message object from the Telegram Bot API; its contents depend on the message type (text, photo, document, poll, etc.).

Error codes

Code	Description
400	A required parameter is missing or has an invalid format
401	The API key is missing or invalid
403	The resource is not accessible to this key
500	Internal server error

Error example:

{
  "ok": false,
  "error": { "errors": "resource_key is required" },
  "error_code": 400
}