Форматы событий imbot.v2

Описание всех событий, которые бот получает через imbot.v2.Event.get (FETCH-режим) или через webhook.

Поля объектов message, chat, user описаны в Объекты и поля чат-ботов 2.0.

Какие события обрабатывать в первую очередь

Минимальный набор событий для рабочего бота:

ONIMBOTV2MESSAGEADD — входящие сообщения от пользователя
ONIMBOTV2COMMANDADD — вызовы слэш-команд
ONIMBOTV2JOINCHAT — добавление бота в чат (обычно отправляют приветствие)
ONIMBOTV2DELETE — удаление бота (очистка ресурсов)

Дополнительно по сценарию:

ONIMBOTV2MESSAGEUPDATE и ONIMBOTV2MESSAGEDELETE — если поддерживаете редактирование/удаление
ONIMBOTV2REACTIONCHANGE — если учитываете реакции
ONIMBOTV2CONTEXTGET — если используете входной контекст диалога

Формат объекта bot

Содержимое поля bot зависит от режима доставки событий.

FETCH (imbot.v2.Event.get) — полный объект бота, как в ответе imbot.v2.Bot.get
Webhook — упрощенный объект {id, code, auth}, где auth содержит OAuth-токен для обратных вызовов

Каждый webhook-вызов содержит данные одного бота. Если приложение зарегистрировало несколько ботов и событие касается нескольких из них — webhook вызывается отдельно для каждого.

Пример объекта bot в webhook-режиме:

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "auth": {
                    "access_token": "0b02a0690000071b0008440001b0007a16b39202c2490f015",
                    "expires": "1772093963",
                    "expires_in": "3600",
                    "scope": "imbot",
                    "domain": "some-domain.bitrix24.ru",
                    "server_endpoint": "https://oauth.bitrix24.tech/rest/",
                    "status": "F",
                    "client_endpoint": "https://some-domain.bitrix24.ru/rest/",
                    "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                    "user_id": "27",
                    "application_token": "831c76b092f9f135d9b6b36c3a720757"
                }
            },
            "message": {},
            "chat": {},
            "user": {}
        }

Параметр auth

Обязательные параметры отмечены *

Название `тип`	Описание
access_token `string`	Токен авторизации OAuth 2.0
expires_in `integer`	Время в секундах до истечения срока действия токена
scope* `string`	Скоуп, в рамках которого произошло событие
domain* `string`	Адрес Битрикс24, на котором произошло событие
server_endpoint* `string`	Адрес сервера авторизации Битрикс24, необходимый для обновления токенов OAuth 2.0
status* `string`	Статус приложения, подписавшегося на это событие: `L` — локальное приложение `F` — бесплатное тиражное приложение `S` — подписное тиражное приложение
client_endpoint* `string`	Общий путь для вызовов методов REST API для Битрикс24, на котором произошло событие
member_id* `string`	Идентификатор Битрикс24, на котором произошло событие
refresh_token `string`	Токен продления авторизации OAuth 2.0
application_token* `string`	Токен для безопасной обработки событий

Токены авторизации не всегда передаются в обработчик события. Если хит, инициировавший событие, не удалось привязать к конкретному пользователю Битрикс24, токены не передаются. Обязательно проверяйте содержимое ключа auth в коде.

Рекомендуем хранить токены, полученные ранее при установке приложения. Используйте их при работе с интерфейсом приложения в виде встроек, виджетов и так далее.

Поле auth зависит от режима доставки событий:

в Webhook-режиме (bot отправляется на указанный обработчик) поле auth присутствует и содержит токены для авторизации обратных вызовов
в FETCH-режиме (imbot.v2.Event.get) поле auth в объекте bot не возвращается, так как токены не требуются

Типы данных в webhook-режиме

Webhook-события доставляются через систему событий Битрикс24, которая сериализует данные через http_build_query. Из-за этого все скалярные значения в webhook-режиме передаются как строки.

Тип	Значение в FETCH	Значение в Webhook
`integer`	`789`	`"789"`
`boolean`	`true` / `false`	`"1"` / `"0"`
`string\\|false`	`false`	`"0"`
`null`	`null`	`""`

При обработке webhook-событий рекомендуется приводить типы явно: (int)$data['messageId'], $data['user']['active'] !== '0'. В FETCH-режиме типы соответствуют документации.

ONIMBOTV2MESSAGEADD

Новое сообщение, адресованное боту. Возникает, когда пользователь отправляет сообщение в чат, в котором состоит бот.

Поле	Тип	Описание
bot	`object`	Объект бота
message	`Message`	Отправленное сообщение
chat	`Chat`	Чат, в котором отправлено сообщение
user	`User`	Автор сообщения
language	`string`	Язык портала (например, `en`, `ru`)

