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

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

  1. Настроить nginx. Подробнее об этом можно прочитать в [этой статье](https://webim.ru/kb/devops/admin-iframe.html).

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

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

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

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

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

    ```
    webim = {
        accountName: "название_аккаунта",
        domain: "название_аккаунта.webim.ru",
        location: "название_размещения",
        fallbackDomains: ["резервный-домен-1.local", "резервный-домен-2.local"]
    };
    ```

    `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.local`.

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

    `fallbackDomains` — опциональный список резервных доменов. Укажите дополнительные домены, на которые будут отправляться запросы, если основной домен из поля `domain` недоступен. Пример: `["domain1.local", "domain2.local", "domain3.local"]`. Поле не является обязательным.

    Если в [редакторе настроек account config](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html) задан параметр `allowed_domains`, перечислите в нём все резервные домены из `fallbackDomains` (одной строкой через запятую), иначе сервер отклонит запросы с этих доменов. В этот же список нужно включить **все** сайты, где разрешён чат, а не только резервные для `fallbackDomains` — иначе виджет перестанет открываться на пропущенных доменах. Если `allowed_domains` не задан (значение по умолчанию), дополнительная настройка не требуется. Формат и ограничения whitelist описаны в [параметрах настроек сервера](https://webim.ru/kb/devops/server-account-config-parameters.html).

  1. При необходимости добавить объект `webim_visitor` в соответствии с [документацией](https://webim.ru/kb/dev/identification/id-2-0.html). Если для аккаунта включена [маршрутизация посетителей](https://webim.ru/kb/for-admins/visitor-routing.html), на родительской странице можно задать `window.chat_routing_fields` — скрипт `iframe-helper.js` передаст его в iframe так же, как `webim_visitor` и `webim_auth_token`.

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

    ```
    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://...'}
      // вызывается, когда оператор воспользовался функцией "Телепорт" - перенаправление посетителя на заданную страницу
      // стандартное решение здесь - выполнить:
      // window.location.href = event.url;
    },

    onProvidedTokenNotFoundError: function () {
      // *не используется с iframe, но может быть использован в других случаях (обычный виджет чата или мобильное приложение)*
      // вызывается, когда auth_token не обнаружен (обрабатывает событие прихода ошибки от сервера Webim 'provided-auth-token-not-found' (см. Webim Realtime API))
      // в случае отсутствия auth_token, обработчик должен инициировать повторную отправку с бэкенда организации POST-запроса в Webim
    };
    ```

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

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

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

---

Источник: https://webim.ru/kb/dev/iframe.html