Event Formats for imbot.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.

Description of all events that the bot receives via imbot.v2.Event.get (FETCH mode) or through webhook.

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

Which Events to Process First

The minimum set of events for a working bot:

ONIMBOTV2MESSAGEADD — incoming messages from users
ONIMBOTV2COMMANDADD — calls to slash commands
ONIMBOTV2JOINCHAT — adding the bot to a chat (usually sends a greeting)
ONIMBOTV2DELETE — removal of the bot (resource cleanup)

Additionally, based on the scenario:

ONIMBOTV2MESSAGEUPDATE and ONIMBOTV2MESSAGEDELETE — if you support editing/deleting
ONIMBOTV2REACTIONCHANGE — if you track reactions
ONIMBOTV2CONTEXTGET — if you use the incoming context of the dialogue

Bot Object Format

The content of the bot field depends on the event delivery mode.

FETCH (imbot.v2.Event.get) — full bot object, as in the response from imbot.v2.Bot.get
Webhook — simplified object {id, code, auth}, where auth contains the OAuth token for callbacks

Each webhook call contains data for one bot. If the application has registered multiple bots and the event concerns several of them, the webhook is called separately for each.

Example of the bot object in webhook mode:

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

Auth Parameter

Required parameters are marked with *

Name `type`	Description
access_token `string`	Authorization token OAuth 2.0
expires_in `integer`	Time in seconds until the token expires
scope* `string`	Scope under which the event occurred
domain* `string`	Address of Bitrix24 where the event occurred
server_endpoint* `string`	Address of the Bitrix24 authorization server needed to refresh OAuth 2.0 tokens
status* `string`	Status of the application that subscribed to this event: `L` — local application `F` — free mass-market application
client_endpoint* `string`	Common path for REST API method calls for Bitrix24 where the event occurred
member_id* `string`	Identifier of Bitrix24 where the event occurred
refresh_token `string`	Token for extending authorization OAuth 2.0
application_token* `string`	Token for secure event handling

Authorization tokens are not always passed to the event handler. If the hit that initiated the event could not be linked to a specific Bitrix24 user, the tokens are not passed. Always check the contents of the auth key in the code.

It is recommended to store tokens obtained earlier during the application installation. Use them when working with the application interface in the form of embeds, widgets, and so on.

The auth field depends on the event delivery mode:

in Webhook mode (bot is sent to the specified handler), the auth field is present and contains tokens for callback authorization
in FETCH mode (imbot.v2.Event.get), the auth field in the bot object is not returned, as tokens are not required

Data Types in Webhook Mode

Webhook events are delivered through the Bitrix24 event system, which serializes data via http_build_query. Because of this, all scalar values in webhook mode are transmitted as strings.

Type	Value in FETCH	Value in Webhook
`integer`	`789`	`"789"`
`boolean`	`true` / `false`	`"1"` / `"0"`
`string	false`	`false`	`"0"`
`null`	`null`	`""`

When processing webhook events, it is recommended to cast types explicitly: (int)$data['messageId'], $data['user']['active'] !== '0'. In FETCH mode, types correspond to the documentation.

ONIMBOTV2MESSAGEADD

A new message addressed to the bot. This occurs when a user sends a message in a chat that the bot is part of.

Field	Type	Description
bot	`object`	Bot object
message	`Message`	The sent message
chat	`Chat`	The chat in which the message was sent
user	`User`	The author of the message
language	`string`	Portal language (e.g., `en`, `ru`)

Example Data

