Migration from imbot to imbot.v2
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
This page helps you migrate an integration from the deprecated imbot API to imbot.v2: choose an event delivery mode, map methods and request fields, and update response handling.
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.
Migration Steps
- Find the v1 methods and events your integration uses in the tables below. Check each call's parameters against the corresponding v2 method page: field names, required fields, and allowed values may differ
- Check which API version was used to register the bot. Replacing v1 calls with v2 calls does not change an existing bot's event format. If you need
ONIMBOTV2*events, account for the registration version and configure handlers for the new event format - Choose a v2 event delivery mode using the table below
- Map request parameters using the methods table and check authorization
- Compare responses and event handlers with the v2 formats. Test the new call and event delivery before switching the live scenario. For a request and response comparison, see the message sending example
How to Choose an Event Mode
|
v2 Mode |
When to Use It |
What to Configure |
|
|
The application has no public event URL, or you need queue control through |
Set |
|
|
The application has a public HTTP event handler |
Set |
Implementation details for both modes are in Event Delivery Modes.
Authorization During Migration
Methods in both versions use the imbot scope. With OAuth, v2 calls do not require botToken. With webhook authorization, pass the bot's botToken provided at registration: the v1 CLIENT_ID is a different token. Keep botToken out of public code and logs.
Methods
|
v1 |
v2 |
Changes |
|
|
||
|
|
||
|
Subscriptions |
||
|
Returns an array of Bot objects instead of a flat list |
||
|
— |
New method: retrieve a single bot by ID |
|
|
|
||
|
|
||
|
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 |
|
|
|
||
|
Returns a Chat object |
||
|
Returns a Chat object |
||
|
In v2, changing the title is done through a universal chat property update |
||
|
In v2, changing the color is done through a universal chat property update |
||
|
In v2, changing the avatar is done through a universal chat property 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 |
|
|
|
||
|
|
||
|
— |
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 |
The table lists fields with equivalents in the specified v2 methods. For boolean fields, convert Y/N to true/false. When creating a chat, TYPE=CHAT corresponds to fields.type=chat, and TYPE=OPEN to fields.type=open. Some v1 parameters have no direct field in the corresponding v2 method, such as EVENT_COMMAND_ADD in Command.register and MENU in Chat.Message.send.
Example: Sending a Message in v1 and v2
The OAuth requests and responses below come from the imbot.message.add and imbot.v2.Chat.Message.send method pages. These are independent examples with different IDs and message text.
v1. Pass the message text in the top-level MESSAGE field:
{
"BOT_ID": 39,
"DIALOG_ID": "chat123",
"MESSAGE": "Message text",
"auth": "**put_access_token_here**"
}
The v1 response returns the numeric message ID in result:
{
"result": 19880117,
"time": {
"start": 1728626400.123,
"finish": 1728626400.234,
"duration": 0.111,
"processing": 0.045,
"date_start": "2024-10-11T10:00:00+03:00",
"date_finish": "2024-10-11T10:00:00+03:00",
"operating_reset_at": 1762349466,
"operating": 0
}
}
v2. Pass the message text in the nested fields.message field:
{
"botId": 456,
"dialogId": "chat5",
"fields": {
"message": "Hello from bot!"
},
"auth": "**put_access_token_here**"
}
The v2 response returns the message ID in result.id:
{
"result": {
"id": 789,
"uuidMap": [],
"failureMap": []
},
"time": {
"start": 1728626400.123,
"finish": 1728626400.234,
"duration": 0.111,
"processing": 0.045,
"date_start": "2024-10-11T10:00:00+03:00",
"date_finish": "2024-10-11T10:00:00+03:00"
}
}
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
- Some flags use
true/falseinstead of strings"Y"/"N", for example a command'sfields.common. Check the type on the method page:fields.urlPreviewin Chat.Message.update acceptsY/N
Event Delivery
In v1, events are delivered through a webhook. In v2, both fetch and webhook are available; the mode selection criteria are described above.
Method Parameters
v1 parameters are passed at the top level (MESSAGE, BOT_ID, TYPE, and others). v2 uses camelCase names and nested fields.* fields, including fields.properties.* for bot properties. The methods table gives specific mappings.
Authorization
v1 supports OAuth and webhook authorization with CLIENT_ID; v2 supports OAuth or webhook authorization with botToken. Token requirements are described in Authorization During Migration.
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 method call or response format changes, the previous version will continue to be supported for 6 months from the date of the change publication.