← К документации

REST

Чат-боты: legacy imbot и imbot.v2

Различия контрактов, регистрация бота нового API и серверное хранение токена.

Не смешивать параметры двух API

Старые imbot.* и imbot.v2.* — разные контракты. Подстановка нового имени метода в старый payload с CODE, TYPE и EVENT_HANDLER не является миграцией.

В новой регистрации параметры находятся внутри fields. Для авторизации через входящий вебхук используется отдельный секрет бота botToken. Его нельзя отдавать в JS публичной страницы.

Регистрация на сервере

Пример использует функцию callWebhook из страницы вебхуков. В конфигурации заранее задайте постоянный секрет бота длиной до 40 символов; не генерируйте новый при каждом запуске.

<?php

$bot_token = (string) getenv('BITRIX24_BOT_TOKEN');
if ($bot_token === '' || strlen($bot_token) > 40) {
    throw new RuntimeException('Не настроен токен бота');
}
$registration = callWebhook($webhook_base, 'imbot.v2.Bot.register', [
    'fields' => [
        'code' => 'notes_demo_bot',
        'botToken' => $bot_token,
        'type' => 'bot',
        'eventMode' => 'fetch',
        'properties' => ['name' => 'Бот проверки'],
    ],
]);
$bot_id = (int) ($registration['result']['bot']['id'] ?? 0);
if ($bot_id <= 0) {
    throw new RuntimeException('Регистрация не вернула ID бота');
}

Сохраните ID вместе с конфигурацией портала. Ответ регистрации, особенно входной токен, не нужно выводить в браузер.

Ответ в известный диалог

В последующих вызовах botId и botToken находятся на верхнем уровне. $dialog_id берётся из события или результата создания чата, к которому у бота есть доступ.

<?php

$send_result = callWebhook($webhook_base, 'imbot.v2.Chat.Message.send', [
    'botId' => $bot_id,
    'botToken' => $bot_token,
    'dialogId' => $dialog_id,
    'fields' => ['message' => 'Запрос получен'],
]);
$message_id = (int) ($send_result['result']['id'] ?? 0);

Получение событий

Режим fetch требует серверного опроса очереди событий. Другой режим использует публичный обработчик. Механизм подтверждения событий, доступность чтения истории и условия доставки проверяются по ревизии API; эти режимы нельзя соединить одним старым EVENT_HANDLER.

Журнал обработчика хранит технические ID и код ошибки. Полный входящий пакет с сообщениями и авторизацией не следует записывать рядом с публичным PHP-файлом.

Источники