For AI agents: markdown of this page — /docs-content-en/chats/messages/search.md documentation index — /llms.txt

Search messages in a chat

GET /v1/chats/:dialogId/messages/search

Finds the messages of one chat whose text contains the query string — the v2 messenger method im.v2.Chat.Message.search. Newest first by default. The response has the shape of the message history in the v2 mode: the messages found and the collections that go with them. The me alias as dialogId addresses the current user's personal dialog — see the Chats overview for details.

To search chats by title, use chat search.

Parameters

Parameter Type Required Default Description
dialogId (path) string yes — Dialog ID: numeric user ID for personal messages, chatXXX for group chats. The special me alias — the current user's personal dialog
query (query) string yes — Search string. At least 3 characters after trimming blanks
lastId (query) number no — Cursor: the smallest message id of the previous page, the largest with order=asc. The boundary itself is not included
order (query) string no desc desc — newest first, asc — oldest first
limit (query) number no 50 Messages per page, from 1 to 200: a value outside the range is clamped and echoed in meta.requestedLimit and meta.appliedLimit

Any other parameter or a repeated parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Found:', data.messages.map((m) => m.id), 'has more:', data.hasNextPage)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Found:', data.messages.map((m) => m.id), 'has more:', data.hasNextPage)

Response fields

Field Type Description
success boolean Always true on success
data.messages array Messages found on the page
data.messages[].id number Message ID
data.messages[].chatId number Chat ID
data.messages[].authorId number Author ID. 0 — a system message
data.messages[].date string Sent date (ISO 8601)
data.messages[].text string Message text
data.users array Authors of the messages found
data.usersShort array Short user cards: id, name, avatar, color, type
data.files array Files of the messages found
data.reactions array Reactions to the messages found
data.additionalMessages array Messages referenced by the messages found: quotes and replies
data.tariffRestrictions object Plan restrictions on message history: isHistoryLimitExceeded
data.hasNextPage boolean There are more matching messages after this page
meta.requestedLimit number The limit passed, when it was outside the range from 1 to 200
meta.appliedLimit number The limit value applied

The response also carries stickers, forwardSource and copilot — collections of the v2 message history shared by all responses that return messages.

Response example

JSON 
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-09-20T10:01:00+00:00",
        "text": "The mockup is ready for review",
        "params": {}
      }
    ],
    "users": [
      { "id": 7, "name": "Anna Smith", "firstName": "Anna", "lastName": "Smith", "avatar": "", "type": "user" }
    ],
    "usersShort": [
      { "id": 7, "name": "Anna Smith", "avatar": "", "color": "#df532d", "type": "user" }
    ],
    "files": [],
    "reactions": [],
    "stickers": [],
    "additionalMessages": [],
    "forwardSource": null,
    "copilot": null,
    "tariffRestrictions": { "isHistoryLimitExceeded": false },
    "hasNextPage": false
  }
}

Error response example

400 — the query is shorter than three characters:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`query` is required: at least 3 characters after trimming blanks."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS No query, or it is shorter than 3 characters after trimming blanks; a parameter other than query, lastId, order, limit; a repeated parameter or an invalid value. Checked before any call to Bitrix24
404 ENTITY_NOT_FOUND Bitrix24 reported "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error, for example CHAT_NOT_FOUND; the portal code is in error.b24Code
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
502 ME_ALIAS_RESOLUTION_FAILED The me alias could not be resolved: Bitrix24 did not return the current user's ID

Full list of common API errors — Errors.

Known specifics

Search may make you a member. When the chat allows auto-join, search adds the current user as a member, as loading a chat does. A READONLY key may use this read operation; search does not mark messages read. The user's Bitrix24 access and the im scope still apply.

A short query is rejected. Bitrix24 does not apply the filter to a string shorter than three characters and would return the whole chat history instead of search results. Such a query is therefore rejected before any call to Bitrix24. Leading and trailing blanks do not count.

Matching is by substring. The query needle also finds probe-needle. Bitrix24 treats % and _ as wildcards and does not escape them.

System messages are found too. The system message about a pin quotes the pinned text, so it appears in the results along with the original. You can tell it apart by authorId 0.

Continue in the message history. To open the chat at a found message, use messages around a message.

See also