Как вызывать методы чат-бота 2.0 и обновлять токен авторизации

Методы чат-ботов imbot.v2 вызываются так же, как остальные методы REST API, но способ авторизации меняет состав параметров запроса и определяет, нужно ли обновлять токен доступа. Правила ниже относятся только к imbot.v2: вызов устаревших методов imbot.* описан на странице Как вызывать методы устаревших чат-ботов.

Чтобы вызывать методы от имени бота, зарегистрируйте бота методом imbot.v2.Bot.register. Для OAuth-сценария приложение должно быть установлено в Битрикс24: первую пару токенов Битрикс24 выдает при установке. Как получить и сохранить эту пару, описано в сценариях установки приложений.

Параметры, ответы и коды ошибок отдельных методов описаны на страницах методов раздела Чат-боты 2.0. Если сообщения нужно отправлять не от имени бота, а от имени пользователя, используйте методы im.* раздела Чаты — авторизация в них устроена иначе, botToken не участвует.

Scope: imbot

Кто может выполнять методы: владелец зарегистрированного бота — приложение или вебхук, от имени которого бот был зарегистрирован. Исключения: imbot.v2.Bot.register — авторизованный пользователь, imbot.v2.Revision.get — любой пользователь

Какие токены участвуют в вызовеКакие токены участвуют в вызове

В вызовах бота встречаются четыре разных токена. Обновлять нужно только access_token.

botToken — это не токен OAuth, он не истекает и не участвует в обновлении авторизации. Он идентифицирует бота при webhook-вызове: по нему Битрикс24 определяет владельца бота вместо client_id приложения.

Как выбрать способ авторизацииКак выбрать способ авторизации

Вызовы через входящий вебхук выполняются только по протоколу HTTPS: при обращении по HTTP вернется ошибка INVALID_REQUEST с описанием Https required. Такие вызовы выполняются с правами пользователя, создавшего вебхук, и в рамках выбранного для вебхука scope.

Развернутое описание обоих способов — в разделе Авторизация.

Базовый вызов методаБазовый вызов метода

Ниже — вызов метода imbot.v2.Chat.Message.send в двух вкладках cURL, по одной на способ авторизации, и через готовую обертку PHP CRest.

Как использовать примеры в документации

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"botToken":"my_bot_token","dialogId":"chat5","fields":{"message":"Введите строку поиска"}}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Chat.Message.send
        

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"dialogId":"chat5","fields":{"message":"Введите строку поиска"},"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/imbot.v2.Chat.Message.send
        

require_once('crest.php');
        
        $result = CRest::call(
            'imbot.v2.Chat.Message.send',
            [
                'botId' => 456,
                // 'botToken' => 'my_bot_token', // только при webhook-авторизации
                'dialogId' => 'chat5',
                'fields' => [
                    'message' => 'Введите строку поиска',
                ],
            ]
        );
        
        if (!empty($result['error'])) {
            echo 'Error: ' . $result['error_description'];
        } else {
            echo 'Message ID: ' . $result['result']['id'];
        }
        

botId возвращает метод imbot.v2.Bot.register при регистрации бота. Формат dialogId — chat{chatId} для групповых чатов и {userId} для личных, подробнее: Формат dialogId.

Примеры того же вызова на JS, PHP и BX24.js — в разделе «Примеры кода» на странице метода imbot.v2.Chat.Message.send.

Что возвращает вызовЧто возвращает вызов

Ответ любого метода состоит из блока result с данными метода и служебного блока time со временем выполнения запроса. Для imbot.v2.Chat.Message.send блок result выглядит так:

{
            "result": {
                "id": 789,
                "uuidMap": {}
            }
        }
        

Состав result у каждого метода свой и описан в разделе «Возвращаемые данные» на его странице.

Ошибки авторизацииОшибки авторизации

Системные ошибки expired_token и NO_AUTH_FOUND возвращаются со статусом 401, insufficient_scope — со статусом 403. Полный список: Коды ошибок.

Обновление OAuth-токенаОбновление OAuth-токена

Раздел относится только к OAuth-сценарию.

Когда обновлять токенКогда обновлять токен

Обновляйте токен по факту ошибки, а не по расписанию:

1. Вызовите метод с сохраненным access_token.
2. Если вернулась ошибка expired_token со статусом 401 — запросите новую пару токенов по сохраненному refresh_token.
3. Сохраните новую пару токенов на своей стороне: вместе с access_token сервер возвращает новое значение refresh_token, дальше используйте его.
4. Повторите исходный запрос с новым access_token.

Если сервер авторизации не вернул новую пару, значит истек сам refresh_token или приложение удалено с Битрикс24. Восстановить авторизацию запросом уже нельзя — приложение нужно установить заново и сохранить выданные при установке токены.

Чем обновлять токенЧем обновлять токен

Готовые обертки берут обновление на себя:

• PHP CRest — набор PHP-файлов для своего веб-сервера, нужен модуль cURL. Продлевает токены автоматически и хранит их сам
• b24phpsdk — Composer-пакет с типизированными сервисами, нужен PHP 8.2 и выше. Обновляет истекший access_token и сообщает об этом событием AuthTokenRenewedEvent, сохранение новой пары реализует разработчик
• b24jssdk — библиотека для JavaScript, подключается через npm. Обновляет пару при ошибке expired_token, сохранение новой пары реализует разработчик

