131  /  166

imbot.app.register

Просмотров: 12862
Дата последнего изменения: 12.07.2023
Анна Кокина
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
1
2
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"]);

Обратите внимание:
  1. Хоть вы при регистрации IFRAME-приложения и задаете размеры окна, оно может быть уменьшено приложением по фактически доступным размерам. Идеальный вариант – делать таким образом, чтобы оно вписывалось в минимальные размеры и могло свободно адаптироваться к увеличению и уменьшению, это будет очень важно для мобильных устройств.
  2. Cсылка на IFRAME обязательно должна вести на сайт с активным HTTPS-сертификатом. Правила разработки IFRAME-обработчика и ограничения вы можете прочитать в документации.
  3. Обязательно используйте проверки хешей перед выполнением любых операций.
  4. Приложения доступны только после перезагрузки страницы или после служебного хита на сервер (на разных установках по разному, от 15 до 26 минут). Приложение появится мгновенно только при взаимодействии с контекстной кнопкой.
  5. В значения IFRAME_WIDTH и IFRAME_HEIGHT вы указываете желаемые значения ширины и высоты окна приложения. Окно приложения будет уменьшено до размера окна мессенджера, если окно мессенджера окажется меньше. Если же, наоборот, больше, то будут использованы желаемые размеры для приложения.
  6. В случае вызова приложения из контекста (клавиатура или меню), оно будет вызвано в контекстном режиме. В этом режиме значение 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 Что-то пошло не так.


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