#Чаты и сообщения
Работайте с мессенджером Битрикс24 от имени авторизованного пользователя: находите чаты CRM-сущностей, читайте и отправляйте сообщения, управляйте участниками, загружайте файлы и получайте события через опрос.
Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key
Быстрый старт | Полный пример | Справочник эндпоинтов | Коды ошибок
#Разделы документации
- Поиск чатов — список последних диалогов, поиск чата CRM-сущности, текстовый поиск, информация о диалоге
- Сообщения — чтение, отправка, редактирование, удаление, отметка прочитанными, массовая загрузка
- Управление чатами — создание групповых чатов, переименование, передача владения, выход
- Участники — список участников, добавление, удаление
- Файлы — загрузка файлов в чат, метаданные файла, папка чата на Диске
- События — подписка, опрос событий мессенджера, отписка
#Оформление сообщений
Справочники по оформлению текста при отправке и редактировании сообщений:
#Идентификаторы чатов
В запросах встречаются два вида идентификаторов:
dialogId— идентификатор диалога: число (ID пользователя) для личной переписки, строка видаchatN(напримерchat123) для групповых чатов.chatId— числовой ID чата без префиксаchat. Нужен для управления чатом, участниками и файлами.
Вместо своего идентификатора можно передать литерал me — он заменяется на ID текущего пользователя, которому принадлежит ключ. Так можно отправить сообщение самому себе, не запрашивая свой ID отдельным вызовом. Литерал пишется строчными буквами и работает везде, где принимается dialogId: информация о диалоге, чтение и отправка сообщений, список участников.
Пример — отправить себе уведомление:
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. Найдите чат сделки
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://vibecode.bitrix24.tech/v1/chats/find?entityType=CRM&entityId=DEAL|123"
Ответ:
{
"success": true,
"data": {
"id": 2741
}
}
data.id — числовой chatId. Для построения dialogId при обращении к эндпоинтам сообщений добавьте префикс chat: chat2741.
#2. Прочитайте сообщения
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://vibecode.bitrix24.tech/v1/chats/chat2741/messages?limit=5"
Ответ:
{
"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. Отправьте ответ
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"}'
Ответ:
{
"success": true,
"data": 36889
}
data — ID отправленного сообщения.
#Полный пример
Непрерывный сценарий: создать групповой чат, отправить приветствие, отметить переписку прочитанной, переименовать чат и выйти из него.
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 недоступен или вернул ошибку сервера |
Общие коды авторизации, ключей и лимитов — на странице Ошибки.