Просмотров: 15315
Дата последнего изменения: 08.09.2023
Сложность урока:
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.