20  /  46

Работа с чат-ботами

Просмотров: 4554 (Статистика ведётся с 06.02.2017)

Примечание: Функция restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.


Внимание! Для работы ботов должен быть обеспечен доступ к marta.bitrix.info с портала или сайта.

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


Регистрация чат-бота

Rest-метод: imbot.register

Вызов метода:
$result = restCommand('imbot.register', Array(

    'CODE' => 'newbot', // Строковой идентификатор бота, уникальный в рамках вашего приложения (обяз.)
    'TYPE' => 'H', // Тип бота, B - чат-бот, ответы поступают сразу, H - человек, ответы поступают с задержкой от 2-х до 10 секунд, O - чат-бот для Открытых линий, S - чат-бот с повышенными привилегиями (supervisor)
    'EVENT_HANDLER' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик событий поступивших от сервера, см. Обработчики событий ниже (обяз).
    'OPENLINE' => 'Y', // Включение режима поддержки Открытых линий, можно не указывать, если TYPE = 'O'
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков
    'PROPERTIES' => Array( // Личные данные чат-бота (обяз.)
        'NAME' => 'NewBot', // Имя чат-бота (обязательное одно из полей NAME или LAST_NAME)
        'LAST_NAME' => '', // Фамилия чат-бота (обязательное одно из полей NAME или LAST_NAME)
        'COLOR' => 'GREEN', // Цвет чат-бота для мобильного приложения RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN,  AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
        'EMAIL' => 'test@test.ru', // E-mail для связи 
        'PERSONAL_BIRTHDAY' => '2016-03-11', // День рождения в формате YYYY-mm-dd
        'WORK_POSITION' => 'Мой первый бот', // Занимаемая должность, используется как описание чат-бота
        'PERSONAL_WWW' => 'http://test.ru', // Ссылка на сайт
        'PERSONAL_GENDER' => 'F', // Пол чат-бота, допустимые значения M -  мужской, F - женский, пусто, если не требуется указывать
        'PERSONAL_PHOTO' => '/* base64 image */', // Аватар чат-бота - base64
    )

), $_REQUEST["auth"]);
Обязательные поля:
CODE - строковой идентификатор бота, уникальный в рамках вашего приложения.
PROPERTIES - массив с личными данными чат-бота.
EVENT_HANDLER - ссылка на обработчик события отправки сообщения чат-боту.
или
EVENT_MESSAGE_ADD - ссылка на обработчик события отправки сообщения чат-боту.
EVENT_WELCOME_MESSAGE - ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат.
EVENT_BOT_DELETE - ссылка на обработчик события удаления чат-бота со стороны клиента.

Результат выполнения: числовой идентификатор созданного бота BOT_ID или ошибка.

Обработчики событий:
Если вам требуется обрабатывать события с помощью разных обработчиков, то вместо EVENT_HANDLER вы можете задать каждый обработчик индивидуально:
'EVENT_MESSAGE_ADD' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события отправки сообщения чат-боту
'EVENT_WELCOME_MESSAGE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат
'EVENT_BOT_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события удаления чат-бота со стороны клиента
'EVENT_MESSAGE_UPDATE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события изменения
'EVENT_MESSAGE_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события удаления сообщений

Ссылки по теме:

Rest API - События установки и обновления

Возможные ошибки:

Код ошибкиОписание ошибки
EVENT_MESSAGE_ADD_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_WELCOME_MESSAGE_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_BOT_DELETE_ERROR Ссылка обработчик события невалидная или не указана.
CODE_ERROR Не указан строковый идентификатор чат-бота.
NAME_ERROR Не указано одно из обязательных полей NAME или LAST_NAME чат-бота.
WRONG_REQUEST Что-то пошло не так.
MAX_COUNT_ERROR Достигнуто максимальное количество зарегистрированных ботов для одного приложения.

Чат-бот с повышенными привилегиями (supervisor) - это бот, получающий доступ ко всем сообщениям в чатах, где он состоит (ко всем, если его пригласили с доступом к истории, и к новым, если доступ к истории ему не доступен).

Для создания чат-бота с повышенными привилегиями в метод imbot.register в поле TYPE укажите тип S.

Обратите внимание, если это не требуется логикой вашего приложения, то рекомендуется отвечать боту на сообщения пользователя только при упоминании этого чат-бота. Проверить это можно по полю TO_USER_ID, которое будет передано в событие.


Внимание! Если планируется устанавливать более одного чат-бота в рамках одного приложения: Bitrix24 Rest накладывает ограничение на работу с обработчиками событий - обработчик может быть только один на одно приложение. Поэтому при регистрации второго чат-бота ссылки на обработчики EVENT_MESSAGE_ADD, EVENT_WELCOME_MESSAGE и EVENT_BOT_DELETE должны быть такими же, как и у первого бота.

