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
search string yes Search 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
data array Array of found chats
data[].id number Numeric chat ID
data[].name string Chat title
data[].description string Chat description
data[].type string Chat type: chat, general, openlines, copilot, channel, crm, tasks, and others
data[].owner number Chat owner ID
data[].userCounter number Number of members
data[].messageCount number Total number of messages
data[].counter number Number of unread messages
data[].unreadId number ID of the first unread message
data[].lastMessageId number ID of the last message
data[].entityType string Type of the linked entity (CRM, TASKS, GENERAL, and others)
data[].entityId string ID of the linked entity
data[].entityLink object Link to the linked entity
data[].entityLink.type string Link type
data[].entityLink.url string Relative URL of the entity in your Bitrix24 account
data[].entityLink.id string Entity ID in string format
data[].dateCreate string Chat creation date (ISO 8601)
data[].role string Role of the current user: owner, manager, member
data[].extranet boolean Whether the chat is an extranet chat
data[].permissions object Member 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": "CRM",
        "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
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
422 BITRIX_ERROR Bitrix24 returned an error (details in message)
502 BITRIX_UNAVAILABLE Bitrix24 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 messages depends on your Bitrix24 account's capabilities and is not guaranteed for all chat types.
  • Results do not support pagination via limit and offset. If you need to get a larger number of 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