← Назад к справке

REST

Chat bots

Рабочая справка по чат-ботам Bitrix24 REST: imbot.v2, регистрация, botToken, список ботов, удаление, отправка сообщений и события.

Для новых интеграций лучше смотреть в сторону imbot.v2. Старый раздел imbot ещё встречается в проектах, но при новой разработке лучше не начинать с устаревших методов.

Общее понимание

Чат-бот — это бот, зарегистрированный приложением и работающий в мессенджере Bitrix24.

imbot и imbot.v2

API Как воспринимать
imbot Старый API ботов. Может встречаться в существующих решениях.
imbot.v2 Актуальный API для жизненного цикла бота, сообщений, команд и файлов.
im.v2 События и работа с мессенджером в новой схеме.

Что хранить после регистрации

После регистрации бота нужно сохранить его ID и токен, если метод вернул токен для дальнейших вызовов. Без этих данных потом сложно обновлять, удалять бота и отправлять сообщения от его имени. 

{
    "bot_id": 25,
    "bot_token": "saved_bot_token"
}

botToken

В ряде методов imbot.v2 используется botToken. Его нужно передавать тем же, который был получен или задан при регистрации бота.

Жизненный цикл бота

Минимальный набор: зарегистрировать, получить список, удалить при необходимости.

Регистрация

Точный набор параметров лучше сверять с текущей документацией метода imbot.v2.Bot.register. В заготовке ниже показан общий принцип. 

BX24.callMethod(
    'imbot.v2.Bot.register',
    {
        CODE: 'support_bot',
        TYPE: 'B',
        EVENT_HANDLER: 'https://example.com/bitrix24/bot-handler.php',
        PROPERTIES: {
            NAME: 'Support bot',
            COLOR: 'GREEN'
        }
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log(result.data());
    }
);

Список ботов

BX24.callMethod(
    'imbot.v2.Bot.list',
    {
        botToken: savedBotToken
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log(result.data());
    }
);

Удаление бота

BX24.callMethod(
    'imbot.v2.Bot.unregister',
    {
        botId: botId,
        botToken: savedBotToken
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log('Bot deleted');
    }
);

Сообщения

Сообщения от имени бота отправляются через методы раздела imbot.v2.Chat.Message.

Отправить сообщение

BX24.callMethod(
    'imbot.v2.Chat.Message.send',
    {
        botToken: savedBotToken,
        chatId: chatId,
        message: {
            text: 'Здравствуйте! Я бот поддержки.'
        }
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log(result.data());
    }
);

Если появляется ошибка владения ботом, проверь, тем ли приложением зарегистрирован бот и тот ли botToken используется.

Получить сообщение

BX24.callMethod(
    'imbot.v2.Chat.Message.get',
    {
        botToken: savedBotToken,
        messageId: messageId
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log(result.data());
    }
);

События сообщений

События бота приходят на обработчик, который указан при регистрации или обновлении бота. Для новой разработки важно не смешивать старые события imbot и новые события imbot.v2: формат данных отличается. 

<?php

/**
 * Читает входящее событие бота.
 */
function fetchBotEventPayload(): array
{
    $input = file_get_contents('php://input');
    $payload = json_decode($input, true);

    if (is_array($payload)) {
        return $payload;
    }

    return $_REQUEST;
}

$event_payload = fetchBotEventPayload();

file_put_contents(
    __DIR__ . '/bot-events.log',
    print_r($event_payload, true) . PHP_EOL,
    FILE_APPEND
);

На первом этапе лучше просто логировать входящие события, чтобы увидеть фактическую структуру payload на своём портале и только потом писать обработку.

Источники