Функция restAuth ниже нужна, когда вы вызываете REST API собственным кодом без обертки.

Функция restAuthФункция restAuth

Функция обменивает сохраненный refresh_token на новую пару токенов. Константы CLIENT_ID и CLIENT_SECRET — это код и секретный ключ приложения из партнерского кабинета или из карточки локального приложения в Битрикс24.

Обновление выполняется GET-запросом к серверу авторизации с четырьмя параметрами в query-строке: grant_type=refresh_token, client_id, client_secret и refresh_token. Адрес сервера зависит от региона лицензии и возвращается в поле domain ответа на запрос токенов. Если приложение работает в нескольких регионах, берите хост из поля domain, а не из константы.

const OAUTH_SERVER = 'https://oauth.bitrix24.tech/oauth/token/';
        const CLIENT_ID = '**put_your_client_id_here**';
        const CLIENT_SECRET = '**put_your_client_secret_here**';
        
        /**
         * Refresh OAuth token pair.
         *
         * @param array $auth Saved authorization data with refresh_token
         *
         * @return array|false New token pair or false if refresh failed
         */
        function restAuth(array $auth)
        {
            if (!CLIENT_ID || !CLIENT_SECRET || empty($auth['refresh_token']))
            {
                return false;
            }
        
            $queryData = http_build_query(
                [
                    'grant_type' => 'refresh_token',
                    'client_id' => CLIENT_ID,
                    'client_secret' => CLIENT_SECRET,
                    'refresh_token' => $auth['refresh_token'],
                ]
            );
        
            $curl = curl_init();
        
            curl_setopt_array(
                $curl,
                [
                    CURLOPT_HEADER => 0,
                    CURLOPT_RETURNTRANSFER => 1,
                    CURLOPT_URL => OAUTH_SERVER . '?' . $queryData,
                ]
            );
        
            $result = curl_exec($curl);
            curl_close($curl);
        
            $tokens = json_decode($result, true);
        
            return empty($tokens['access_token']) ? false : $tokens;
        }
        

Сервер возвращает JSON, из которого нужно сохранить четыре поля:

• access_token — новый токен доступа для параметра auth
• refresh_token — новое значение, старое больше не используйте
• expires_in — время жизни access_token в секундах
• domain — домен сервера авторизации для следующего обновления

Полный состав ответа сервера авторизации описан на странице Автоматическое продление токенов OAuth 2.0.

Как использовать restAuthКак использовать restAuth

callRest в примере — ваша функция вызова метода, которая подставляет access_token в параметр auth.

$params = [
            'botId' => 456,
            'dialogId' => 'chat5',
            'fields' => ['message' => 'Введите строку поиска'],
        ];
        
        $result = callRest('imbot.v2.Chat.Message.send', $params, $auth['access_token']);
        
        if (($result['error'] ?? '') === 'expired_token')
        {
            $newAuth = restAuth($auth);
        
            if ($newAuth === false)
            {
                // refresh_token истек или приложение удалено — нужна повторная установка приложения
                error_log('Token refresh failed');
            }
            else
            {
                $auth = $newAuth;
                saveAuth($auth); // сохраните новую пару токенов в своем хранилище
                $result = callRest('imbot.v2.Chat.Message.send', $params, $auth['access_token']);
            }
        }
        

Хранение секретовХранение секретов

Секретами считайте код вебхука вместе с его URL, CLIENT_SECRET, refresh_token и botToken:

• храните их только на своем сервере — код вебхука дает полный доступ к REST API в рамках своего scope и не требует отдельного подтверждения
• не передавайте их в браузер, ссылки и журналы приложения
• не сохраняйте их в репозитории — выносите в переменные окружения или защищенное хранилище

Общие правила безопасности интеграции — Рекомендации по безопасности.

Частые источники путаницыЧастые источники путаницы

Два места, где похожие названия означают разные вещи:

• в fields.* вложены параметры, описывающие содержимое — текст сообщения, свойства бота, настройки команды. Идентификаторы и служебные параметры вроде botId, dialogId, botToken, offset передаются верхним уровнем запроса
• eventMode бота не связан со способом авторизации: бот с webhook-авторизацией может работать в режиме fetch, а бот приложения с OAuth — в режиме webhook. Сами режимы доставки событий описаны в разделе Режимы доставки событий

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

• Чат-боты 2.0: быстрый старт — первый бот от регистрации до ответа на сообщение
• Чат-боты 2.0: обзор методов — все методы раздела, типы ботов, лимиты и формат dialogId
• Зарегистрировать бота imbot.v2.Bot.register — где задается botToken и выбирается eventMode
• Отправить сообщение imbot.v2.Chat.Message.send — параметры, ответ и коды ошибок метода из примеров
• Автоматическое продление токенов OAuth 2.0 — полный цикл работы с токенами OAuth
• Как вызывать методы устаревших чат-ботов — только для интеграций на устаревших методах imbot.*