Пример данных

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "appId": "custom123abc",
                "eventMode": "fetch",
                "countMessage": 150,
                "countCommand": 3,
                "countChat": 12,
                "countUser": 45
            },
            "message": {
                "id": 789,
                "chatId": 5,
                "authorId": 1,
                "date": "2025-01-15T10:30:00+03:00",
                "text": "Hello bot!",
                "isSystem": false,
                "uuid": "",
                "forward": null,
                "params": {},
                "viewedByOthers": false
            },
            "chat": {
                "id": 5,
                "dialogId": "chat5",
                "type": "chat",
                "name": "Support Chat",
                "entityType": "",
                "owner": 1,
                "avatar": "",
                "color": "#ab7761"
            },
            "user": {
                "id": 1,
                "active": true,
                "name": "John Smith",
                "firstName": "John",
                "lastName": "Smith",
                "workPosition": "Developer",
                "color": "#df532d",
                "avatar": "",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "default",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T10:29:00+03:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2MESSAGEUPDATE

Сообщение в чате бота отредактировано.

Поле	Тип	Описание
bot	`object`	Объект бота
message	`Message`	Обновленное сообщение
chat	`Chat`	Чат, в котором отредактировано сообщение
user	`User`	Автор сообщения
language	`string`	Язык портала

Формат данных идентичен ONIMBOTV2MESSAGEADD. Поле message содержит обновленный текст.

ONIMBOTV2MESSAGEDELETE

Сообщение в чате бота удалено.

Поле	Тип	Описание
bot	`object`	Объект бота
messageId	`integer`	ID удаленного сообщения
chat	`Chat`	Чат, в котором удалено сообщение
user	`User`	Автор удаленного сообщения
language	`string`	Язык портала

ONIMBOTV2JOINCHAT

Бота добавили в чат или бот получил приглашение.

Поле	Тип	Описание
bot	`object`	Объект бота
dialogId	`string`	ID диалога (например, `chat5`)
chat	`Chat`	Чат, в который добавлен бот
user	`User`	Пользователь, добавивший бота
language	`string`	Язык портала

Пример данных

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "appId": "custom123abc",
                "eventMode": "fetch",
                "countMessage": 150,
                "countCommand": 3,
                "countChat": 12,
                "countUser": 45
            },
            "dialogId": "chat5",
            "chat": {
                "id": 5,
                "dialogId": "chat5",
                "type": "chat",
                "name": "Project Chat",
                "entityType": "",
                "owner": 1,
                "avatar": "",
                "color": "#ab7761"
            },
            "user": {
                "id": 1,
                "active": true,
                "name": "John Smith",
                "firstName": "John",
                "lastName": "Smith",
                "workPosition": "Developer",
                "color": "#df532d",
                "avatar": "",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "default",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T10:29:00+03:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2DELETE

Бот удален из системы. Это последнее событие, которое получит бот.

Поле	Тип	Описание
bot	`object`	Объект бота

Пример данных

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "appId": "custom123abc",
                "eventMode": "fetch",
                "countMessage": 150,
                "countCommand": 3,
                "countChat": 12,
                "countUser": 45
            }
        }

ONIMBOTV2CONTEXTGET

Пользователь открыл диалог с ботом, передав произвольные контекстные данные. Контекст задается вызывающей стороной — например, при переходе по ссылке с параметром botContextData.

Поле	Тип	Описание
bot	`object`	Объект бота
dialogId	`string`	ID диалога (например, `chat5`)
context	`object`	Произвольные данные, переданные при открытии диалога
chat	`Chat`	Чат
user	`User`	Пользователь, открывший диалог
language	`string`	Язык портала

