Skip to content

migration.md

Latest commit

 

History

History
110 lines (84 loc) · 9.49 KB

migration.md

File metadata and controls

110 lines (84 loc) · 9.49 KB
Raw

Migration from imbot to imbot.v2

{% note tip "" %}

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

{% endnote %}

Table of method and event correspondence between the deprecated API (imbot) and the new bot platform (imbot.v2).

{% note info "" %}

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.

{% endnote %}

Methods

#| || v1 | v2 | Changes || || imbot.register | imbot.v2.Bot.register | Parameters are nested in fields.*, added fields.eventMode (fetch/webhook) || || imbot.update | imbot.v2.Bot.update | Parameters are nested in fields.*. Changing webhookUrl or eventMode automatically rebuilds subscriptions ONIMBOTV2* — manual event.unbind is not needed || || imbot.unregister | imbot.v2.Bot.unregister | Subscriptions ONIMBOTV2* are cleaned automatically — workaround with manual event.unbind after unregister is not needed || || imbot.bot.list | imbot.v2.Bot.list | Returns an array of Bot objects instead of a flat list || || — | imbot.v2.Bot.get | New method: retrieve a single bot by ID || || imbot.message.add | imbot.v2.Chat.Message.send | Text and parameters in fields.* || || imbot.message.update | imbot.v2.Chat.Message.update | Parameters in fields.* || || imbot.message.delete | imbot.v2.Chat.Message.delete | No changes || || — | imbot.v2.Chat.Message.read | New method: mark messages as read || || — | imbot.v2.Chat.Message.Reaction.add | New method: add a reaction || || — | imbot.v2.Chat.Message.Reaction.delete | New method: remove a reaction || || imbot.message.like | imbot.v2.Chat.Message.Reaction.add, imbot.v2.Chat.Message.Reaction.delete | In v2, setting and removing a reaction are separated into two methods || || imbot.chat.add | imbot.v2.Chat.add | Parameters in fields.* || || imbot.chat.get | imbot.v2.Chat.get | Returns a Chat object || || imbot.dialog.get | imbot.v2.Chat.get | Returns a Chat object || || imbot.chat.updateTitle | imbot.v2.Chat.update | In v2, changing the title is done through a universal chat property update || || imbot.chat.updateColor | imbot.v2.Chat.update | In v2, changing the color is done through a universal chat property update || || imbot.chat.updateAvatar | imbot.v2.Chat.update | In v2, changing the avatar is done through a universal chat property update || || — | imbot.v2.Chat.update | New universal method: update chat properties || || imbot.chat.user.add | imbot.v2.Chat.User.add | — || || imbot.chat.user.delete | imbot.v2.Chat.User.delete | — || || imbot.chat.user.list | imbot.v2.Chat.User.list | — || || imbot.chat.leave | imbot.v2.Chat.leave | — || || imbot.chat.setManager | imbot.v2.Chat.Manager.add, imbot.v2.Chat.Manager.delete | In v2, assigning and removing admin rights are separated into two methods || || imbot.chat.setOwner | imbot.v2.Chat.setOwner | — || || imbot.chat.sendTyping | imbot.v2.Chat.InputAction.notify | — || || — | imbot.v2.Chat.TextField.enabled | New method: control the input field || || imbot.command.register | imbot.v2.Command.register | Parameters in fields.* || || imbot.command.update | imbot.v2.Command.update | Parameters in fields.* || || — | imbot.v2.Command.list | New method: list of bot commands || || imbot.command.unregister | imbot.v2.Command.unregister | — || || imbot.command.answer | imbot.v2.Command.answer | — || || — | imbot.v2.Event.get | New method: polling events (fetch mode) || || — | imbot.v2.File.upload | New method: upload a file to chat || || — | imbot.v2.File.download | New method: get a download link || || — | imbot.v2.Revision.get | New method: get API revision numbers || |#

Events

#| || v1 | v2 | Changes || || ONIMBOTMESSAGEADD | ONIMBOTV2MESSAGEADD | Data in V2 format (camelCase, Bot/Chat/Message/User objects) || || ONIMBOTMESSAGEUPDATE | ONIMBOTV2MESSAGEUPDATE | Data in V2 format: camelCase and nested objects || || ONIMBOTMESSAGEDELETE | ONIMBOTV2MESSAGEDELETE | Data in V2 format: camelCase and nested objects || || ONIMBOTJOINCHAT | ONIMBOTV2JOINCHAT | Data in V2 format: camelCase and nested objects || || ONIMBOTDELETE | ONIMBOTV2DELETE | Data in V2 format: camelCase and bot object in the new format || || ONIMCOMMANDADD | ONIMBOTV2COMMANDADD | Data in V2 format: camelCase and nested objects; context field in lowercase: textarea, keyboard, menu || || ONIMBOTCONTEXTGET | ONIMBOTV2CONTEXTGET | Data in V2 format: camelCase and nested objects || || — | ONIMBOTV2REACTIONCHANGE | New event: change reaction to a bot message || |#

Key Differences in v2

Data Format

  • camelCase instead of UPPER_CASE for keys — for example, chatId instead of CHAT_ID
  • Nested objects instead of flat fields — Bot, Chat, Message, User
  • Boolean fields — actual true/false instead 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_ID field
  • 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 method call or response format changes, the previous version will continue to be supported for 6 months from the date of the change publication.

Continue Learning