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

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

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

Эта страница помогает перенести интеграцию с устаревшего API imbot на imbot.v2: выбрать способ доставки событий, сопоставить методы и поля запросов, обновить обработку ответов.

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

Порядок перехода

Найдите используемые методы и события v1 в таблицах ниже. Сверьте параметры каждого вызова со страницей соответствующего метода v2: названия полей, обязательность и допустимые значения могут отличаться.
Проверьте, через какую версию API зарегистрирован бот. Замена вызовов v1 на v2 сама по себе не меняет формат событий существующего бота. Если нужны события ONIMBOTV2*, учитывайте версию регистрации при планировании перехода и настройте обработку нового формата событий.
Выберите режим доставки событий для бота v2 по таблице ниже.
Перенесите параметры запросов по таблице методов и проверьте авторизацию.
Сверьте ответы и обработчики событий с форматами v2. Проверьте новый вызов и получение события до переключения рабочего сценария. Для примера сравнения запросов и ответов смотрите отправку сообщения.

Как выбрать режим событий

Режим v2	Когда подходит	Что настроить
`fetch`	У приложения нет публичного URL для событий или нужен контроль очереди через `offset`	Укажите `fields.eventMode: fetch` при регистрации бота и опрашивайте imbot.v2.Event.get. Это режим по умолчанию
`webhook`	У приложения есть публичный HTTP-обработчик событий	Укажите `fields.eventMode: webhook` и обязательный `fields.webhookUrl`. Обработчик должен отвечать HTTP 200; повторная доставка при сбое не гарантируется

Подробности реализации обоих режимов — в разделе Режимы доставки событий.

Авторизация при переходе

Методы обеих версий используют scope imbot. При OAuth вызовы v2 не требуют botToken. При авторизации через вебхук передавайте токен бота botToken, указанный при его регистрации: CLIENT_ID из v1 не является тем же токеном. Храните botToken вне публичного кода и логов.

Методы

v1	v2	Изменения
imbot.register	imbot.v2.Bot.register	`CODE` → `fields.code`, `PROPERTIES.NAME` → `fields.properties.name`, `PROPERTIES.WORK_POSITION` → `fields.properties.workPosition`. Вместо `EVENT_HANDLER` задайте `fields.eventMode: webhook` и `fields.webhookUrl`; для опроса событий — `fields.eventMode: fetch`
imbot.update	imbot.v2.Bot.update	`BOT_ID` → `botId`, `FIELDS.PROPERTIES.NAME` → `fields.properties.name`, `FIELDS.PROPERTIES.WORK_POSITION` → `fields.properties.workPosition`, `FIELDS.EVENT_HANDLER` → `fields.webhookUrl` при `fields.eventMode: webhook`. Смена `webhookUrl` или `eventMode` автоматически пересобирает подписки `ONIMBOTV2*` — ручной `event.unbind` не нужен
imbot.unregister	imbot.v2.Bot.unregister	Подписки `ONIMBOTV2*` чистятся автоматически — workaround с ручным `event.unbind` после unregister не нужен
imbot.bot.list	imbot.v2.Bot.list	Возвращает массив объектов Bot вместо плоского списка
—	imbot.v2.Bot.get	Новый метод: получение одного бота по ID
imbot.message.add	imbot.v2.Chat.Message.send	`BOT_ID` → `botId`, `DIALOG_ID` → `dialogId`, `MESSAGE` → `fields.message`, `ATTACH` → `fields.attach`, `KEYBOARD` → `fields.keyboard`, `SYSTEM` → `fields.system`, `URL_PREVIEW` → `fields.urlPreview`. В v2 `botId` обязателен
imbot.message.update	imbot.v2.Chat.Message.update	`BOT_ID` → `botId`, `MESSAGE_ID` → `messageId`, `MESSAGE` → `fields.message`, `ATTACH` → `fields.attach`, `KEYBOARD` → `fields.keyboard`, `URL_PREVIEW` → `fields.urlPreview`
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	`BOT_ID` → `botId`, `TYPE` → `fields.type`, `TITLE` → `fields.title`, `DESCRIPTION` → `fields.description`, `COLOR` → `fields.color`, `AVATAR` → `fields.avatar`, `USERS` → `fields.userIds`. В v2 `botId` обязателен, значения `TYPE` и `COLOR` изменились
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	`BOT_ID` → `botId`, `COMMAND` → `fields.command`, `LANG[].TITLE` → `fields.title.{код языка}`, `LANG[].PARAMS` → `fields.params.{код языка}`, `COMMON` → `fields.common`, `HIDDEN` → `fields.hidden`, `EXTRANET_SUPPORT` → `fields.extranetSupport`
imbot.command.update	imbot.v2.Command.update	`COMMAND_ID` → `commandId`, `FIELDS.COMMAND` → `fields.command`, `FIELDS.LANG[].TITLE` → `fields.title.{код языка}`, `FIELDS.LANG[].PARAMS` → `fields.params.{код языка}`, `FIELDS.HIDDEN` → `fields.hidden`, `FIELDS.EXTRANET_SUPPORT` → `fields.extranetSupport`. В v2 дополнительно обязателен `botId`
—	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

В таблице показаны поля с соответствием в указанных методах v2. Для полей типа boolean преобразуйте значения Y/N в true/false. При создании чата значение TYPE=CHAT соответствует fields.type=chat, а TYPE=OPEN — fields.type=open. У отдельных параметров v1 нет прямого поля в соответствующем методе v2, например у EVENT_COMMAND_ADD в Command.register и MENU в Chat.Message.send.

Пример: отправка сообщения в v1 и v2

Ниже — запросы через OAuth и ответы из страниц методов imbot.message.add и imbot.v2.Chat.Message.send. Это два независимых примера: значения ID и текста в них различаются.

v1. Текст сообщения передается на верхнем уровне в MESSAGE:

{
    "BOT_ID": 39,
    "DIALOG_ID": "chat123",
    "MESSAGE": "Текст сообщения",
    "auth": "**put_access_token_here**"
}

Ответ v1 возвращает ID сообщения числом в 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. Текст сообщения передается во вложенном поле fields.message:

{
    "botId": 456,
    "dialogId": "chat5",
    "fields": {
        "message": "Hello from bot!"
    },
    "auth": "**put_access_token_here**"
}

Ответ v2 возвращает ID сообщения в 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"
    }
}

События

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
Часть флагов передается как true/false вместо строк "Y"/"N", например fields.common у команды. Проверяйте тип на странице метода: fields.urlPreview в Chat.Message.update принимает Y/N

Была ли статья полезна?

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

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

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

Порядок перехода

Как выбрать режим событий

Авторизация при переходе

Методы

Пример: отправка сообщения в v1 и v2

События

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

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

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

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

Авторизация

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

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

Была ли статья полезна?

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

Порядок переходаПорядок перехода

Как выбрать режим событийКак выбрать режим событий

Авторизация при переходеАвторизация при переходе

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

Пример: отправка сообщения в v1 и v2Пример: отправка сообщения в v1 и v2

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

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

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

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

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

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

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

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

Была ли статья полезна?

Порядок перехода

Как выбрать режим событий

Авторизация при переходе

Методы

Пример: отправка сообщения в v1 и v2

События

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

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

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

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

Авторизация

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

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