Пример данных

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "appId": "custom123abc",
                "eventMode": "fetch",
                "countMessage": 150,
                "countCommand": 3,
                "countChat": 12,
                "countUser": 45
            },
            "dialogId": "chat5",
            "context": {
                "entityId": 164,
                "entityType": "task",
                "source": "link"
            },
            "chat": {
                "id": 5,
                "dialogId": "chat5",
                "type": "chat",
                "name": "Support Chat",
                "entityType": "",
                "owner": 1,
                "avatar": "",
                "color": "#ab7761"
            },
            "user": {
                "id": 1,
                "active": true,
                "name": "John Smith",
                "firstName": "John",
                "lastName": "Smith",
                "workPosition": "Developer",
                "color": "#df532d",
                "avatar": "",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "default",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T10:29:00+03:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2COMMANDADD

Пользователь вызвал слэш-команду бота.

Поле	Тип	Описание
bot	`object`	Объект бота
command	`object`	Данные команды. Описание полей — ниже
message	`Message`	Сообщение с командой
chat	`Chat`	Чат, из которого вызвана команда
user	`User`	Пользователь, вызвавший команду
language	`string`	Язык портала

Объект command

Поле	Тип	Описание
id	`integer`	ID зарегистрированной команды
command	`string`	Вызванная команда (например, `/help`)
params	`string`	Параметры команды — текст после команды
context	`string`	Контекст вызова: `textarea` — введена вручную, `keyboard` — нажата кнопка клавиатуры, `menu` — выбрана из контекстного меню

Если одно сообщение содержит несколько слэш-команд, событие генерируется отдельно для каждой команды.

Пример данных

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "appId": "custom123abc",
                "eventMode": "fetch",
                "countMessage": 150,
                "countCommand": 3,
                "countChat": 12,
                "countUser": 45
            },
            "command": {
                "id": 78,
                "command": "/help",
                "params": "topic",
                "context": "textarea"
            },
            "message": {
                "id": 790,
                "chatId": 5,
                "authorId": 1,
                "date": "2025-01-15T10:30:00+03:00",
                "text": "/help topic",
                "isSystem": false,
                "uuid": "",
                "forward": null,
                "params": {},
                "viewedByOthers": false
            },
            "chat": {
                "id": 5,
                "dialogId": "chat5",
                "type": "chat",
                "name": "Support Chat",
                "entityType": "",
                "owner": 1,
                "avatar": "",
                "color": "#ab7761"
            },
            "user": {
                "id": 1,
                "active": true,
                "name": "John Smith",
                "firstName": "John",
                "lastName": "Smith",
                "workPosition": "Developer",
                "color": "#df532d",
                "avatar": "",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "default",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T10:29:00+03:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2REACTIONCHANGE

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

Поле	Тип	Описание
bot	`object`	Объект бота
reaction	`string`	Код реакции (например, `like`). Список кодов — в imbot.v2.Chat.Message.Reaction.add
action	`string`	Действие: `add` — реакция добавлена, `delete` — удалена
message	`Message`	Сообщение, на которое поставлена реакция
chat	`Chat`	Чат
user	`User`	Пользователь, изменивший реакцию
language	`string`	Язык портала

Пример данных

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "appId": "custom123abc",
                "eventMode": "fetch",
                "countMessage": 150,
                "countCommand": 3,
                "countChat": 12,
                "countUser": 45
            },
            "reaction": "like",
            "action": "add",
            "message": {
                "id": 789,
                "chatId": 5,
                "authorId": 456,
                "date": "2025-01-15T10:30:00+03:00",
                "text": "Hello! How can I help?",
                "isSystem": false,
                "uuid": "",
                "forward": null,
                "params": {},
                "viewedByOthers": true
            },
            "chat": {
                "id": 5,
                "dialogId": "chat5",
                "type": "chat",
                "name": "Support Chat",
                "entityType": "",
                "owner": 1,
                "avatar": "",
                "color": "#ab7761"
            },
            "user": {
                "id": 1,
                "active": true,
                "name": "John Smith",
                "firstName": "John",
                "lastName": "Smith",
                "workPosition": "Developer",
                "color": "#df532d",
                "avatar": "",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "default",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T10:29:00+03:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

Продолжите изучение

Получить события бота

Обзор методов

Форматы событий imbot.v2

Какие события обрабатывать в первую очередьКакие события обрабатывать в первую очередь

Формат объекта botФормат объекта bot

Параметр authПараметр auth

Типы данных в webhook-режимеТипы данных в webhook-режиме

ONIMBOTV2MESSAGEADDONIMBOTV2MESSAGEADD

Пример данныхПример данных

ONIMBOTV2MESSAGEUPDATEONIMBOTV2MESSAGEUPDATE

ONIMBOTV2MESSAGEDELETEONIMBOTV2MESSAGEDELETE

ONIMBOTV2JOINCHATONIMBOTV2JOINCHAT

Пример данныхПример данных

ONIMBOTV2DELETEONIMBOTV2DELETE

Пример данныхПример данных

ONIMBOTV2CONTEXTGETONIMBOTV2CONTEXTGET

Пример данныхПример данных

ONIMBOTV2COMMANDADDONIMBOTV2COMMANDADD

Объект commandОбъект command

Пример данныхПример данных

ONIMBOTV2REACTIONCHANGEONIMBOTV2REACTIONCHANGE

Пример данныхПример данных

Продолжите изучениеПродолжите изучение

Какие события обрабатывать в первую очередь

Формат объекта bot

Параметр auth

Типы данных в webhook-режиме

ONIMBOTV2MESSAGEADD

Пример данных

ONIMBOTV2MESSAGEUPDATE

ONIMBOTV2MESSAGEDELETE

ONIMBOTV2JOINCHAT

Пример данных

ONIMBOTV2DELETE

Пример данных

ONIMBOTV2CONTEXTGET

Пример данных

ONIMBOTV2COMMANDADD

Объект command

Пример данных

ONIMBOTV2REACTIONCHANGE

Пример данных

Продолжите изучение