#Bot-события (ONIMBOTV2*)

Приходят автоматически для всех ботов с eventMode: "fetch". Получаются через polling.

Каждое событие имеет структуру:

JSON 
{
  "eventId": 29,
  "type": "ONIMBOTV2JOINCHAT",
  "date": "2026-04-13T17:12:00+03:00",
  "data": {
    "dialogId": "chat3553",
    "bot": { ... },
    "chat": { ... },
    "user": { ... },
    "language": "ru"
  }
}
Поле Тип Описание
eventId number ID события — передайте как offset в следующем запросе polling
type string Код типа события
date string Дата и время (ISO 8601)
data object Данные события (структура зависит от типа)

#Список событий

Тип Описание
ONIMBOTV2MESSAGEADD Новое сообщение боту
ONIMBOTV2MESSAGEUPDATE Сообщение отредактировано
ONIMBOTV2MESSAGEDELETE Сообщение удалено
ONIMBOTV2JOINCHAT Бот добавлен в чат
ONIMBOTV2COMMANDADD Вызвана slash-команда
ONIMBOTV2REACTIONCHANGE Реакция на сообщение бота
ONIMBOTV2DELETE Бот удалён с портала
ONIMBOTV2CONTEXTGET Запрошен контекст диалога

#ONIMBOTV2MESSAGEADD

Новое сообщение боту (личное или @упоминание в групповом чате).

JSON 
{
  "eventId": 35,
  "type": "ONIMBOTV2MESSAGEADD",
  "date": "2026-04-13T17:15:00+03:00",
  "data": {
    "dialogId": "chat123",
    "bot": {
      "id": 42,
      "code": "support_bot",
      "type": "bot",
      "isHidden": false,
      "isReactionsEnabled": true,
      "eventMode": "fetch"
    },
    "message": {
      "id": 1501,
      "chatId": 123,
      "authorId": 1,
      "date": "2026-04-13T17:15:00+03:00",
      "text": "Привет, бот! Подскажи по задаче #42",
      "isSystem": false,
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "forward": null,
      "params": {
        "FILE_ID": ["15423"]
      },
      "viewedByOthers": false
    },
    "chat": {
      "id": 123,
      "dialogId": "chat123",
      "type": "chat",
      "name": "Рабочий чат",
      "owner": 1,
      "color": "#64a513",
      "entityType": "",
      "entityId": "",
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    },
    "user": {
      "id": 1,
      "active": true,
      "name": "Иван Петров",
      "firstName": "Иван",
      "lastName": "Петров",
      "workPosition": "Менеджер",
      "color": "#1eb4aa",
      "gender": "M",
      "extranet": false,
      "bot": false,
      "status": "online",
      "departments": [1, 5],
      "type": "employee"
    },
    "language": "ru"
  }
}

Поля data:

Поле Описание
dialogId ID диалога
bot Объект бота (id, code, type, eventMode)
message.id ID сообщения — используйте для ответа через replyId
message.params.FILE_ID Массив строк — ID прикреплённых файлов. Скачать: GET /files/:fileId
message.forward Объект пересланного сообщения или null
chat.entityType Тип привязки: LINES (открытая линия), CRM, пустая строка (обычный чат)
chat.permissions Права в чате (manageUsersAdd, manageSettings и др.)
user Автор сообщения (id, name, departments, status и др.)
language Язык интерфейса пользователя

#Обработка голосовых и файловых сообщений

Голосовые сообщения и файлы-вложения попадают в ONIMBOTV2MESSAGEADD со следующими особенностями:

  • message.text часто пуст (голосовое без transcript) или содержит только пояснение ("Голосовое сообщение").
  • Массив message.params.FILE_ID — авторитативный источник информации о вложениях, появляется сразу в payload события.
  • GET /v1/chats/:dialogId/messages не гарантирует, что то же сообщение вернётся сразу — disk-индекс Bitrix24 иногда догоняет событие с задержкой в 1–2 секунды. Не ждите его через polling.

Корректный паттерн:

javascript 
const FILE_FETCH_TIMEOUT_MS = 10_000

