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