Каждый PHP-разработчик, работающий с экосистемой Bitrix Framework, должен глубоко понимать работу её ключевых компонентов. В этой статье мы проведем подробный аудит темы «Пример создания чат-бота для Открытых линий», проанализируем лучшие практики и покажем, как правильно использовать битрикс в реальных задачах.

Пример создания чат-бота для Открытых линий

Процесс создания чат-бота для Открытых линий аналогичен созданию обычного чат-бота, но есть два отличия:

1. При создании чат-бота для Открытых линий в imbot.register в параметр TYPE нужно передать O

2. Если необходимо расширить возможности уже существующего чат-бота, то следует передать новый ключ OPENLINE => Y, и тогда чат-бот будет работать в гибридном режиме.

В гибридном режиме чат-бот должен корректно работать в групповом чате, персональном чате и чате открытых линий. Для этого нужно во всех входящих событиях (ONIMBOTMESSAGEADD и ONIMBOTJOINCHAT) проверять параметр CHAT_ENTITY_TYPE — для Открытых линий он должен быть CHAT_ENTITY_TYPE => LINES.

Во всем остальном это привычный и уже знакомый чат-бот.

Для более тесной интеграции с Открытыми линиями необходимо иметь права доступа на scope imopenlines.

С данным правом будут доступны команды:

• imopenlines.network.join — подключение открытой линии вашей компании к порталу Битрикс24, после чего сотрудники смогут вам писать
• imopenlines.bot.session.operator — переключение разговора на свободного оператора
• imopenlines.bot.session.transfer — переключение разговора на конкретного оператора
• imopenlines.bot.session.finish — завершение текущей сессии

Скачать пример чат-бота для Открытых линий

В качестве примера чат-бота для открытых линий мы подготовили чат-бот «ITR Bot». Получить его можно следующими способами:

• скачать c сервиса GitHub, файл itr.php
• найти и скопировать в продукте «Битрикс24 в коробке» в папке \Bitrix\ImBot\Bot\OpenlinesMenuExample

Данный чат-бот выступает в качестве первой линии поддержки: сначала все сообщения будут поступать к нему, а только потом — сотрудникам в очередь. Время, через которое сообщения будут переадресованы с чат-бота на сотрудников, задается в настройках открытой линии.

Также в чат-бот добавлен класс для построения многоуровневого меню в чатах.

Запуск на своем портале

Вы можете взять код примера чат-бота выше, выложить на своем сервере и запустить чат-бота на своем портале в качестве локального приложения, не публикуя его через Маркет:

• В левом меню в разделе Приложения (1) перейдите в подраздел Разработчикам (2) и выберите пункт Другое (3):

!Добавление приложения

• Используйте сценарий Локальное приложение (4):

!Локальное приложение

• Выберите тип приложения Серверное и настройте его параметры:
• Смените название бота
• Включите опцию Использует только API и задайте приложению права доступа на:
• Создание и управление Чат-ботами — без этих прав приложение не сможет зарегистрировать чат-бота
• Открытые линии — без этих прав приложение не сможет работать с открытыми линиями
• Поскольку скрипт написан таким образом, что является обработчиком всех событий, то в полях Путь вашего обработчика и Путь для первоначальной установки ссылки будут вести на один и тот же URL

!Добавить приложение ITR Bot

• После сохранения настроек появятся дополнительные поля: Код приложения (client_id) и Ключ приложения (client_secret)

!Настройки бота

• Скопируйте данные из этих полей и вставьте в файл itr.php

!Настройки открытых линий

• В настройках бота нажмите Переустановить. Теперь бот готов к работе.

Этот бот не публикует сообщения о том, что его пригласили на портал. После установки он будет доступен в настройках открытых линий. Выберите его ответственным и укажите время, через которое разговор будет переведен от чат-бота в очередь к сотрудникам:

!Настройки открытых линий

Ниже показан диалог: сначала отвечает «ITR Bot», клиент кликает в меню по пунктам, далее очередь переходит на оператора, так как клиент выбрал пункт меню 0. Wait operator answer:

!Диалог с ITR Bot

Настроить собственное меню в «ITR Bot» можно в методе itrRun:

/**
* Run ITR menu
*
* @param $portalId
* @param $dialogId
* @param $userId
* @param string $message
* @return bool
*/
function itrRun($portalId, $dialogId, $userId, $message = '')
{
    if ($userId <= 0)
        return false;

    $menu0 = new ItrMenu(0);
    $menu0->setText('Main menu (#0)');
    $menu0->addItem(1, 'Text', ItrItem::sendText('Text message (for #USER_NAME#)'));
    $menu0->addItem(2, 'Text without menu', ItrItem::sendText('Text message without menu', true));
    $menu0->addItem(3, 'Open menu #1', ItrItem::openMenu(1));
    $menu0->addItem(0, 'Wait operator answer', ItrItem::sendText('Wait operator answer', true));

    $menu1 = new ItrMenu(1);
    $menu1->setText('Second menu (#1)');
    $menu1->addItem(2, 'Transfer to queue', ItrItem::transferToQueue('Transfer to queue'));
    $menu1->addItem(3, 'Transfer to user', ItrItem::transferToUser(1, false, 'Transfer to user #1'));
    $menu1->addItem(4, 'Transfer to bot', ItrItem::transferToBot('marta', true, 'Transfer to bot Marta', 'Marta not found :('));
    $menu1->addItem(5, 'Finish session', ItrItem::finishSession('Finish session'));
    $menu1->addItem(6, 'Exec function', ItrItem::execFunction(function($context){
        $result = restCommand('imbot.message.add', Array(
            "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
            "MESSAGE" => 'Function executed (action)',
        ), $_REQUEST["auth"]);
        writeToLog($result, 'Exec function');
    }, 'Function executed (text)'));
    $menu1->addItem(9, 'Back to main menu', ItrItem::openMenu(0));

    $itr = new Itr($portalId, $dialogId, 0, $userId);
    $itr->addMenu($menu0);
    $itr->addMenu($menu1);
    $itr->run(prepareText($message));

    return true;
}