Процедура установки чата Webim на сайт в iframe

Для встраивания на сайт чат-окна сервиса Webim в iframe необходимо:

1. Настроить nginx. Подробнее об этом можно прочитать в этой статье.

2. Добавить на сайт элементы интерфейса:

   • Контейнер, содержащий iframe, в котором будет размещён виджет чата <iframe id="webim-chat-iframe" style="border: none">, элемент должен иметь id webim-chat-iframe и не заданный атрибут src (заполняется скриптом), на момент загрузки страницы контейнер должен быть скрыт.

   • Кнопку старта чата, на момент загрузки страницы она также должна быть скрыта, по клику на кнопку должен происходить вызов webim.api.chat.start().

   • Кнопку закрытия чата, предполагается, что она скрывается и показывается вместе с виджетом чата, по клику на кнопку должен происходить вызов webim.api.chat.close().

3. Добавить на страницу конфигурационный JavaScript-объект:

   webim = {
       accountName: "название_аккаунта",
       domain: "название_аккаунта.webim.ru",
       location: "название_размещения",
   };
   

   accountName — имя клиента в Webim:

   • у облачных клиентов accountName входит в домен вида <accountname>.webim.ru, по которому клиент авторизуется. Например, в домене mycompany.webim.ru доменом аккаунта будет mycompany.

   • у hosted-клиентов в качестве accountName выступает значение соответствующего параметра в файле main.ini. Примером указываемого по умолчанию accountName может служить mybank123.

   domain — домен аккаунта клиента в Webim:

   • у облачных клиентов домен имеет вид <accountname>.webim.ru. Пример: mycompany.webim.ru.

   • у hosted-клиентов домен имеет произвольный вид. Пример: chat.company.com.

   location — размещение аккаунта клиента в Webim. Не является обязательным.

4. При необходимости добавить объект webim_visitor в соответствии с документацией.

5. Имплементировать обработчики событий:

   webimHandlers = {
   
   onInit: function (event) {
     // получает на входе объект {online: true/false, onlineStatus: 'online'/'busy_online'/'offline'/'busy_offline'}
     // здесь следует инициализировать внешний вид кнопки старта чата в зависимости от статуса и сделать ее видимой
   },
   
   onChatShownStateChanged: function (event) {
     // получает на входе объект {shown: }
     // вызывается, когда необходимо скрыть/показать виджет чата, это может происходить как в ответ на действия пользователя,
     // так и на поступающую информацию от сервера (например, когда оператор переоткрыл закрытый посетителем чат)
     // здесь следует показать/скрыть контейнер с iframe
   },
   
   onChatReadChanged: function (event) {
     // получает на входе объект {read: }
     // вызывается, когда меняется статус прочитанности чата посетителем
     // здесь следует включать/выключать визуальную сигнализацию о непрочитанности, например "мигание" заголовком страницы
   },
   
   onTeleport: function (event) {
     // получает на входе объект {url: 'https://...'}
     // вызывается, когда оператор воcпользовался функцией "Телепорт" - перенаправление посетителя на заданную страницу
     // стандартное решение здесь - выполнить:
     // window.location.href = event.url;
   },
   
   onProvidedTokenNotFoundError: function () {
     // *не используется с iframe, но может быть использован в других случаях (обычный виджет чата или мобильное приложение)*
     // вызывается, когда auth_token не обнаружен (обрабатывает событие прихода ошибки от сервера Webim 'provided-auth-token-not-found' (см. Webim Realtime API))
     // в случае отсутствия auth_token, обработчик должен инициировать повторную отправку с бэкенда организации POST-запроса в Webim
   };
   

6. Необходимо добавить вызов webim.api.init() после полной загрузки страницы.

7. Подключить копию скрипта https://<account_name>.webim.ru/webim/js/v/iframe-helper.js. Вы можете осуществлять необходимые преобразования в Вашем коде. Для поддержки авторизации и выхода пользователя из системы без перезагрузки страницы сайта необходимо обновлять объект webim_visitor (присваивать null при выходе) и делать вызов webim.api.onProvidedVisitorChanged(). Работающий прототип можно посмотреть по ссылке https://<account_name>.webim.ru/webim/iframe-sample.php, где <account_name> - имя Вашего аккаунта Webim. Такую страницу можно открыть для любого аккаунта, указав в URL нужное имя домена.

8. При необходимости можно активировать параметр passthrough_last_visitor_activity_from_iframe в account-config - это позволит пробрасывать события о действиях, совершаемых клиентом (таких как авторизация пользователя), из iframe чата в основное окно сайта клиента.