Event Formats im.v2

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

This document describes all events that a user application receives via im.v2.Event.get.

The fields of the message, chat, and user objects are described in Chatbot Objects and Fields 2.0.

Quick Navigation: ONIMV2MESSAGEADD | ONIMV2MESSAGEUPDATE | ONIMV2MESSAGEDELETE | ONIMV2REACTIONCHANGE | ONIMV2JOINCHAT

Differences from Method Responses

In these events, the chat and user objects are returned in a simplified format:

the chat object does not contain the role and muteList fields — these depend on the specific user and cannot be the same for all recipients
the user object does not contain the network, botData, and avatarHr fields
the online status fields (idle, lastActivityDate, mobileLastDate, desktopLastDate) are always set to false

This article describes the event format of the im.v2.Event.get method (polling/FETCH), so the auth field in the event data is not returned.

If using a webhook subscription for events, the webhook wrapper may contain an auth object with tokens.

ONIMV2MESSAGEADD

A new message in the chat that the subscribed user is part of.

Field	Type	Description
message	`Message`	The sent message. Field descriptions for the object — Message
chat	`Chat`	The chat where the message was sent. Field descriptions for the object — Chat
user	`User`	The author of the message. Field descriptions for the object — User
language	`string`	The language of Bitrix24 (e.g., `en`, `de`)

Example Data

{
            "message": {
                "id": 5012,
                "chatId": 5,
                "authorId": 1,
                "date": "2025-01-15T10:30:00+02:00",
                "text": "Hello everyone!",
                "isSystem": false,
                "uuid": "",
                "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": {},
                "diskFolderId": 42,
                "permissions": {},
                "parentChatId": 0,
                "parentMessageId": 0,
                "isNew": false,
                "textFieldEnabled": "Y",
                "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": "employee"
            },
            "language": "en"
        }

ONIMV2MESSAGEUPDATE

A message in the chat has been edited.

Field	Type	Description
message	`Message`	The updated message. Field descriptions for the object — Message
chat	`Chat`	The chat where the message was edited. Field descriptions for the object — Chat
user	`User`	The author of the message. Field descriptions for the object — User
language	`string`	The language of Bitrix24

The data format is identical to ONIMV2MESSAGEADD. The message field contains the updated text.

ONIMV2MESSAGEDELETE

A message in the chat has been deleted.

Field	Type	Description
messageId	`integer`	ID of the deleted message
chat	`Chat`	The chat where the message was deleted. Field descriptions for the object — Chat
user	`User`	The author of the message. Field descriptions for the object — User
language	`string`	The language of Bitrix24

ONIMV2REACTIONCHANGE

A reaction to a message in the chat has been added or removed.

Field	Type	Description
reaction	`string`	Reaction code (e.g., `like`)
action	`string`	Action: `add` — reaction added, `delete` — removed
message	`Message`	The message to which the reaction has changed. Field descriptions for the object — Message
chat	`Chat`	The chat. Field descriptions for the object — Chat
user	`User`	The user who changed the reaction. Field descriptions for the object — User
language	`string`	The language of Bitrix24

ONIMV2JOINCHAT

A new participant has been added to the chat.

Field	Type	Description
dialogId	`string`	ID of the dialog (e.g., `chat5`)
chat	`Chat`	The chat to which the participant has been added. Field descriptions for the object — Chat
user	`User`	The added user. Field descriptions for the object — User
language	`string`	The language of Bitrix24

Continue Learning

Retrieve User Events

Overview of Methods

Event Formats im.v2

Differences from Method ResponsesDifferences from Method Responses

ONIMV2MESSAGEADDONIMV2MESSAGEADD

Example DataExample Data

ONIMV2MESSAGEUPDATEONIMV2MESSAGEUPDATE

ONIMV2MESSAGEDELETEONIMV2MESSAGEDELETE

ONIMV2REACTIONCHANGEONIMV2REACTIONCHANGE

ONIMV2JOINCHATONIMV2JOINCHAT

Continue LearningContinue Learning