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

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

Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Быстрый старт | Полный пример | Справочник эндпоинтов | Коды ошибок

#Разделы документации

  • Поиск чатов — список последних диалогов, поиск чата CRM-сущности, текстовый поиск, информация о диалоге
  • Сообщения — чтение, отправка, редактирование, удаление, отметка прочитанными, массовая загрузка
  • Управление чатами — создание групповых чатов, переименование, передача владения, выход
  • Участники — список участников, добавление, удаление
  • Файлы — загрузка файлов в чат, метаданные файла, папка чата на Диске
  • События — подписка, опрос событий мессенджера, отписка

#Оформление сообщений

Справочники по оформлению текста при отправке и редактировании сообщений:

#Идентификаторы чатов

В запросах встречаются два вида идентификаторов:

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

Вместо своего идентификатора можно передать литерал me — он заменяется на ID текущего пользователя, которому принадлежит ключ. Так можно отправить сообщение самому себе, не запрашивая свой ID отдельным вызовом. Литерал пишется строчными буквами и работает везде, где принимается dialogId: информация о диалоге, чтение и отправка сообщений, список участников.

Пример — отправить себе уведомление:

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/me/messages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Квартальный отчёт готов"}'

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

Найдите чат CRM-сделки, прочитайте сообщения и отправьте ответ.

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

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

Ответ:

JSON
{
  "success": true,
  "data": {
    "id": 2741
  }
}

data.id — числовой chatId. Для построения dialogId при обращении к эндпоинтам сообщений добавьте префикс chat: chat2741.

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

Terminal
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/chats/chat2741/messages?limit=5"

Ответ:

JSON
{
  "success": true,
  "data": {
    "chatId": 253,
    "messages": [
      {
        "id": 9357,
        "chatId": 253,
        "authorId": 1,
        "date": "2026-04-26T18:10:54+03:00",
        "text": "Коллеги, КП утверждено. Можно выставлять счёт.",
        "unread": false
      }
    ],
    "users": [
      {
        "id": 1,
        "name": "Иван Петров",
        "firstName": "Иван",
        "lastName": "Петров"
      }
    ],
    "files": []
  }
}

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

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

Ответ:

JSON
{
  "success": true,
  "data": 36889
}

data — ID отправленного сообщения.

#Полный пример

Непрерывный сценарий: создать групповой чат, отправить приветствие, отметить переписку прочитанной, переименовать чат и выйти из него.

javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

// 1. Создаём групповой чат
const created = await api('POST', '/chats', {
  title: 'Рабочая группа',
  users: [1, 5, 12],
})
const chatId = created.data            // числовой chatId
const dialogId = `chat${chatId}`       // dialogId для эндпоинтов сообщений
console.log('Чат создан, ID:', chatId)

// 2. Отправляем приветствие
const sent = await api('POST', `/chats/${dialogId}/messages`, {
  message: 'Добро пожаловать в рабочую группу!',
})
console.log('Сообщение отправлено, ID:', sent.data)

// 3. Отмечаем переписку прочитанной
const read = await api('POST', `/chats/${dialogId}/read`, {})
console.log('Непрочитанных осталось:', read.data.counter)

// 4. Переименовываем чат — управление идёт по числовому chatId, без префикса chat
await api('PATCH', `/chats/${chatId}`, {
  title: 'Проект: Поставка оборудования',
})

// 5. Выходим из чата
await api('POST', `/chats/${chatId}/leave`, {})
console.log('Готово')

Если вы владелец чата, сначала передайте владение через POST /v1/chats/:chatId/owner, затем покидайте чат — иначе выход зафиксируется, но владельцем останетесь вы.

#Справочник эндпоинтов

Все 23 эндпоинта раздела:

Метод Путь Bitrix24 метод Описание
GET /v1/chats/recent im.recent.list Последние диалоги
GET /v1/chats/find im.chat.get Найти чат CRM-сущности
GET /v1/chats/search im.search.chat.list Поиск чатов по тексту
GET /v1/chats/:dialogId im.dialog.get Информация о диалоге
GET /v1/chats/:dialogId/messages im.dialog.messages.get Чтение сообщений
POST /v1/chats/:dialogId/messages im.message.add Отправка сообщения
PATCH /v1/chats/:dialogId/messages/:messageId im.message.update Редактирование сообщения
DELETE /v1/chats/:dialogId/messages/:messageId im.message.delete Удаление сообщения
POST /v1/chats/:dialogId/read im.dialog.read Отметить прочитанным
POST /v1/chats/messages/bulk batch (im.dialog.messages.get) Массовая загрузка из нескольких диалогов
POST /v1/chats im.chat.add Создать групповой чат
PATCH /v1/chats/:chatId im.chat.updateTitle Переименовать чат
POST /v1/chats/:chatId/owner im.chat.setOwner Передать владение
POST /v1/chats/:chatId/leave im.chat.leave Покинуть чат
GET /v1/chats/:dialogId/users im.dialog.users.list Список участников
POST /v1/chats/:chatId/users im.chat.user.add Добавить участников
DELETE /v1/chats/:chatId/users im.chat.user.delete Удалить участника
POST /v1/chats/:chatId/files im.disk.folder.get + disk.folder.uploadfile + im.disk.file.commit Загрузить файл в чат
GET /v1/chats/files/:fileId disk.file.get Метаданные файла
GET /v1/chats/:chatId/folder im.disk.folder.get Папка чата на Диске
POST /v1/chats/events/subscribe im.v2.Event.subscribe Подписаться на события
POST /v1/chats/events/unsubscribe im.v2.Event.unsubscribe Отписаться от событий
GET /v1/chats/events im.v2.Event.get Получить события

#Коды ошибок

Коды, специфичные для работы с чатами:

Код HTTP Описание
SCOPE_DENIED 403 API-ключ не имеет скоупа im
TOKEN_MISSING 401 У API-ключа не настроены токены Битрикс24
MISSING_PARAMS 400 Не переданы обязательные параметры (entityType/entityId при поиске, filename/content при загрузке файла)
INVALID_REQUEST 400 Некорректное тело запроса (например, пустой массив dialogs в массовой загрузке)
BATCH_LIMIT_EXCEEDED 400 Превышен лимит 50 диалогов в массовой загрузке
INVALID_CHAT_ID 400 chatId не является положительным целым числом
TITLE_EMPTY 400 Пустое название при переименовании чата
INVALID_OFFSET 400 Некорректный offset при опросе событий
INVALID_LIMIT 400 limit вне допустимого диапазона
CHAT_NOT_FOUND_OR_NO_ACCESS 404 Чат не существует или нет прав на операцию
DIALOG_NOT_FOUND_OR_NO_ACCESS 404 Диалог не существует или нет доступа
ENTITY_NOT_FOUND 404 Запрошенный объект не найден
FILE_NOT_FOUND 404 Файл с указанным fileId не найден
FOLDER_NOT_FOUND 404 Папка чата на Диске не найдена
UPLOAD_FAILED 500 Не удалось загрузить файл на Диск
ME_ALIAS_RESOLUTION_FAILED 502 Не удалось определить текущего пользователя для алиаса me
BITRIX_ERROR 422 Битрикс24 вернул ошибку (текст в поле message)
BITRIX_UNAVAILABLE 502 Портал Битрикс24 недоступен или вернул ошибку сервера

Общие коды авторизации, ключей и лимитов — на странице Ошибки.

#Смотрите также