Если необходимо обрабатывать несколько ботов в рамках одного приложения, то необходимо предусмотреть это внутри обработчика событий. Для этого при поступлении события передается массив ботов, чтобы можно было корректно их обработать.

Максимальное количество ботов для одного приложения: 5.



Удаление чат-бота из системы

Внимание! Все чаты один-на-один данного чат-бота с пользователями будут утеряны.

Rest-метод: imbot.unregister

Вызов метода:
$result = restCommand('imbot.unregister', Array(

    'BOT_ID' => 39 // числовой идентификатор бота
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков

), $_REQUEST["auth"]);
Результат выполнения: true или ошибка.

Ссылки по теме:

Rest API - События установки и обновления

Возможные ошибки:

Код ошибкиОписание ошибки
BOT_ID_ERROR Чат-бот не найден.
APP_ID_ERROR Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.


Обновление данных бота

Rest-метод: imbot.update

Вызов метода:
$result = restCommand('imbot.update', Array(

    'BOT_ID' => 39, // Идентификатор чат-бота, которого нужно изменить (обяз.)
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков
    'FIELDS' => Array( // Данные для обновления (обяз.)
        'CODE' => 'newbot', // Строковой идентификатор чат-бота, уникальный в рамках вашего приложения 
        'EVENT_HANDLER' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик событий поступивших от сервера, см. Обработчики событий ниже (обяз).
        'PROPERTIES' => Array( // Обязательное при обновлении данных бота
            'NAME' => 'UpdatedBot', // Имя чат-бота 
            'LAST_NAME' => '', // Фамилия чат-бота 
            'COLOR' => 'MINT', // Цвет чат-бота для мобильного приложения RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME,  BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
            'EMAIL' => 'test2@test.ru', // E-mail для связи
            'PERSONAL_BIRTHDAY' => '2016-03-12', // День рождения в формате YYYY-mm-dd
            'WORK_POSITION' => 'Мой второй бот', // Занимаемая должность, используется как описание чат-бота
            'PERSONAL_WWW' => 'http://test2.ru', // Ссылка на сайт
            'PERSONAL_GENDER' => 'M', // Пол бота, допустимые значения M  - мужской, F - женсикй, пусто, если не требуется указывать
            'PERSONAL_PHOTO' => '/* base64 image */', // Аватар чат-бота - base64
        )
    )

), $_REQUEST["auth"]);
Обязательные поля:
BOT_ID - идентификатор чат-бота, которого нужно изменить.
FIELDS - массив с данными для обновления.
PROPERTIES - массив с личными данными чат-бота.
EVENT_HANDLER - ссылка на обработчик события отправки сообщения чат-боту.
или
EVENT_MESSAGE_ADD - ссылка на обработчик события отправки сообщения чат-боту.
EVENT_WELCOME_MESSAGE - ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат.
EVENT_BOT_DELETE - ссылка на обработчик события удаления чат-бота со стороны клиента.

Результат выполнения: true или ошибка.

Обработчики событий:
Если вам требуется обрабатывать события с помощью разных обработчиков, то вместо EVENT_HANDLER вы можете задать каждый обработчик индивидуально:
'EVENT_MESSAGE_ADD' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события отправки сообщения чат-боту
'EVENT_WELCOME_MESSAGE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат
'EVENT_BOT_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события удаления чат-бота со стороны клиента
'EVENT_MESSAGE_UPDATE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события изменения
'EVENT_MESSAGE_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события удаления сообщений

Ссылки по теме:

Rest API - События установки и обновления

Возможные ошибки:

Код ошибкиОписание ошибки
BOT_ID_ERROR Чат-бот не найден.
APP_ID_ERROR Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
EVENT_MESSAGE_ADD_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_WELCOME_MESSAGE_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_BOT_DELETE_ERROR Ссылка обработчик события невалидная или не указана.
NAME_ERROR Не указано одно из обязательных полей NAME или LAST_NAME чат- бота.
WRONG_REQUEST Что-то пошло не так.

Метод imbot.update больше не поддерживает изменение полей TYPE и OPENLINE (im 17.5.10).



Получение доступных чат-ботов

Rest-метод: imbot.bot.list

Вызов метода:
$result = restCommand('imbot.bot.list', Array(
), $_REQUEST["auth"]);
Результат выполнения: массив массивов, содержащий данные по чат-ботам:
  • ID - идентификатор бота.
  • NAME - имя чат-бота.
  • CODE - внутренний код.
  • OPENLINE - поддерживает или нет открытые линии.


2
Курсы разработаны в компании «1С-Битрикс»