Перейти к содержанию

Процедура установки чата 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 чата в основное окно сайта клиента.