Просмотров: 10129
Дата последнего изменения: 12.07.2023
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
4
5
Регистрация приложения для чата
Приложения делятся на два типа: JS-команда и IFRAME-приложение.
Вызов метода для JS-команды
$result = restCommand('imbot.app.register', Array(
'BOT_ID' => 62, // Идентификатор бота владельца приложения для чата
'CODE' => 'echo', // Код приложения для чата
'JS_METHOD' => 'SEND',
'JS_PARAM' => '/help',
'ICON_FILE' => '/* base64 image */', // Иконка в base64
'CONTEXT' => 'BOT', // Контекст приложения
'EXTRANET_SUPPORT' => 'N', // Доступна ли команда пользователям экстранет, по умолчанию N
'LIVECHAT_SUPPORT' => 'N', // Поддержка онлайн-чата
'IFRAME_POPUP' => 'N', // iframe будет открыт с возможностью перемещения внутри мессенджера, переход между диалогами не будет закрывать такое окно.
'LANG' => Array( // Массив переводов, желательно указывать как минимум для RU и EN
Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Echobot BUTTON', 'DESCRIPTION' => 'Send help command'),
)
), $_REQUEST["auth"]);
Варианты для JS_METHOD
:
PUT
- вставка команды чат-боту в textarea, JS_PARAM
может содержать только текст команды и параметры к ней (разрешенные символы: a-z 0-9 - + _ / ).
SEND
- отправка команды чат-боту, JS_PARAM
может содержать только текст команды и параметры к ней (разрешенные символы a-z 0-9 - + _ / ).
CALL
- вызов телефонного номера.
SUPPORT
- открытие чат-бота техподдержки работающего через Открытые линии, в JS_PARAM
необходимо указать код открытой линии (32 символа).
Формат иконки ICON_FILE
:
- В данное поле необходимо передать base64 от вашей иконки, формат иконки подробно описан в документации.
- Обратите внимание, если данное поле не указано, то приложение будет доступно в системном диалоге "Приложения для чата".
Контекст CONTEXT
указывает, где будет доступно приложение:
ALL
– во всех чатах.
USER
– только в чатах Один-на-один.
CHAT
– только в групповых чатах.
BOT
– только у чат-бота, который установил приложение.
LINES
– только в чатах Открытых линий.
CALL
– только в чатах, созданных в рамках Телефонии.
К каждому контексту можно добавить постфикс -admin
, тогда приложение будет доступно в нужном контексте только администраторам Битрикс24.
Вызов метода для IFRAME-приложения
$result = restCommand('imbot.app.register', Array(
'BOT_ID' => 62, // Идентификатор бота владельца приложения для чата
'CODE' => 'echo', // Код приложения для чата
'IFRAME' => 'https://marta.bitrix.info/iframe/echo.php',
'IFRAME_WIDTH' => '350', // Желаемая ширина фрейма. Минимальное значение - 250px
'IFRAME_HEIGHT' => '150', // Желаемая высота фрейма. Минимальное значение - 50px
'HASH' => 'd1ab17949a572b0979d8db0d5b349cd2', // Токен для доступа к вашему фрейму для проверки подписи, 32 символа.
'ICON_FILE' => '/* base64 image */', // Иконка в base64
'CONTEXT' => 'BOT', // Контекст
'HIDDEN' => 'N', // Скрытое приложение или нет
'EXTRANET_SUPPORT' => 'N', // Доступна ли команда пользователям экстранет, по умолчанию N
'LIVECHAT_SUPPORT' => 'N', // Поддержка онлайн-чата
'IFRAME_POPUP' => 'N', // iframe будет открыт с возможностью перемещения внутри мессенджера, переход между диалогами не будет закрывать такое окно.
'LANG' => Array( // Массив переводов, желательно указывать как минимум для RU и EN
Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Echobot IFRAME', 'DESCRIPTION' => 'Open Echobot IFRAME app', 'COPYRIGHT' => 'Bitrix24'),
)
), $_REQUEST["auth"]);
Обратите внимание:
- Хоть вы при регистрации IFRAME-приложения и задаете размеры окна, оно может быть уменьшено приложением по фактически доступным размерам. Идеальный вариант – делать таким образом, чтобы оно вписывалось в минимальные размеры и могло свободно адаптироваться к увеличению и уменьшению, это будет очень важно для мобильных устройств.
- Cсылка на
IFRAME
обязательно должна вести на сайт с активным HTTPS-сертификатом. Правила разработки IFRAME-обработчика и ограничения вы можете прочитать в документации.
- Обязательно используйте проверки хешей перед выполнением любых операций.
- Приложения доступны только после перезагрузки страницы или после служебного хита на сервер (на разных установках по разному, от 15 до 26 минут). Приложение появится мгновенно только при взаимодействии с контекстной кнопкой.
- В значения
IFRAME_WIDTH
и IFRAME_HEIGHT
вы указываете желаемые значения ширины и высоты окна приложения. Окно приложения будет уменьшено до размера окна мессенджера, если окно мессенджера окажется меньше. Если же, наоборот, больше, то будут использованы желаемые размеры для приложения.
- В случае вызова приложения из контекста (клавиатура или меню), оно будет вызвано в контекстном режиме. В этом режиме значение
IFRAME_POPUP
будет игнорироваться.
Результат выполнения
Числовой идентификатор созданного приложения APP_ID
или ошибка.
Возможные коды ошибок
Код |
Описание |
BOT_ID_ERROR |
Чат-бот не найден. |
APP_ID_ERROR |
Приложение для чата не принадлежит этому rest-приложению. Работать можно только с приложениями для чата, установленными в рамках текущего rest-приложения. |
IFRAME_HTTPS |
Ссылка на IFRAME обязательно должна быть на сайт с активным HTTPS-сертификатом. |
HASH_ERROR |
Вы не указали хеш для приложения. Мы рекомендуем использовать уникальных хеш для каждого IFRAME и каждой установки. |
PARAMS_ERROR |
Ошибка при указании JS-команды или IFRAME-параметров. |
LANG_ERROR |
Не переданы языковые фразы для видимой команды. |
WRONG_REQUEST |
Что-то пошло не так. |
|