#Чаты и сообщения

Работайте с мессенджером Битрикс24 от имени авторизованного пользователя. Находите чаты CRM-сущностей, читайте и отправляйте сообщения, управляйте участниками, загружайте файлы.

#Обзор

Chats API оборачивает Bitrix24 REST API (im.*) в 21 RESTful-эндпоинт. В отличие от бот-платформы (скоуп imbot), этот API работает от имени пользователя, привязанного к API-ключу, и использует скоуп im.

Требуемый скоуп: im

Базовый URL: https://vibecode.bitrix24.tech/v1

Авторизация: заголовок X-Api-Key с вашим API-ключом.

Как работает прокси:

Параметры из тела запроса / query-строки передаются в Bitrix24 как есть, без фильтрации
Прокси автоматически подставляет токены авторизации — вам не нужно хранить и передавать токены
Ответы приходят в формате { success: true, data: <результат> } или { success: false, error: { code, message } }

dialogId vs chatId:

dialogId — идентификатор диалога: число (ID пользователя) для личных чатов, "chatN" (например "chat123") для групповых
chatId — числовой ID чата (без префикса chat). Используется в эндпоинтах управления чатом, участниками, файлами

#Быстрый старт

#1. Найдите чат CRM-сделки

Terminal

curl -H "X-Api-Key: $VIBE_KEY" \
  "https://vibecode.bitrix24.tech/v1/chats/find?entityType=CRM&entityId=DEAL|123"

Ответ:

JSON

{
  "success": true,
  "data": {
    "id": 456,
    "title": "Чат по сделке: Поставка оборудования",
    "type": "chat",
    "entityType": "CRM",
    "entityId": "DEAL|123",
    "dialogId": "chat456"
  }
}

#2. Прочитайте последние сообщения

Terminal

curl -H "X-Api-Key: $VIBE_KEY" \
  "https://vibecode.bitrix24.tech/v1/chats/chat456/messages?limit=5"

Ответ:

JSON

{
  "success": true,
  "data": {
    "chatId": 456,
    "messages": [
      {
        "id": 8901,
        "chatId": 456,
        "authorId": 1,
        "date": "2026-03-31T09:15:00+03:00",
        "text": "Коллеги, КП утверждено. Можно выставлять счёт."
      },
      {
        "id": 8899,
        "chatId": 456,
        "authorId": 3,
        "date": "2026-03-31T09:10:00+03:00",
        "text": "Клиент подтвердил условия по телефону."
      }
    ],
    "users": {
      "1": { "id": 1, "name": "Иван Петров", "firstName": "Иван", "lastName": "Петров" },
      "3": { "id": 3, "name": "Мария Сидорова", "firstName": "Мария", "lastName": "Сидорова" }
    }
  }
}

#3. Отправьте ответ

Terminal

curl -X POST https://vibecode.bitrix24.tech/v1/chats/chat456/messages \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Счёт выставлен. Номер: СЧ-2026-0458" }'

Ответ:

JSON

{
  "success": true,
  "data": 8902
}

#Поиск чатов

#GET /v1/chats/recent

Возвращает список последних диалогов пользователя (личные и групповые чаты). Bitrix24: im.recent.list

Параметры:

Параметр	В	Тип	Обяз.	По умолч.	Описание
—	—	—	—	—	Все query-параметры передаются в Bitrix24 как есть

Пример (curl):

Terminal

curl -H "X-Api-Key: $VIBE_KEY" \
  "https://vibecode.bitrix24.tech/v1/chats/recent"

Пример (JavaScript):

javascript

const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/recent', {
  headers: { 'X-Api-Key': VIBE_KEY }
})
const { data } = await res.json()
console.log('Последние чаты:', data)

Ответ (успех):

JSON

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "chat456",
        "chatId": 456,
        "type": "chat",
        "avatar": "",
        "title": "Чат по сделке: Поставка оборудования",
        "message": {
          "id": 8901,
          "text": "Счёт выставлен. Номер: СЧ-2026-0458",
          "senderId": 1,
          "date": "2026-03-31T09:20:00+03:00"
        },
        "counter": 0,
        "pinned": false
      },
      {
        "id": "3",
        "chatId": 91,
        "type": "private",
        "avatar": "https://portal.bitrix24.ru/upload/resize_cache/123/photo.jpg",
        "title": "Мария Сидорова",
        "message": {
          "id": 8850,
          "text": "Хорошо, жду документы.",
          "senderId": 3,
          "date": "2026-03-31T08:45:00+03:00"
        },
        "counter": 2,
        "pinned": false
      }
    ]
  }
}

Ошибки:

Код	HTTP	Описание
`SCOPE_DENIED`	403	API-ключ не имеет скоупа `im`
`TOKEN_MISSING`	401	API-ключ не имеет настроенных токенов