28  /  166

imbot.register

Просмотров: 19859
Дата последнего изменения: 08.09.2023
Анна Кокина
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
1
2
3
4
5

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

Обратите внимание! Метод указан с использованием функции restCommand – это метод отправки данных в Битрикс24. Данный метод есть в ЭхоБоте и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.

Примечания:

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

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

Вызов метода

$result = restCommand('imbot.register', Array(

    'CODE' => 'newbot', // Строковой идентификатор бота, уникальный в рамках вашего приложения (обяз.)
    'TYPE' => 'B', // Тип, B – чат-бот, ответы поступают сразу, 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 для связи. НЕЛЬЗЯ использовать e-mail, дублирующий 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.



3
Курсы разработаны в компании «1С-Битрикс»
Доступна новая документация по REST: понятнее описания, больше примеров, удобнее поиск
Перейти