Events: Overview of Methods
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.
The methods subscribe the user to messenger events and return them in polling mode. Use them if the integration needs to read the stream of events on behalf of the user or application.
Quick navigation: all methods and events
How to Work with Events
- Enable event recording via im.v2.Event.subscribe. The method is idempotent: a repeated call is safe.
- Retrieve accumulated events through im.v2.Event.get.
- Pass
offsetto confirm already processed records. Take the value from thenextOffsetfield of the previous response. - Terminate the subscription using the im.v2.Event.unsubscribe method.
What is polling mode
Polling is a mode of receiving events where the application periodically requests accumulated events from the server. The server does not know the application's address and does not send anything on its own—it only accumulates a queue and delivers it upon request.
This distinguishes polling from webhook: in webhook mode, Bitrix24 calls the application's URL with each new event. Polling is convenient if the application does not have a permanent HTTP server or public URL.
Without a subscription, events are not recorded, and im.v2.Event.get returns an empty events array. After unsubscribing, the already accumulated events remain available until the storage period expires or until they are confirmed with offset.
Limits and Restrictions
|
Limit |
Value |
|
Events per single |
1–1000, 100 by default |
|
Storage period of recorded events |
24 hours |
|
Delivery method |
Polling only. Webhook mode is not supported for user events |
|
Number of recipients |
The events of a single user can be received by only one application. If several applications subscribe the same user, a call with |
The single-recipient restriction is intentional: the assumption is that one agent reacts to a user's events immediately. If you need several independent handlers, use different user contexts or webhook subscriptions.
How This Differs from Chatbot Events
|
If You Need To |
Open the Section |
|
Read the event stream on behalf of a user or application, without registering a bot |
The |
|
Receive bot events — incoming messages, command calls, adding the bot to a chat |
There are two differences. The im.v2 events require an explicit subscription, whereas the subscription to the ONIMBOTV2* bot events is created automatically when the bot is registered. In addition, the im.v2 events are available only through polling, while bot events can also be received in webhook mode.
Overview of Methods and Events
Scope:
imWho can execute methods: user or application with access to the messenger
Methods
|
Method |
Description |
|
Subscribes to event recording |
|
|
Stops event recording |
|
|
Returns events in polling mode |
|
|
Description of events and data structures |
Events
The event type arrives in the events[].type field of the im.v2.Event.get response, and the data — in the events[].data field.
|
Event |
Triggered |
|
When a new message appears in a chat the subscribed user belongs to |
|
|
When a message is edited in a chat |
|
|
When a message is deleted in a chat |
|
|
When a reaction to a message in a chat is added or removed |
|
|
When a new participant is added to a chat |