API Change Log for 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

Change history for the API imbot.v2: new features, fixes, and changes with breaking changes. Entries are listed from newest to oldest and grouped by REST API revision. The revision of a specific Bitrix24 account is returned by the imbot.v2.Revision.get method in the rest field: changes from revisions with a higher number are not yet available on that Bitrix24 account.

Record Prefixes

  • BOT-NEW: new functionality
  • BOT-FIX: bug fix or incorrect behavior
  • BOT-BC: change with breaking compatibility. The old format is supported for 6 months from the date of publication of the change, after which it may be discontinued without notice.

Code format: BOT-{TYPE}-{MMDD}-{N}, where MMDD is the publication date, and N is a sequential number for that date.

REST Revision 36

Publication date: 06.05.2026

BOT-BC-0506-1: Bot.register, botToken length limit

The change has not taken effect, and backward compatibility is preserved.

Previously

imbot.v2.Bot.register accepted botToken of any length. A 40-character limit with the BOT_TOKEN_INVALID_LENGTH error was announced for 06.08.2026.

Now

No change: imbot.v2.Bot.register accepts botToken of any length, and no limit has been introduced for registration.

The 40-character limit applies to a new token when you rotate it via imbot.v2.Bot.update in the fields.botToken parameter. A longer token is rejected with the BOT_TOKEN_INVALID_LENGTH error, see #BOT-NEW-0501-2.

Impact on integrators

For new bots, set a botToken of no more than 40 characters. Bots with a long token keep working. To switch to a short token, call Bot.update {fields: {botToken: '...'}}: the request is authorized with the old long token, and the new one is passed in fields.

Affected methods: imbot.v2.Bot.register, imbot.v2.Bot.update

REST Revision 35

Publication date: 01.05.2026

BOT-FIX-0501-1: Bot.update / Bot.unregister, automatic cleanup of subscriptions to events ONIMBOTV2*

Previously

When changing webhookUrl via imbot.v2.Bot.update, switching eventMode from webhook to fetch, or deleting a bot via imbot.v2.Bot.unregister, old subscriptions to events ONIMBOTV2* remained in the registry and continued to send events to the previously configured URL. After several URL changes, events were sent to all previous addresses simultaneously. Deleted webhook bots also continued to receive events until manually cleared via event.unbind.

Now

imbot.v2.Bot.update and imbot.v2.Bot.unregister automatically bring the bot's subscriptions up to date:

  • When changing webhookUrl — old subscriptions are deleted, new ones are created.
  • When switching eventMode: webhook → fetch — all bot subscriptions are deleted.
  • When Bot.unregister — all bot subscriptions are deleted for any mode.

Cleanup is performed based on the bot's APPLICATION_TOKEN. For OAuth applications with multiple bots, cleanup is skipped if the bot has active neighbors sharing the same APPLICATION_TOKEN.

Impact on integrators

If your code has a workaround with manual event.unbind after Bot.update {eventMode: 'fetch'} or Bot.unregister — it can be removed: after the fix, it does nothing.

Affected methods: imbot.v2.Bot.update, imbot.v2.Bot.unregister

BOT-NEW-0501-2: Bot.update, botToken rotation

The ability to change botToken via fields.botToken has been added to imbot.v2.Bot.update. Request authorization is performed with the old token, while the new one is passed in fields.

After a successful rotation, all ONIMBOTV2* subscriptions are moved to the new APPLICATION_TOKEN if the bot works in webhook mode. The old token immediately loses access. Everything is done in a single transaction.

In case of token collision, the code BOT_TOKEN_ROTATION_FAILED is returned. The length of botToken must not exceed 40 characters.

Affected method: imbot.v2.Bot.update

BOT-FIX-0501-3: Removal of the bot.appId field from method responses and events

Previously

The field bot.appId was present in method responses and in the data of events ONIMBOTV2*.

Now

The field bot.appId has been removed from the responses of all methods and from all events ONIMBOTV2*.

Impact on integrators

If your code read result.bot.appId or data.bot.appId — the field is now absent. To check bot ownership, use result.bot.code or the mere fact of a successful method response (which is only available to the owner).

Affected methods and events: imbot.v2.Bot.register, imbot.v2.Bot.get, imbot.v2.Bot.list, imbot.v2.Bot.update, all events ONIMBOTV2*

REST Revision 34

Publication date: 08.04.2026

BOT-NEW-0408-1: Documentation, general error codes for BotController

Descriptions of basic error codes that may occur at the BotController level have been added to all imbot.v2 methods:

  • BOT_TOKEN_NOT_SPECIFIED: botToken not provided during webhook authorization
  • BOT_ID_REQUIRED: botId not provided
  • BOT_NOT_FOUND: bot not found
  • BOT_OWNERSHIP_ERROR: bot does not belong to the application

