Migration from imbot to 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.
A mapping table of methods and events between the deprecated API (imbot) and the new bot platform (imbot.v2).
Methods v1 and v2 operate in parallel. Bots registered through v1 are visible in v2 and vice versa. However, the event formats differ — the bot receives events only in the format of the API version through which it was registered.
Methods
|
v1 |
v2 |
Changes |
|
Parameters are nested in |
||
|
Parameters are nested in |
||
|
No changes |
||
|
Returns an array of Bot objects instead of a flat list |
||
|
— |
New method: retrieve a single bot by ID |
|
|
Text and parameters in |
||
|
Parameters in |
||
|
No changes |
||
|
— |
New method: mark messages as read |
|
|
— |
New method: add a reaction |
|
|
— |
New method: remove a reaction |
|
|
imbot.v2.Chat.Message.Reaction.add, imbot.v2.Chat.Message.Reaction.delete |
In v2, setting and removing a reaction are separated into two methods |
|
|
Parameters in |
||
|
Returns a Chat object |
||
|
Returns a Chat object |
||
|
In v2, changing the title is done through a universal chat properties update |
||
|
In v2, changing the color is done through a universal chat properties update |
||
|
In v2, changing the avatar is done through a universal chat properties update |
||
|
— |
New universal method: update chat properties |
|
|
— |
||
|
— |
||
|
— |
||
|
— |
||
|
In v2, assigning and removing admin rights are separated into two methods |
||
|
— |
||
|
— |
||
|
— |
New method: control the input field |
|
|
Parameters in |
||
|
Parameters in |
||
|
— |
New method: list of bot commands |
|
|
— |
||
|
— |
||
|
— |
New method: polling events (fetch mode) |
|
|
— |
New method: upload a file to chat |
|
|
— |
New method: get a download link |
|
|
— |
New method: get API revision numbers |
Events
|
v1 |
v2 |
Changes |
|
Data in V2 format (camelCase, Bot/Chat/Message/User objects) |
||
|
Data in V2 format: camelCase and nested objects |
||
|
Data in V2 format: camelCase and nested objects |
||
|
Data in V2 format: camelCase and nested objects |
||
|
Data in V2 format: camelCase and |
||
|
Data in V2 format: camelCase and nested objects; |
||
|
ONIMBOTCONTEXTGET |
Data in V2 format: camelCase and nested objects |
|
|
— |
New event: change reaction to a bot message |
Key Differences in v2
Data Format
- camelCase instead of UPPER_CASE for keys — for example,
chatIdinstead ofCHAT_ID - Nested objects instead of flat fields — Bot, Chat, Message, User
- Boolean fields — actual
true/falseinstead of strings"Y"/"N"
Event Delivery
- v1: only webhook (EVENT_HANDLER URL)
- v2: fetch mode (polling via imbot.v2.Event.get) + webhook mode as an option when registering the bot
Method Parameters
- v1: flat top-level parameters (
MESSAGE_ADD,BOT_ID,TYPE, etc.) - v2: grouping in
fields.*/properties.*, camelCase names
Authorization
- v1: OAuth or webhook authorization with
CLIENT_IDfield - v2: OAuth or webhook authorization with
botToken
Changes within v2
The API imbot.v2 continues to evolve. New features, fixes, and changes with loss of backward compatibility are published in the API imbot.v2 Change Log.
If the format of a method's call or response changes, the previous version will continue to be supported for 6 months from the date of the change publication.
Continue Exploring
- Register a bot imbot.v2.Bot.register
- Get Events from imbot.v2.Event.get
- API imbot.v2 Change Log
- Automation Rule Platform: Overview of the Section