{
            "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+02: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+02:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2MESSAGEUPDATE

A message in the bot's chat has been edited.

Field	Type	Description
bot	`object`	Bot object
message	`Message`	The updated message
chat	`Chat`	The chat in which the message was edited
user	`User`	The author of the message
language	`string`	Portal language

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

ONIMBOTV2MESSAGEDELETE

A message in the bot's chat has been deleted.

Field	Type	Description
bot	`object`	Bot object
messageId	`integer`	ID of the deleted message
chat	`Chat`	The chat in which the message was deleted
user	`User`	The author of the deleted message
language	`string`	Portal language

ONIMBOTV2JOINCHAT

The bot has been added to a chat or received an invitation.

Field	Type	Description
bot	`object`	Bot object
dialogId	`string`	ID of the dialog (e.g., `chat5`)
chat	`Chat`	The chat to which the bot was added
user	`User`	The user who added the bot
language	`string`	Portal language

Example Data

{
            "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+02:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2DELETE

The bot has been removed from the system. This is the last event the bot will receive.

Field	Type	Description
bot	`object`	Bot object

Example Data

{
            "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

The user opened a dialogue with the bot, passing arbitrary context data. The context is set by the calling party — for example, when following a link with the botContextData parameter.

Field	Type	Description
bot	`object`	Bot object
dialogId	`string`	ID of the dialog (e.g., `chat5`)
context	`object`	Arbitrary data passed when opening the dialog
chat	`Chat`	The chat
user	`User`	The user who opened the dialog
language	`string`	Portal language

Example Data

{
            "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+02:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2COMMANDADD

The user invoked a slash command of the bot.

Field	Type	Description
bot	`object`	Bot object
command	`object`	Command data. Field descriptions — below
message	`Message`	The message with the command
chat	`Chat`	The chat from which the command was invoked
user	`User`	The user who invoked the command
language	`string`	Portal language

Command Object

Field	Type	Description
id	`integer`	ID of the registered command
command	`string`	Invoked command (e.g., `/help`)
params	`string`	Command parameters — text after the command
context	`string`	Invocation context: `textarea` — entered manually, `keyboard` — button pressed, `menu` — selected from context menu

If a single message contains multiple slash commands, an event is generated separately for each command.

Example Data

{
            "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+02: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+02:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

ONIMBOTV2REACTIONCHANGE

A reaction to the bot's message has been added or removed.

Field	Type	Description
bot	`object`	Bot object
reaction	`string`	Reaction code (e.g., `like`). A list of codes can be found in imbot.v2.Chat.Message.Reaction.add
action	`string`	Action: `add` — reaction added, `delete` — removed
message	`Message`	The message to which the reaction was added
chat	`Chat`	The chat
user	`User`	The user who changed the reaction
language	`string`	Portal language

Example Data

{
            "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+02: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+02:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "employee"
            },
            "language": "en"
        }

Continue Learning

Retrieve Bot Events

Overview of Methods

Event Formats for imbot.v2

Which Events to Process FirstWhich Events to Process First

Bot Object FormatBot Object Format

Auth ParameterAuth Parameter

Data Types in Webhook ModeData Types in Webhook Mode

ONIMBOTV2MESSAGEADDONIMBOTV2MESSAGEADD

Example DataExample Data

ONIMBOTV2MESSAGEUPDATEONIMBOTV2MESSAGEUPDATE

ONIMBOTV2MESSAGEDELETEONIMBOTV2MESSAGEDELETE

ONIMBOTV2JOINCHATONIMBOTV2JOINCHAT

Example DataExample Data

ONIMBOTV2DELETEONIMBOTV2DELETE

Example DataExample Data

ONIMBOTV2CONTEXTGETONIMBOTV2CONTEXTGET

Example DataExample Data

ONIMBOTV2COMMANDADDONIMBOTV2COMMANDADD

Command ObjectCommand Object

Example DataExample Data

ONIMBOTV2REACTIONCHANGEONIMBOTV2REACTIONCHANGE

Example DataExample Data

Continue LearningContinue Learning

Which Events to Process First

Bot Object Format

Auth Parameter

Data Types in Webhook Mode

ONIMBOTV2MESSAGEADD

Example Data

ONIMBOTV2MESSAGEUPDATE

ONIMBOTV2MESSAGEDELETE

ONIMBOTV2JOINCHAT

Example Data

ONIMBOTV2DELETE

Example Data

ONIMBOTV2CONTEXTGET

Example Data

ONIMBOTV2COMMANDADD

Command Object

Example Data

ONIMBOTV2REACTIONCHANGE

Example Data

Continue Learning