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

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

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

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

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

• Ссылки и гости — ссылки на чат для сотрудников, вступление по коду, гостевые ссылки и приглашения по почте и SMS
• Поиск чатов — последние диалоги, счётчики непрочитанного, папки, проверка доступа и внешний ID, каналы, коллабы и внешние чаты, общие чаты, изменения с момента, чат CRM-сущности, поиск и сведения о диалоге
• Сообщения — чтение, загрузка, контекст, отправка, редактирование, удаление, отметка прочитанными, «прочитать позже», массовая загрузка
• Управление чатами — групповые чаты, владение, уведомления, метка «непрочитано», вступление, родительские чаты, удаление, закреп, прочтение всех чатов или раздела списка, выход
• Участники — участники, упоминания, проверка участия и менеджеры, добавление и удаление
• Файлы — загрузка файлов в чат, загрузка без публикации и публикация загруженных файлов, сохранение на Диск, расшифровка аудио, метаданные файла, папка чата на Диске
• CoPilot — черновой чат CoPilot, модель и роль ассистента, переписывание и оценка ответов
• Стикеры — наборы стикеров, подключение чужих наборов, удаление, недавние стикеры
• Настройки мессенджера — общие настройки пользователя, статус
• Служебные методы — формы задачи и потока, контекст для ботов, Zoom, состояние обновлений, ограничения тарифа, промо-подсказки, отдел пользователя, выход десктоп-приложения
• События — подписка, опрос событий мессенджера, отписка

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

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

• Форматирование текста (BB-коды)
• Клавиатура
• Вложения

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

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

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

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

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

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": "Квартальный отчёт готов"}'

Личное сообщение сотруднику

Чтобы отправить сотруднику личное сообщение, подставьте его числовой ID пользователя Битрикс24 в качестве dialogId. Отдельный поиск или создание диалога не нужны — POST /v1/chats/:dialogId/messages с числовым dialogId доставляет сообщение в личную переписку с этим сотрудником. Поиск чата GET /v1/chats/find находит чаты CRM-сущностей, для личного диалога он не требуется.

Числовой ID сотрудника — из списка пользователей GET /v1/users.

curl -X POST "https://vibecode.bitrix24.tech/v1/chats/42/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": 2741,
    "messages": [
      {
        "id": 9357,
        "chatId": 2741,
        "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, затем покидайте чат — иначе выход зафиксируется, но владельцем останетесь вы.

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

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

Коды ошибок

Ошибки чатов

Коды портала приходят в error.b24Code при 422 BITRIX_ERROR. Для закрепа чатов это FOLDER_PINS_LIMIT_EXCEEDED — уже закреплено 45 чатов, и INVALID_PIN_POSITION — position больше 45 при смене порядка закреплённого чата.

Системные ошибки

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

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

• Бот-платформа
• Уведомления
• Ключи и авторизация
• Лимиты и оптимизация
• Справочник ошибок