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

Search chats by text

GET /v1/chats/search

Searches chats and dialogs by title or message text. Returns an array of chat objects matching the search query.

Parameters

Parameter Type Required Description
Parametersearch Typestring Requiredyes DescriptionSearch string. When empty, returns results without filtering

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/search?search=Deal" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/search?search=Deal" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const query = new URLSearchParams({ search: 'Deal' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/chats/search?${query}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Chats found:', data.length)

JavaScript — OAuth application

javascript 
const query = new URLSearchParams({ search: 'Deal' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/chats/search?${query}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of found chats
Fielddata[].id Typenumber DescriptionNumeric chat ID. Pass it as chatN in dialogId — for example, to get dialog details
Fielddata[].name Typestring DescriptionChat title
Fielddata[].description Typestring DescriptionChat description
Fielddata[].type Typestring DescriptionChat type: chat, general, openlines, copilot, channel, crm, tasks, and others
Fielddata[].owner Typenumber DescriptionChat owner ID. Source: user list
Fielddata[].userCounter Typenumber DescriptionNumber of members
Fielddata[].messageCount Typenumber DescriptionTotal number of messages
Fielddata[].counter Typenumber DescriptionNumber of unread messages
Fielddata[].unreadId Typenumber DescriptionID of the first unread message. Source: reading messages
Fielddata[].lastMessageId Typenumber DescriptionID of the last message. Source: reading messages
Fielddata[].entityType Typestring DescriptionType of the linked entity (CRM, TASKS, GENERAL, and others)
Fielddata[].entityId Typestring DescriptionID of the linked entity. For CRM — <TYPE>|<ID>, the format accepted by finding a CRM entity chat
Fielddata[].entityLink Typeobject DescriptionLink to the linked entity
Fielddata[].entityLink.type Typestring DescriptionType of the linked record. For CRM — the entity type: DEAL, DYNAMIC, and others
Fielddata[].entityLink.url Typestring DescriptionRelative URL of the entity in your Bitrix24 account
Fielddata[].entityLink.id Typestring DescriptionEntity ID in string format, same as entityId
Fielddata[].dateCreate Typestring DescriptionChat creation date (ISO 8601)
Fielddata[].role Typestring DescriptionRole of the current user: owner, manager, member
Fielddata[].extranet Typeboolean DescriptionWhether the chat is an extranet chat
Fielddata[].permissions Typeobject DescriptionMember permissions by operation

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 456,
      "name": "Deal chat",
      "description": "Here we discuss the deal details",
      "type": "crm",
      "owner": 1,
      "userCounter": 3,
      "messageCount": 9,
      "counter": 0,
      "unreadId": 0,
      "lastMessageId": 1450,
      "entityType": "CRM",
      "entityId": "DEAL|42",
      "entityLink": {
        "type": "DEAL",
        "url": "/crm/deal/details/42/",
        "id": "DEAL|42"
      },
      "dateCreate": "2026-03-03T15:07:38+00:00",
      "role": "owner",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    },
    {
      "id": 789,
      "name": "Discussion of deal No. 5",
      "description": null,
      "type": "chat",
      "owner": 12,
      "userCounter": 2,
      "messageCount": 4,
      "counter": 0,
      "unreadId": 0,
      "lastMessageId": 890,
      "entityType": "",
      "entityId": "",
      "entityLink": {
        "type": "",
        "url": "",
        "id": ""
      },
      "dateCreate": "2026-02-26T15:56:08+00:00",
      "role": "member",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    }
  ]
}

Error response example

403 — no im scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error (details in message)
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error

The full list of general API errors — Errors.

Known specifics

  • The search is performed by chat title. Matching by message text depends on your Bitrix24 account's capabilities and is not guaranteed for all chat types.
  • Results do not support pagination via limit and offset. To get more results, refine the search query.
  • To search for the chat of a specific CRM entity, use GET /v1/chats/find — it accepts entityType and entityId and returns an exact match.

See also