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
ParameterdialogId (path) Typestring Requiredyes Default— DescriptionDialog 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
Parameterquery (query) Typestring Requiredyes Default— DescriptionSearch string. At least 3 characters after trimming blanks
ParameterlastId (query) Typenumber Requiredno Default— DescriptionCursor: the smallest message id of the previous page, the largest with order=asc. The boundary itself is not included
Parameterorder (query) Typestring Requiredno Defaultdesc Descriptiondesc — newest first, asc — oldest first
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionMessages 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.messages Typearray DescriptionMessages found on the page
Fielddata.messages[].id Typenumber DescriptionMessage ID
Fielddata.messages[].chatId Typenumber DescriptionChat ID — equals data.chat.id in the chat loading response
Fielddata.messages[].authorId Typenumber DescriptionAuthor ID — the profile is in data.users of the same response or can be fetched by user ID. 0 — a system message
Fielddata.messages[].date Typestring DescriptionDate sent (ISO 8601)
Fielddata.messages[].text Typestring DescriptionMessage text
Fielddata.users Typearray DescriptionAuthors of the messages found
Fielddata.usersShort Typearray DescriptionShort user cards: id, name, avatar, color, type
Fielddata.files Typearray DescriptionFiles of the messages found
Fielddata.reactions Typearray DescriptionReactions to the messages found
Fielddata.additionalMessages Typearray DescriptionMessages referenced by the messages found: quotes and replies
Fielddata.tariffRestrictions Typeobject DescriptionPlan restrictions on message history: isHistoryLimitExceeded
Fielddata.hasNextPage Typeboolean DescriptionThere are more matching messages after this page
Fieldmeta.requestedLimit Typenumber DescriptionThe limit passed, when it was outside the range from 1 to 200
Fieldmeta.appliedLimit Typenumber DescriptionThe 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
HTTP400 CodeINVALID_PARAMS DescriptionNo 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 reported "not found". The Bitrix24 code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error, for example CHAT_NOT_FOUND. The Bitrix24 code is in error.b24Code
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionThe 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