Миграция с imbot на imbot.v2

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Таблица соответствия методов и событий между устаревшим API (imbot) и новой бот-платформой (imbot.v2).

Методы v1 и v2 работают параллельно. Боты, зарегистрированные через v1, видны в v2 и наоборот. Однако формат событий различается — бот получает события только в формате той версии API, через которую был зарегистрирован.

Методы

v1	v2	Изменения
imbot.register	imbot.v2.Bot.register	Параметры вложены в `fields.*`, добавлен `fields.eventMode` (fetch/webhook)
imbot.update	imbot.v2.Bot.update	Параметры вложены в `fields.*`
imbot.unregister	imbot.v2.Bot.unregister	Без изменений
imbot.bot.list	imbot.v2.Bot.list	Возвращает массив объектов Bot вместо плоского списка
—	imbot.v2.Bot.get	Новый метод: получение одного бота по ID
imbot.message.add	imbot.v2.Chat.Message.send	Текст и параметры в `fields.*`
imbot.message.update	imbot.v2.Chat.Message.update	Параметры в `fields.*`
imbot.message.delete	imbot.v2.Chat.Message.delete	Без изменений
—	imbot.v2.Chat.Message.read	Новый метод: отметить сообщения прочитанными
—	imbot.v2.Chat.Message.Reaction.add	Новый метод: добавить реакцию
—	imbot.v2.Chat.Message.Reaction.delete	Новый метод: удалить реакцию
imbot.message.like	imbot.v2.Chat.Message.Reaction.add, imbot.v2.Chat.Message.Reaction.delete	В v2 установка и снятие реакции разделены на два метода
imbot.chat.add	imbot.v2.Chat.add	Параметры в `fields.*`
imbot.chat.get	imbot.v2.Chat.get	Возвращает объект Chat
imbot.dialog.get	imbot.v2.Chat.get	Возвращает объект Chat
imbot.chat.updateTitle	imbot.v2.Chat.update	В v2 изменение заголовка выполняется через универсальное обновление свойств чата
imbot.chat.updateColor	imbot.v2.Chat.update	В v2 изменение цвета выполняется через универсальное обновление свойств чата
imbot.chat.updateAvatar	imbot.v2.Chat.update	В v2 изменение аватара выполняется через универсальное обновление свойств чата
—	imbot.v2.Chat.update	Новый универсальный метод: обновление свойств чата
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	В v2 назначение и снятие прав администратора разделены на два метода
imbot.chat.setOwner	imbot.v2.Chat.setOwner	—
imbot.chat.sendTyping	imbot.v2.Chat.InputAction.notify	—
—	imbot.v2.Chat.TextField.enabled	Новый метод: управление полем ввода
imbot.command.register	imbot.v2.Command.register	Параметры в `fields.*`
imbot.command.update	imbot.v2.Command.update	Параметры в `fields.*`
—	imbot.v2.Command.list	Новый метод: список команд бота
imbot.command.unregister	imbot.v2.Command.unregister	—
imbot.command.answer	imbot.v2.Command.answer	—
—	imbot.v2.Event.get	Новый метод: polling событий (fetch-режим)
—	imbot.v2.File.upload	Новый метод: загрузка файла в чат
—	imbot.v2.File.download	Новый метод: получение ссылки на скачивание
—	imbot.v2.Revision.get	Новый метод: получение номеров ревизий API

События

v1	v2	Изменения
ONIMBOTMESSAGEADD	ONIMBOTV2MESSAGEADD	Данные в формате V2 (camelCase, объекты Bot/Chat/Message/User)
ONIMBOTMESSAGEUPDATE	ONIMBOTV2MESSAGEUPDATE	Данные в формате V2: camelCase и вложенные объекты
ONIMBOTMESSAGEDELETE	ONIMBOTV2MESSAGEDELETE	Данные в формате V2: camelCase и вложенные объекты
ONIMBOTJOINCHAT	ONIMBOTV2JOINCHAT	Данные в формате V2: camelCase и вложенные объекты
ONIMBOTDELETE	ONIMBOTV2DELETE	Данные в формате V2: camelCase и объект `bot` нового формата
ONIMCOMMANDADD	ONIMBOTV2COMMANDADD	Данные в формате V2: camelCase и вложенные объекты; поле `context` в нижнем регистре: `textarea`, `keyboard`, `menu`
ONIMBOTCONTEXTGET	ONIMBOTV2CONTEXTGET	Данные в формате V2: camelCase и вложенные объекты
—	ONIMBOTV2REACTIONCHANGE	Новое событие: изменение реакции на сообщение бота

Ключевые отличия v2

Формат данных

camelCase вместо UPPER_CASE для ключей — например, chatId вместо CHAT_ID
Вложенные объекты вместо плоских полей — Bot, Chat, Message, User
Boolean-поля — настоящие true/false вместо строк "Y"/"N"

Доставка событий

v1: только webhook (EVENT_HANDLER URL)
v2: fetch-режим (polling через imbot.v2.Event.get) + webhook-режим на выбор при регистрации бота

Параметры методов

v1: плоские параметры верхнего уровня (MESSAGE_ADD, BOT_ID, TYPE и т.д.)
v2: группировка в fields.* / properties.*, camelCase имена

Авторизация

v1: OAuth или webhook-авторизация с полем CLIENT_ID
v2: OAuth или webhook-авторизация с botToken

Изменения внутри v2

API imbot.v2 продолжает развиваться. Новые возможности, исправления и изменения с потерей обратной совместимости публикуются в Журнале изменений API imbot.v2.

Если формат вызова или ответа метода меняется, предыдущий вариант продолжает поддерживаться 6 месяцев с момента публикации изменения.

Продолжите изучение

Объекты и поля

Журнал изменений API imbot.v2

Миграция с imbot на imbot.v2

МетодыМетоды

СобытияСобытия

Ключевые отличия v2Ключевые отличия v2

Формат данныхФормат данных

Доставка событийДоставка событий

Параметры методовПараметры методов

АвторизацияАвторизация

Изменения внутри v2Изменения внутри v2

Продолжите изучениеПродолжите изучение