async function handleMessageAdd(event) {
  const { message } = event.data
  const fileIds = message.params?.FILE_ID ?? []

  // Обычное текстовое сообщение — ничего особенного
  if (fileIds.length === 0) {
    return handleText(message)
  }

  // Есть вложение — читаем метаданные через disk API
  for (const fileId of fileIds) {
    let meta = null
    for (let attempt = 0; attempt < 2; attempt++) {
      // encodeURIComponent защищает от future-regressions если fileId когда-то
      // окажется не чисто-числовым (например, B24 поменяет формат ID или
      // этот паттерн расширят на user-provided ID из другого источника).
      const url = `https://vibecode.bitrix24.tech/v1/files/${encodeURIComponent(fileId)}`
      // AbortController защищает handler от зависания, если B24 или наш proxy
      // отвечают медленно. Без timeout одно «залипшее» событие может заблокировать poll-loop.
      const controller = new AbortController()
      const timer = setTimeout(() => controller.abort(), FILE_FETCH_TIMEOUT_MS)
      let res
      try {
        res = await fetch(url, {
          headers: { 'X-Api-Key': process.env.VIBE_KEY },
          signal: controller.signal,
        })
      } catch (err) {
        clearTimeout(timer)
        if (err.name === 'AbortError') {
          console.warn(`File ${fileId} fetch timed out after ${FILE_FETCH_TIMEOUT_MS}ms, retrying`)
          continue
        }
        throw err
      }
      clearTimeout(timer)
      if (res.ok) {
        meta = await res.json()
        break
      }
      // 403 BITRIX_ACCESS_DENIED или 404 сразу после события — типично:
      // disk ещё не проиндексировал файл. Ждём 1.5 секунды и ретраим.
      if (res.status === 403 || res.status === 404) {
        await sleep(1500)
        continue
      }
      throw new Error(`Failed to read file ${fileId}: HTTP ${res.status}`)
    }
    if (!meta) {
      // Файл всё ещё недоступен — логируем и продолжаем без attachment
      console.warn(`File ${fileId} not available after retry, skipping`)
      continue
    }
    await processAttachment(meta.data)
  }
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms))

Требуемые скоупы у API-ключа: imbot (получение событий) + disk (вызов /v1/files/:id). Скоуп disk часто забывают — без него GET /v1/files/:id возвращает SCOPE_DENIED 403. Скоуп im дополнительно нужен, если вы также вызываете native im.* методы (не требуется для этого паттерна).

Модель прав в Bitrix24:

  • Бот-пользователь (от чьего имени работает API-ключ) должен быть участником чата, в котором пришло сообщение. Для групповых ботов — обычно автоматически при установке. Для personal/supervisor ботов — требуется UI-настройка (см. create.md).
  • Файл-вложение должен быть в пределах retention-окна Bitrix24 (обычно 7–30 дней в зависимости от тарифа). Старые файлы физически удаляются и возвращают BITRIX_ACCESS_DENIED даже с правильным скоупом.
  • disk scope у ключа необходим, но недостаточен — он открывает эндпоинт /v1/files/:id, но права на конкретный файл B24 проверяет отдельно по chat membership.

Исторический контекст: этот паттерн формализован по результатам обращений VB-42EF198A (пустой text у голосовых), VB-5E3EFAEE (BITRIX_ACCESS_DENIED на /files/:id из бота) и VB-5BDB065A (запрос на документацию). До его появления боты зависали в бесконечных retry-циклах по chat messages API.

#ONIMBOTV2MESSAGEUPDATE

Сообщение отредактировано. Структура аналогична MESSAGEADD — message содержит обновлённый текст.

#ONIMBOTV2MESSAGEDELETE

Сообщение удалено. Вместо объекта message содержит messageId (число).

JSON 
{
  "eventId": 37,
  "type": "ONIMBOTV2MESSAGEDELETE",
  "date": "2026-04-13T17:16:00+03:00",
  "data": {
    "dialogId": "chat123",
    "bot": { "id": 42, "code": "support_bot", "type": "bot" },
    "messageId": 1501,
    "chat": { "id": 123, "dialogId": "chat123", "type": "chat", "name": "Рабочий чат" },
    "user": { "id": 1, "name": "Иван Петров" }
  }
}

