Особые требования

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

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качать его можно:

• c сервиса GitHub (itr.php).
• или взять в продукте «Битрикс24 в коробке» тут: \Bitrix\ImBot\Bot\OpenlinesMenuExample.

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

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

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

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

  

• Затем использовать сценарий Локальное приложение 4:

  

• Выбираем тип Серверное приложение. Можно сменить название бота вместо «Локальное приложение». Включаем опцию Использует только API и даем приложению права доступа, как минимум на Создание и управление Чат-ботами (без этих прав приложение не сможет зарегистрировать чат-бота), а также на Открытые линии (без этих прав приложение не сможет работать с открытыми линиями).

  

• Поскольку наш скрипт написан таким образом, что является обработчиком всех событий, то в форме приложения мы укажем обе ссылки на один и тот же URL.
• Нажмите кнопку Сохранить. Появятся дополнительные поля: Код приложения (client_id) и Ключ приложения (client_secret):

  

• Скопируйте данные из этих полей и вставьте в файл itr.php .
• В настройках бота нажмите Переустановить. Теперь он готов к работе.
• Обратите внимание, данный бот не публикует сообщения о том, что его пригласили на портале. Но после установки он будет доступен в настройках открытых линий, где нужно выбрать его ответственным и указать через какое время переводить разговор от чат-бота в очередь:

  

  Примечание. Клиент может переключиться на оператора раньше, отправив сообщение 0 (цифра "ноль") или выбрав пункт меню 0. Wait operator answer. Вообще, пользователь может нажать на 0 при любом чат-боте и пользователь будет перенаправлен на оператора, обрабатывать дополнительно это не требуется.

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

  

• Настроить собственное меню в боте 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;
  }