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 response has the shape of the message history in the v2 mode: the messages found and the collections that go with them.

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 refers to the current user's personal dialog. chatXXX is the id field of a recent dialogs row; the user ID comes from the user list
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; the passed and applied values are 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 — equals data.chat.id in the chat loading response
data.messages[].authorId number Author ID — the profile is in data.users of the same response or can be fetched by user ID. 0 — a system message
data.messages[].date string Date sent (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 — only when it was clamped to a bound

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 Bitrix24 code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error, for example CHAT_NOT_FOUND. The Bitrix24 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 itself does not mark messages as read. The user's Bitrix24 permissions and the im scope are checked.

Matching is by substring. The query needle also finds probe-needle. The % and _ characters work as wildcards and are not escaped.

System messages are found too. The system message about pinning 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