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.

This document describes all events that the bot receives through imbot.v2.Event.get (FETCH mode) or via webhook.

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

Automatic Subscription Management

The bot's subscription to events ONIMBOTV2* is automatically created when imbot.v2.Bot.register is called with eventMode: "webhook", updated when imbot.v2.Bot.update is called (when webhookUrl or eventMode changes), and removed when imbot.v2.Bot.unregister is called or when switching to fetch mode. Manual calls to event.bind / event.unbind are not required and may lead to discrepancies with internal accounting.

Which Events to Handle First

The minimum set of events for a working bot:

ONIMBOTV2MESSAGEADD — incoming messages from users
ONIMBOTV2COMMANDADD — calls to slash commands
ONIMBOTV2JOINCHAT — the bot being added to a chat (usually sends a greeting)
ONIMBOTV2DELETE — the bot being removed (cleaning up resources)

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.bitrix.info/rest/",
                    "status": "F",
                    "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                    "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                    "user_id": "27",
                    "application_token": "831c76b092f9f135d9b6b36c3a720757"
                }
            },
            "message": {},
            "chat": {},
            "user": {}
        }

Webhook Notification Structure

In webhook mode, the POST request contains two different auth:

top-level auth — the entire request's conversion, always present;
data.bot.auth — OAuth tokens for the specific bot for callbacks.

{
            "event": "ONIMBOTV2MESSAGEADD",
            "data": {
                "bot": {
                    "id": 456,
                    "code": "support_bot",
                    "auth": {"access_token": "...", "refresh_token": "...", "application_token": "..."}
                },
                "message": {},
                "chat": {},
                "user": {}
            },
            "ts": 1772093963,
            "auth": {
                "domain": "your-account.bitrix24.com",
                "application_token": "..."
            }
        }

To verify the authenticity of the webhook, use the application_token from the top level — auth.application_token, not from data.bot.auth.application_token.

The request arrives as application/x-www-form-urlencoded via http_build_query, so the keys have PHP format: data[bot][id]=..., auth[application_token]=....

Chat Object in Events

The chat object in events does not contain the fields role and muteList — these fields depend on the specific user and cannot be the same for all event recipients.

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 (the bot is sent to the specified handler), the auth field is present and contains tokens for authorizing callbacks.
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 where the message was sent
user	`User`	The author of the message
language	`string`	Bitrix24 language (e.g., `en`, `de`)

Example Data

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "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 where the message was edited
user	`User`	The author of the message
language	`string`	Bitrix24 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 where the message was deleted
user	`User`	The author of the deleted message
language	`string`	Bitrix24 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`	Bitrix24 language

Example Data

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "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",
                "eventMode": "fetch",
                "countMessage": 150,
                "countCommand": 3,
                "countChat": 12,
                "countUser": 45
            }
        }

ONIMBOTV2CONTEXTGET

The user has opened a dialogue with the bot, passing arbitrary context data. The context is set by the calling party — for example, when navigating via 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`	Bitrix24 language

Example Data

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "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 has invoked a slash command for 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`	Bitrix24 language

Command Object

Field	Type	Description
id	`integer`	ID of the registered command
command	`string`	The invoked command (e.g., `/help`)
params	`string`	Command parameters — text following 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",
                "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`). The list of codes is 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`	Bitrix24 language

Example Data

{
            "bot": {
                "id": 456,
                "code": "support_bot",
                "type": "bot",
                "isHidden": false,
                "isSupportOpenline": false,
                "isReactionsEnabled": true,
                "backgroundId": null,
                "language": "en",
                "moduleId": "rest",
                "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

Automatic Subscription ManagementAutomatic Subscription Management

Which Events to Handle FirstWhich Events to Handle First

Bot Object FormatBot Object Format

Webhook Notification StructureWebhook Notification Structure

Chat Object in EventsChat Object in Events

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

Automatic Subscription Management

Which Events to Handle First

Bot Object Format

Webhook Notification Structure

Chat Object in Events

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