Event Formats im.v2
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
imWho can subscribe: an authorized user
This document describes all events that an application or a user receives via im.v2.Event.get.
Bitrix24 records events only after im.v2.Event.subscribe is called on behalf of the user, and delivers them only in polling mode — by calls to im.v2.Event.get. The subscription and polling procedure is described in the overview Working with Chat.
Each event is an element of the result.events array with the eventId, type, date, and data fields. The tables and examples below describe the contents of data; the other fields are described on the im.v2.Event.get page. The fields of the message, chat, and user objects are described in Chatbot Objects and Fields 2.0.
Quick navigation: All Events
Overview of Events
|
Event |
When it arrives |
|
A new message in a chat where the subscribed user is a member |
|
|
A message has been edited |
|
|
A message has been deleted |
|
|
A reaction to a message has been added or removed |
|
|
A new participant has been added to a chat |
Differences from Method Responses
In event data, the chat and user objects are shortened:
chat— without theroleandmuteListfields: they depend on the specific user and cannot be the same for all recipientsuser— without thenetwork,botData, andavatarHrfields, and the online status fieldsidle,lastActivityDate,mobileLastDate,desktopLastDateare alwaysfalse
There is no auth field in the event data. im.v2 events arrive in the im.v2.Event.get response rather than in the application handler, so authorization is passed in the request itself.
ONIMV2MESSAGEADD
A new message in a chat that the subscribed user is part of, including a message sent by the user.
|
Field |
Type |
Description |
|
message |
The sent message. Field descriptions for the object — Message |
|
|
chat |
The chat where the message was sent. Field descriptions for the object — Chat |
|
|
user |
The author of the message. Field descriptions for the object — User |
|
|
language |
|
The language of Bitrix24 (e.g., |
|
additionalMessages |
|
Array of |
Example Data
{
"message": {
"id": 5012,
"chatId": 5,
"authorId": 1,
"date": "2025-01-15T10:30:00+02: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
A message in the chat has been edited. If the message is updated with the im.message.update method, the event is not sent.
|
Field |
Type |
Description |
|
message |
The updated message. Field descriptions for the object — Message |
|
|
chat |
The chat where the message was edited. Field descriptions for the object — Chat |
|
|
user |
The author of the message. Field descriptions for the object — User |
|
|
language |
|
The language of Bitrix24 |
|
additionalMessages |
|
Array of |
The data has the same structure as in ONIMV2MESSAGEADD, except that message contains the message with the updated text.
ONIMV2MESSAGEDELETE
A message in the chat has been deleted.
|
Field |
Type |
Description |
|
messageId |
|
ID of the deleted message |
|
chat |
The chat where the message was deleted. Field descriptions for the object — Chat |
|
|
user |
The author of the message. Field descriptions for the object — User |
|
|
language |
|
The language of Bitrix24 |
Example Data
The chat and user objects here and in the examples below are shortened. The ONIMV2MESSAGEADD example shows the most fields; all fields are described on the Chatbot Objects and Fields 2.0 page.
{
"messageId": 5012,
"chat": {
"id": 5,
"dialogId": "chat5",
"name": "Project Chat",
"type": "chat"
},
"user": {
"id": 1,
"name": "John Smith",
"type": "user"
},
"language": "en"
}
ONIMV2REACTIONCHANGE
A reaction to a message in the chat has been added or removed.
|
Field |
Type |
Description |
|
reaction |
|
Reaction code (e.g., |
|
action |
|
Action with the reaction. In |
|
message |
The message to which a reaction was added or from which it was removed. Field descriptions for the object — Message |
|
|
chat |
The chat. Field descriptions for the object — Chat |
|
|
user |
The user who changed the reaction. Field descriptions for the object — User |
|
|
language |
|
The language of Bitrix24 |
|
additionalMessages |
|
Array of |
Example Data
{
"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
A new participant has been added to the chat.
|
Field |
Type |
Description |
|
dialogId |
|
Dialog ID. For a group chat — |
|
chat |
The chat to which the participant has been added. Field descriptions for the object — Chat |
|
|
user |
The added user. Field descriptions for the object — User |
|
|
language |
|
The language of Bitrix24 |
Example Data
{
"dialogId": "chat5",
"chat": {
"id": 5,
"dialogId": "chat5",
"name": "Project Chat",
"type": "chat"
},
"user": {
"id": 3,
"name": "Alex Brown",
"type": "user"
},
"language": "en"
}