Создание приложения

Приложения делятся на два типа: JS-команда и IFRAME-приложение.

Расскажем об API-методах работы c приложениями.

Регистрация приложения для чата

Rest-метод: imbot.app.register

Вызов метода для 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	Что то пошло не так.

Удаление приложения для чата

Rest-метод: imbot.app.unregister

Вызов метода:

$result = restCommand('imbot.app.unregister', Array(

    'APP_ID' => 13, // идентификатор команды для удаления

), $_REQUEST["auth"]);

Результат выполнения: true или ошибка.

Возможные ошибки:

Код ошибки	Описание ошибки
CHAT_APP_ID_ERROR	Приложение не найдено.
APP_ID_ERROR	Приложение для чата не принадлежит этому rest-приложению, работать можно только с приложениями для чата, установленными в рамках текущего rest-приложения.
WRONG_REQUEST	Что то пошло не так.

Обновление данных о приложении в чате

Обратите внимание, обязательными полями является идентификатор приложения и одно из нужных полей для редактирования. Если указать методы JS и IFRAME в одной команде, будут использованы только JS.

Rest-метод: imbot.app.update

Вызов метода:

$result = restCommand('imbot.app.update', Array(

   'APP_ID' => 13, // идентификатор чата
   'FIELDS' => Array(
      'IFRAME' => 'https://marta.bitrix.info/iframe/echo.php',
      'IFRAME_WIDTH' => '350', // желаемая ширина фрейма. Минимальное значение - 250px
      'IFRAME_HEIGHT' => '150', // желаемая высота фрейма. Минимальное значение - 50px
       'JS_METHOD' => 'SEND', 
       'JS_PARAM' => '/help', 
      'HASH' => 'register', // токен для доступа к вашему фрейму, 32 символа. 
       '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 IFRAME', 'DESCRIPTION' => 'Open Echobot IFRAME app', 'COPYRIGHT' => 'Bitrix24'), 
      )
   )
), $_REQUEST["auth"]);

Результат выполнения: true или ошибка.

Возможные ошибки:

Код ошибки	Описание ошибки
CHAT_APP_ID_ERROR	Приложение не найдено.
APP_ID_ERROR	Приложение для чата не принадлежит этому rest-приложению, работать можно только с приложениями для чата, установленными в рамках текущего rest-приложения.
IFRAME_HTTPS	Ссылка на `IFRAME` обязательно должна быть на сайт с активным HTTPS-сертификатом.
WRONG_REQUEST	Что то пошло не так.

Курсы разработаны в компании «1С-Битрикс»