#ONIMBOTV2JOINCHAT

Бот добавлен в чат. user — кто добавил бота.

JSON 
{
  "eventId": 29,
  "type": "ONIMBOTV2JOINCHAT",
  "date": "2026-04-13T17:12:00+03:00",
  "data": {
    "dialogId": "chat3553",
    "bot": { "id": 42, "code": "support_bot", "type": "bot", "eventMode": "fetch" },
    "chat": {
      "id": 3553,
      "dialogId": "chat3553",
      "type": "chat",
      "name": "Отдел продаж",
      "owner": 42,
      "color": "#64a513",
      "permissions": { "manageUsersAdd": "member", "manageSettings": "owner" }
    },
    "user": { "id": 3, "name": "Мария Сидорова", "workPosition": "Руководитель" },
    "language": "ru"
  }
}

#ONIMBOTV2COMMANDADD

Вызвана slash-команда бота. Содержит дополнительный объект command.

JSON 
{
  "eventId": 40,
  "type": "ONIMBOTV2COMMANDADD",
  "date": "2026-04-13T17:18:00+03:00",
  "data": {
    "dialogId": "chat123",
    "bot": { "id": 42, "code": "support_bot", "type": "bot" },
    "message": { "id": 1510, "text": "/help задачи" },
    "chat": { "id": 123, "dialogId": "chat123" },
    "user": { "id": 1, "name": "Иван Петров" },
    "command": {
      "id": 7,
      "command": "help",
      "params": "задачи",
      "context": "textarea"
    }
  }
}

Поля command:

Поле Описание
id ID команды
command Текст команды без /
params Параметры, введённые после команды
context Откуда вызвана: textarea (поле ввода), keyboard (кнопка), menu (контекстное меню)

Для ответа используйте POST /commands/:commandId/answer с messageId из message.id.

#ONIMBOTV2REACTIONCHANGE

Реакция добавлена или удалена на сообщение бота.

JSON 
{
  "eventId": 42,
  "type": "ONIMBOTV2REACTIONCHANGE",
  "date": "2026-04-13T17:19:00+03:00",
  "data": {
    "dialogId": "chat123",
    "bot": { "id": 42, "code": "support_bot", "type": "bot" },
    "reaction": "like",
    "action": "add",
    "message": { "id": 1502, "text": "Привет! Чем могу помочь?" },
    "chat": { "id": 123, "dialogId": "chat123" },
    "user": { "id": 1, "name": "Иван Петров" }
  }
}
Поле Описание
reaction Код реакции (см. коды реакций)
action "add" — добавлена, "delete" — удалена

#ONIMBOTV2DELETE

Бот удалён с портала. Содержит только объект bot — без chat и user.

JSON 
{
  "eventId": 50,
  "type": "ONIMBOTV2DELETE",
  "date": "2026-04-13T17:25:00+03:00",
  "data": {
    "bot": { "id": 42, "code": "support_bot", "type": "bot" }
  }
}

#ONIMBOTV2CONTEXTGET

Запрошен контекст диалога (например, из CRM-карточки). Содержит объект context.

JSON 
{
  "eventId": 45,
  "type": "ONIMBOTV2CONTEXTGET",
  "date": "2026-04-13T17:20:00+03:00",
  "data": {
    "dialogId": "chat789",
    "bot": { "id": 42, "code": "support_bot", "type": "bot" },
    "context": {
      "entityId": "DEAL_15",
      "entityType": "CRM",
      "source": "sidepanel"
    },
    "chat": { "id": 789, "dialogId": "chat789", "name": "Сделка: Поставка оборудования" },
    "user": { "id": 5, "name": "Алексей Козлов" }
  }
}
Поле Описание
context.entityId ID сущности (например, DEAL_15)
context.entityType Тип сущности (CRM и др.)
context.source Откуда открыт: sidepanel, chat и др.

#Общие объекты в событиях

Все события (кроме ONIMBOTV2DELETE) содержат объекты bot, chat, user с одинаковой структурой. Полные объекты показаны в примере ONIMBOTV2MESSAGEADD выше. В сокращённых примерах показаны только ключевые поля.

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