Skip to content

index.md

Latest commit

 

History

History
100 lines (67 loc) · 5.16 KB

index.md

File metadata and controls

100 lines (67 loc) · 5.16 KB
Raw

Events: Overview of Methods

{% note tip "" %}

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.

{% endnote %}

The bot can operate in fetch mode, where it retrieves events through polling requests, or in webhook mode, where Bitrix24 sends events to the bot's URL.

Quick navigation: all methods and events

Event Delivery Modes {#event-modes}

#| || Mode | Description | When to use || || fetch | The bot receives events via imbot.v2.Event.get | For AI agents, server-side bots, and integrations without a persistent HTTP server || || webhook | Bitrix24 sends events to the bot's URL via HTTP POST | For bots with a persistent HTTP server || |#

The mode is set during bot registration with the eventMode parameter of the imbot.v2.Bot.register method.

The data format depends on the mode. In fetch mode, the full bot object arrives; in webhook mode, a simplified object {id, code, auth}. In webhook mode, all scalar values arrive as strings, so the types have to be cast explicitly. More details — Format of the bot Object.

Event Subscription {#subscription}

Subscriptions to ONIMBOTV2* events are managed by the platform itself:

{% note warning "" %}

There is no need to call event.bind and event.unbind manually — doing so may lead to a mismatch with the internal subscription records.

{% endnote %}

Limits {#limits}

#| || Limit | Value || || Events per single imbot.v2.Event.get call | 1–1000, 100 by default || || Recommended polling interval in fetch mode | 5–30 seconds when there are no new events || || Delivery in webhook mode | The platform expects HTTP 200. Retries on failure are not guaranteed || |#

An example of a polling cycle and a webhook handler is available in Chatbots 2.0: Overview of Methods.

Relationship with Other Objects {#relations}

Bot. Events are delivered to a specific bot, so botId is passed to imbot.v2.Event.get, and for webhook authorization, botToken as well — Bots.

Messages. The ONIMBOTV2MESSAGE* and ONIMBOTV2REACTIONCHANGE events are the main incoming flow for the bot. Responses to them are sent by the methods of the Messages group.

Commands. A slash command call arrives as the ONIMBOTV2COMMANDADD event, and the response is sent by the imbot.v2.Command.answer method — Commands.

Bot context. The ONIMBOTV2CONTEXTGET event delivers to the bot the arbitrary data passed when the chat was opened — Passing Context to a Bot.

User events. If you need to read the messenger event flow on behalf of a user rather than a bot, use the im.v2.Event.* methods.

Overview of Methods and Events {#all-methods}

Scope: imbot

Who can execute the methods: owner of the registered bot

Methods

#| || Method | Description || || imbot.v2.Event.get | Returns bot events in polling mode || || Event Formats | Description of events and data structures || |#

Events

The minimum set for a working bot is ONIMBOTV2MESSAGEADD, ONIMBOTV2COMMANDADD, ONIMBOTV2JOINCHAT, and ONIMBOTV2DELETE. Connect the remaining events as your scenario requires.

#| || Event | Triggered || || ONIMBOTV2MESSAGEADD | When a user sends a message to a chat the bot belongs to || || ONIMBOTV2MESSAGEUPDATE | When a message is edited in the bot's chat || || ONIMBOTV2MESSAGEDELETE | When a message is deleted in the bot's chat || || ONIMBOTV2REACTIONCHANGE | When a reaction to the bot's message is added or removed || || ONIMBOTV2COMMANDADD | When a user calls a slash command of the bot || || ONIMBOTV2JOINCHAT | When the bot is added to a chat or invited to one || || ONIMBOTV2CONTEXTGET | When a dialog with the bot is opened, if context data is passed || || ONIMBOTV2DELETE | When the bot is deleted from the system. The last event the bot receives || |#

Continue Your Exploration