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

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: im

Кто может подписаться: авторизованный пользователь

Описание всех событий, которые приложение или пользователь получает через im.v2.Event.get.

Битрикс24 записывает события только после вызова im.v2.Event.subscribe от имени пользователя, а доставляет их только в режиме polling — вызовами im.v2.Event.get. Порядок подписки и опроса описан в обзоре Работа с чатом.

Каждое событие — элемент массива result.events с полями eventId, type, date и data. Таблицы и примеры ниже описывают содержимое data, остальные поля — на странице im.v2.Event.get. Поля объектов message, chat, user описаны в Объекты и поля чат-ботов 2.0.

Быстрый переход: все события

Обзор событий

Событие	Когда приходит
ONIMV2MESSAGEADD	Новое сообщение в чате, где состоит подписанный пользователь
ONIMV2MESSAGEUPDATE	Сообщение отредактировано
ONIMV2MESSAGEDELETE	Сообщение удалено
ONIMV2REACTIONCHANGE	Реакция на сообщение добавлена или удалена
ONIMV2JOINCHAT	В чат добавлен новый участник

Отличия от ответов методов

В данных событий объекты chat и user приходят сокращенными:

chat — без полей role и muteList: они зависят от конкретного пользователя и не могут быть одинаковыми для всех получателей
user — без полей network, botData, avatarHr, а поля онлайн-статуса idle, lastActivityDate, mobileLastDate, desktopLastDate всегда равны false

В данных события нет поля auth. События im.v2 приходят в ответе im.v2.Event.get, а не в обработчик приложения, поэтому авторизация передается в самом запросе.

ONIMV2MESSAGEADD

Новое сообщение в чате, в котором состоит подписанный пользователь, в том числе отправленное им самим.

Поле	Тип	Описание
message	`Message`	Отправленное сообщение. Описание полей объекта — Message
chat	`Chat`	Чат, в котором отправлено сообщение. Описание полей объекта — Chat
user	`User`	Автор сообщения. Описание полей объекта — User
language	`string`	Язык Битрикс24 (например, `en`, `ru`)
additionalMessages	`array`	Массив объектов `Message`. Если `message` — ответ на другое сообщение, в массиве — исходное сообщение, иначе массив пустой. Если исходное сообщение удалено, оно придет с текстом об удалении

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

{
    "message": {
        "id": 5012,
        "chatId": 5,
        "authorId": 1,
        "date": "2025-01-15T10:30:00+03:00",
        "text": "Hello everyone!",
        "isSystem": false,
        "uuid": null,
        "forward": null,
        "params": [],
        "viewedByOthers": false
    },
    "chat": {
        "id": 5,
        "dialogId": "chat5",
        "name": "Project Chat",
        "type": "chat",
        "messageType": "C",
        "owner": 1,
        "color": "#ab7761",
        "avatar": "",
        "description": "",
        "extranet": false,
        "containsCollaber": false,
        "entityType": "",
        "entityId": "",
        "entityData1": "",
        "entityData2": "",
        "entityData3": "",
        "entityLink": {
            "type": "",
            "url": "",
            "id": ""
        },
        "diskFolderId": 42,
        "permissions": {
            "manageUsersAdd": "member",
            "manageUsersDelete": "manager",
            "manageUi": "member",
            "manageSettings": "owner",
            "manageMessages": "member",
            "manageMessagesAutoDelete": "manager",
            "manageGuestInvites": "manager",
            "manageDelete": "member",
            "canPost": "member"
        },
        "parentChatId": 0,
        "parentMessageId": 0,
        "isNew": false,
        "textFieldEnabled": true,
        "backgroundId": null
    },
    "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": false,
        "mobileLastDate": false,
        "desktopLastDate": false,
        "absent": false,
        "departments": [1],
        "phones": false,
        "website": "",
        "email": "john@example.com",
        "type": "user"
    },
    "language": "en",
    "additionalMessages": []
}

ONIMV2MESSAGEUPDATE

Сообщение в чате отредактировано. Если сообщение изменено методом im.message.update, событие не приходит.