BOT-NEW-0408-2: Documentation, additional materials

Links to documentation on advanced messaging capabilities: text formatting, Attach attachments, Keyboard keyboards have been added to Quick Start.

BOT-FIX-0408-3: Command.list, fixed localization display

Previously

imbot.v2.Command.list returned empty title and params for commands registered via REST, including imbot.v2.Command.register and imbot.v2.Command.update. Localizations were correctly saved to the database but were not read due to an error in ID mapping.

Now

title and params are correctly returned in the interface language with a fallback to the default language.

Impact on integrators

Command titles and parameters can be retrieved from the method response, so you do not need to keep a copy of them on your side.

Affected method: imbot.v2.Command.list

BOT-FIX-0408-4: Bot.register / Bot.update, normalization of backgroundId

Previously

backgroundId did not pass validation through the enum of allowed values. Invalid values, such as typos in case or non-existent IDs, were saved to the database as is.

Now

backgroundId is validated against the list of allowed values. Invalid values are set to null without an error. Allowed values: azure, mint, steel, slate, teal, cornflower, sky, peach, frost.

Impact on integrators

Check backgroundId in the method response: if the value was not saved, the response contains null.

Affected methods: imbot.v2.Bot.register, imbot.v2.Bot.update

BOT-FIX-0408-5: Chat.TextField.enabled, support for P2P chats

Previously

imbot.v2.Chat.TextField.enabled returned ACCESS_DENIED in private P2P chats with the bot, although this is the primary use case for the method.

Now

The method checks the bot's membership in the chat instead of the edit permission. It works in any chats where the bot is a participant.

Impact on integrators

The method can be called in private chats between a user and the bot.

Affected method: imbot.v2.Chat.TextField.enabled

BOT-FIX-0408-6: Error code BOT_TOKEN_NOT_SPECIFIED

Previously

When calling methods via webhook without botToken, the error CLIENT_ID_NOT_SPECIFIED was returned.

Now

BOT_TOKEN_NOT_SPECIFIED is returned, which corresponds to the actual reason for the error.

Impact on integrators

If your code handled the CLIENT_ID_NOT_SPECIFIED error, replace it with BOT_TOKEN_NOT_SPECIFIED.

Affected methods: imbot.v2.Bot.register, imbot.v2.Bot.list, imbot.v2.Bot.get, imbot.v2.Bot.update, imbot.v2.Bot.unregister

REST Revision 33

Publication date: 02.04.2026

BOT-NEW-0402-1: New method Revision.get

The method imbot.v2.Revision.get has been added to retrieve API revision numbers. It allows determining the compatibility of Bitrix24 with specific methods and fields and does not require botId and botToken.

BOT-FIX-0402-2: Chat.Message.send, normalization of boolean fields

Previously

When passing fields.system, fields.urlPreview, fields.skipConnector, fields.silentConnector as JSON booleans, i.e., true or false, the values were not converted to Y or N and could be ignored.

Now

All four boolean fields are correctly normalized. Allowed values are true, false, "Y", "N".

Affected method: imbot.v2.Chat.Message.send

Earlier Changes

BOT-BC-0330-1: Command.register, parameters moved to fields

Publication date: 30.03.2026 | Support for the old format until: 30.09.2026

Previously (legacy)

Parameters were passed at the top level of the request:

{
          "botId": 456,
          "botToken": "...",
          "command": "help",
          "title": {"en": "Help"},
          "hidden": false
        }
        

Now

Command parameters are grouped in the fields object, as in other imbot.v2 methods.

{
          "botId": 456,
          "botToken": "...",
          "fields": {
            "command": "help",
            "title": {"en": "Help"},
            "hidden": false
          }
        }
        

Compatibility

If fields is provided, the new format is used. If fields is absent, the legacy format is used. The 30.09.2026 support deadline has passed, but the method still accepts the flat format. Pass the parameters in fields: support for the legacy format may be discontinued without notice.

Affected method: imbot.v2.Command.register

BOT-BC-0325-1: Event.get, pagination through nextOffset

Publication date: 25.03.2026 | Support for the old format until: 25.09.2026

Previously

The response contained the field lastEventId, and the client had to compute the next offset as lastEventId + 1.

Now

The response contains the field nextOffset. To get the next batch, pass this value in the offset parameter. The lastEventId field has been removed from the response.

{
          "result": {
            "events": [],
            "nextOffset": 1002,
            "hasMore": false
          }
        }
        

Next request:

{
          "botId": 456,
          "botToken": "...",
          "offset": 1002
        }
        

If hasMore: false, there are no new events, but nextOffset still needs to be saved for the next polling cycle.

Affected method: imbot.v2.Event.get

Continue Learning