Поле	Тип	Описание
message	`Message`	Обновленное сообщение. Описание полей объекта — Message
chat	`Chat`	Чат, в котором отредактировано сообщение. Описание полей объекта — Chat
user	`User`	Автор сообщения. Описание полей объекта — User
language	`string`	Язык Битрикс24
additionalMessages	`array`	Массив объектов `Message`. Если `message` — ответ на другое сообщение, в массиве — исходное сообщение, иначе массив пустой. Если исходное сообщение удалено, оно придет с текстом об удалении

Данные устроены так же, как у ONIMV2MESSAGEADD, только в message — сообщение с обновленным текстом.

ONIMV2MESSAGEDELETE

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

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

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

Объекты chat и user здесь и в примерах ниже сокращены. Больше всего полей показано в примере ONIMV2MESSAGEADD, описание всех полей — на странице Объекты и поля чат-ботов 2.0.

{
    "messageId": 5012,
    "chat": {
        "id": 5,
        "dialogId": "chat5",
        "name": "Project Chat",
        "type": "chat"
    },
    "user": {
        "id": 1,
        "name": "John Smith",
        "type": "user"
    },
    "language": "en"
}

ONIMV2REACTIONCHANGE

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

Поле	Тип	Описание
reaction	`string`	Код реакции (например, `like`)
action	`string`	Действие с реакцией. В событиях `im.v2` приходит пустой строкой и при добавлении, и при удалении реакции: по этому полю их не различить
message	`Message`	Сообщение, реакция на которое добавлена или удалена. Описание полей объекта — Message
chat	`Chat`	Чат. Описание полей объекта — Chat
user	`User`	Пользователь, изменивший реакцию. Описание полей объекта — User
language	`string`	Язык Битрикс24
additionalMessages	`array`	Массив объектов `Message`. Если `message` — ответ на другое сообщение, в массиве — исходное сообщение, иначе массив пустой. Если исходное сообщение удалено, оно придет с текстом об удалении

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

{
    "reaction": "like",
    "action": "",
    "message": {
        "id": 5012,
        "chatId": 5,
        "authorId": 1,
        "date": "2025-01-15T10:30:00+03:00",
        "text": "Hello everyone!",
        "isSystem": false,
        "uuid": null,
        "forward": null,
        "params": [],
        "viewedByOthers": false
    },
    "chat": {
        "id": 5,
        "dialogId": "chat5",
        "name": "Project Chat",
        "type": "chat"
    },
    "user": {
        "id": 2,
        "name": "Jane Doe",
        "type": "user"
    },
    "language": "en",
    "additionalMessages": []
}

ONIMV2JOINCHAT

Новый участник добавлен в чат.

Поле	Тип	Описание
dialogId	`string`	ID диалога. Для группового чата — `chat` и ID чата, например `chat5`. Для личного — ID собеседника
chat	`Chat`	Чат, в который добавлен участник. Описание полей объекта — Chat
user	`User`	Добавленный пользователь. Описание полей объекта — User
language	`string`	Язык Битрикс24

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

{
    "dialogId": "chat5",
    "chat": {
        "id": 5,
        "dialogId": "chat5",
        "name": "Project Chat",
        "type": "chat"
    },
    "user": {
        "id": 3,
        "name": "Alex Brown",
        "type": "user"
    },
    "language": "en"
}

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

Была ли статья полезна?

Получить события пользователя

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

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

Обзор событийОбзор событий

Отличия от ответов методовОтличия от ответов методов

ONIMV2MESSAGEADDONIMV2MESSAGEADD

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

ONIMV2MESSAGEUPDATEONIMV2MESSAGEUPDATE

ONIMV2MESSAGEDELETEONIMV2MESSAGEDELETE

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

ONIMV2REACTIONCHANGEONIMV2REACTIONCHANGE

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

ONIMV2JOINCHATONIMV2JOINCHAT

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

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

Была ли статья полезна?

Обзор событий

Отличия от ответов методов

ONIMV2MESSAGEADD

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

ONIMV2MESSAGEUPDATE

ONIMV2MESSAGEDELETE

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

ONIMV2REACTIONCHANGE

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

ONIMV2JOINCHAT

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

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