# JavaScript API виджета Webim

В данной статье описывается **visitor JavaScript API сервиса Webim**, доступный в браузере через глобальный объект `webim`.

Этот API предназначен для:

  * управления виджетом чата со стороны страницы сайта (открытие/закрытие чата, переключение языка и размещения, уведомление об изменениях в профиле посетителя);

  * обработки клиентских событий (инициализация, изменение статуса отображения чата, «телепортация» и т. п.) через набор обработчиков `webim.handlers` / глобальный объект `webimHandlers`.

Серверные API (Stored Data API, Custom Channel API, Realtime API) описаны в отдельном разделе [Webim API](https://webim.ru/kb/dev/api/) и не относятся к данному документу.

## Структура объекта `webim`

После подключения стандартного скрипта виджета (`button.js` либо `iframe-helper.js`) на странице становится доступен глобальный объект:

  * `webim` — конфигурация и точка входа для JS API.

  * `webim.api` — методы управления виджетом и вложенные объекты `chat`, `button`, `invitation`.

  * `webim.handlers` — набор callback-функций (обработчиков событий), используемых виджетом; значения берутся из глобального объекта `webimHandlers`.

Также может использоваться отдельный объект `webim_visitor` для передачи данных авторизованного посетителя. Его формат описан в статье по [Идентификации через подписанные поля](https://webim.ru/kb/dev/identification/id-2-0.html).

Для авторизации по токену (server-to-server) может использоваться глобальная переменная `webim_auth_token`. Рекомендуется устанавливать `webim_auth_token` на странице **до подключения** скрипта виджета. Если токен был установлен или изменён **после загрузки страницы** (без перезагрузки), необходимо вызвать метод `webim.api.onAuthTokenChanged()`.

Для [маршрутизации посетителей](https://webim.ru/kb/for-admins/visitor-routing.html) на странице можно задать объект `window.chat_routing_fields`. Он нужен, в том числе, при идентификации по токену: поля из `provide_visitor_fields` виджету недоступны. Формат и приоритет описаны в статье [Идентификация через подписанные поля](https://webim.ru/kb/dev/identification/id-2-0.html#chat-routing-fields).

### Базовая конфигурация `webim`

Минимальный конфигурационный объект `webim` выглядит так:

```
webim = {
  accountName: 'имя_аккаунта',
  domain: 'домен_аккаунта',
  location: 'ключ_размещения' // необязательно
};
```

  * `accountName` — имя аккаунта Webim. Для облачных клиентов входит в поддомен вида `<account_name>.webim.ru`.

  * `domain` — домен сервиса Webim для данного аккаунта (например, `mycompany.webim.ru` или произвольный домен для hosted-установки).

  * `location` — ключ (идентификатор) размещения, если в аккаунте используется несколько размещений.

Примеры подключения кнопки чата с использованием этого объекта приведены в [этой статье](https://webim.ru/kb/dev/link-button-start-chat.html).

## Режимы работы JavaScript API

Visitor JS API работает в двух основных режимах:

  1. **Встроенный виджет (стандартная кнопка/окно чата)** — виджет и JS-код находятся в одной странице.

  1. **Виджет в iframe** — виджет загружается в iframe, а логика управления находится в родительской странице.

### Встроенный виджет

В стандартной схеме установка виджета выполняется по инструкции из [этой статьи](https://webim.ru/kb/getting-started/install-button.html). На страницу добавляется:

  * объект `webim` с конфигурацией;

  * скрипт `button.js`, который инициализирует виджет и объект `webim.api`.

В этом режиме:

  * Все методы `webim.api.*` доступны в той же странице.

  * Инициализация выполняется самим скриптом кнопки; метод `webim.api.init()` в этой схеме не используется (он нужен только для варианта с iframe).

  * Обработчики событий удобно задавать через глобальный объект `webimHandlers` (см. ниже).

### Виджет в iframe

Для размещения чата в iframe используется схема из [этой статьи](https://webim.ru/kb/dev/iframe.html). В родительской странице:

  1. Создаётся контейнер `<iframe id="webim-chat-iframe">`, скрытый при загрузке.

  1. Добавляются элементы интерфейса (кнопка старта, кнопка закрытия), которые вызывают `webim.api.chat.start()` и `webim.api.chat.close()` соответственно.

  1. Определяются объекты `webim` и `webim_visitor` (при необходимости). Для маршрутизации при идентификации по токену задайте также `window.chat_routing_fields`.

  1. Имплементируются обработчики событий в объекте `webim.handlers`.

  1. Подключается скрипт `iframe-helper.js`.

  1. После полной загрузки страницы вызывается `webim.api.init()`.

В этом режиме:

  * `webim.api.chat.start()` и `webim.api.chat.close()` управляют показом/скрытием iframe с виджетом.

  * Обработчик `webimHandlers.onChatShownStateChanged` используется для синхронизации видимости контейнера iframe с состоянием виджета (внутри виджета он доступен как `webim.handlers.onChatShownStateChanged`).

  * Обработчик `webim.handlers.onProvidedTokenNotFoundError` в iframe-схеме не используется; он актуален для обычного виджета и мобильных приложений.

  * При включении параметра `passthrough_last_visitor_activity_from_iframe` в `account-config` события активности внутри iframe (например, авторизация) могут пробрасываться в основное окно сайта.

## Интерфейс `webim.api`

### Методы верхнего уровня `webim.api`

#### `webim.api.init()`

Инициализирует JS API и виджет чата **в схеме с iframe**. Метод доступен, когда на странице подключён `iframe-helper.js`, и должен быть вызван после того, как на странице:

  * создан объект `webim` с корректной конфигурацией;

  * при необходимости определён объект `webim_visitor`;

  * задан глобальный объект `webimHandlers` с обработчиками.

В схеме с iframe вызов `webim.api.init()` выполняется явно после полной загрузки страницы. В стандартной схеме с подключением только `button.js` отдельного публичного вызова `webim.api.init()` нет — инициализация выполняется автоматически самим скриптом кнопки.

Метод не принимает аргументов и не возвращает значения. Результатом инициализации является:

  * установление соединения с сервисом Webim;

  * вызов `webim.handlers.onInit(event)` (при его наличии).

#### `webim.api.onProvidedVisitorChanged()`

Уведомляет виджет о том, что объект `webim_visitor` был изменён.

Использование:

  * при авторизации пользователя на сайте после загрузки страницы;

  * при изменении полей профиля (имя, телефон, email и т. п.);

  * при выходе пользователя из аккаунта (в этом случае `webim_visitor` обычно сбрасывается в `null`).

После изменения `webim_visitor` рекомендуется:

  1. Корректно пересчитать подпись полей посетителя (см. [идентификация через подписанные поля](https://webim.ru/kb/dev/identification/id-2-0.html)).

  1. Вызвать `webim.api.onProvidedVisitorChanged()`.

Если значения полей передаются пустыми строками (например, `phone: ''`), посетитель не сможет заполнить эти поля через виджет чата в дальнейшем. Поэтому не следует передавать пустые значения только ради «резервирования» полей.

#### `webim.api.onAuthTokenChanged()`

Уведомляет виджет о том, что значение глобальной переменной `webim_auth_token` было изменено.

Доступность:

  * метод поддерживается, начиная с **Webim Server 10.8**.

Использование:

  * при установке/обновлении токена авторизации (`webim_auth_token`) без перезагрузки страницы;

  * при выходе пользователя из системы, если требуется сбросить ранее переданный токен.

Метод не принимает аргументов и не возвращает значения.

Рекомендации по использованию:

  * сначала обновите значение `window.webim_auth_token`, затем вызовите `webim.api.onAuthTokenChanged()` — иначе виджет может продолжать использовать предыдущее значение токена до перезагрузки страницы;

  * чтобы «сбросить» токен, установите `window.webim_auth_token` в `null` (или удалите переменную) и вызовите `webim.api.onAuthTokenChanged()`.

Примеры:

```
window.webim_auth_token = 'NEW_TOKEN_VALUE';
webim.api.onAuthTokenChanged();
```

```
window.webim_auth_token = null;
// или: delete window.webim_auth_token;
webim.api.onAuthTokenChanged();
```


#### `webim.api.onUrlChange()` { #webim-api-on-url-change }

Уведомляет виджет о смене URL страницы без её перезагрузки (например, в SPA-приложениях). Рекомендуется вызывать данный метод при каждом изменении маршрута.

Метод не принимает аргументов: виджет сам считывает текущий адрес страницы. Поэтому вызывать его нужно **после** того, как адрес уже изменён (`history.pushState()`, `history.replaceState()` или переход внутри роутера).

Ожидаемый эффект:

  * корректное обновление контекста посещения в сервисе Webim (приоритетные страницы, источники и т. п.);

  * корректная работа автоприглашений и логики маршрутизации, зависящих от URL.

#### `webim.api.setFocusState(isFocused)`

Передаёт виджету информацию о том, активно ли в данный момент окно (вкладка) сайта.

Параметры:

  * `isFocused` — булево значение:

    * `true` — окно активно (пользователь взаимодействует с вкладкой);

    * `false` — окно неактивно (например, пользователь перешёл на другую вкладку).

Ожидаемый эффект:

  * более точная оценка активности посетителя;

  * использование этой информации в логике тайм-аутов и отправки уведомлений.

#### `webim.api.changeLocation(location)`

Позволяет динамически переключать текущее размещение, с которым связан виджет, без полной перезагрузки страницы.

Параметры:

  * `location` — ключ (идентификатор) размещения, совпадающий со значением, указанным в настройках размещений.

Применение:

  * на сайтах, где одно и то же приложение обслуживает несколько «виртуальных» размещений;

  * для динамического изменения дизайна и поведения чата при переходе пользователя в разные разделы сайта.

#### `webim.api.changeLang(lang)`

Меняет язык интерфейса виджета в рантайме.

Параметры:

  * `lang` — строковой код языка (например, `ru`, `en`, `pt`), соответствующий языкам, включённым в настройках сервиса.

Применение:

  * на многоязычных сайтах, когда язык интерфейса сайта переключается без перезагрузки страницы;

  * при первичной установке языка, отличного от языка по умолчанию.

### Объект `webim.api.chat`

Объект `webim.api.chat` отвечает за управление жизненным циклом текущего чата на стороне посетителя.

#### `webim.api.chat.start()` { #chat-start }

Открывает виджет и инициирует диалог.

Применение:

  * при клике на кнопку «Начать чат»;

  * при автоматическом открытии чата (например, при входе на определённую страницу — хотя массовое автозапускание на всех страницах не рекомендуется). Готовые примеры кода приведены в статье [Как открыть страницу сайта сразу с развёрнутым чатом](https://webim.ru/kb/dev/open-chat-on-page-load.html).

Особенности:

  * В режиме iframe метод должен быть привязан к пользовательскому действию (клик по кнопке), после чего через обработчик `onChatShownStateChanged` следует показать контейнер с iframe.

  * В стандартном режиме виджет открывается в миниатюрном окне или отдельном окне в соответствии с логикой, описанной в статье [Логика открытия виджета](https://webim.ru/kb/dev/widget-open-logic.html).

Метод не возвращает значения.

#### `webim.api.chat.close()`

Закрывает окно виджета на стороне посетителя.

Важно отличать:

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

  * окончательное закрытие диалога в терминах сервера (например, по тайм-ауту или действию оператора) — описано в статье [Логика обработки чатов](https://webim.ru/kb/faq/chat-processing-logic.html).

Обработчик закрытия чата на стороне сервера срабатывает только на окончательное закрытие диалога.

#### `webim.api.chat.isActive()` { #chat-is-active }

Возвращает булево значение, отражающее наличие активного диалога у посетителя. Проверяется состояние текущей сессии посетителя:

  * `true` — сессия находится в состоянии чата, то есть у посетителя есть незавершённый диалог (независимо от того, открыт ли сейчас виджет);

  * `false` — во всех остальных случаях: диалог ещё не начинался, уже полностью закрыт либо сессия находится в другом состоянии (например, показывается приглашение).

Возможные сценарии использования:

  * не открывать чат автоматически, если у посетителя уже есть активный диалог;

  * менять поведение кнопки (например, «Продолжить чат» вместо «Начать чат»).

### Объект `webim.api.button`

На стороне страницы за отображение кнопки запуска чата обычно отвечает пользовательский HTML-элемент (кнопка, ссылка и т. п.), а состояние кнопки управляется через обработчики событий (например, `onInit`) и манипуляции с DOM, как описано в статье по iframe-интеграции.

Рекомендуется:

  * использовать `webim.handlers.onInit` для установки начального состояния кнопки (онлайн/офлайн, видимость);

  * явно управлять показом/скрытием элемента кнопки через собственный JS-код с учётом статуса, переданного в `onInit`.

### Объект `webim.api.invitation`

Объект предназначен для работы с автоприглашениями и приглашениями к чату.

За детальную реализацию управление приглашениями может отвечать как клиентский код (через события и DOM), так и серверные настройки автоприглашений.

## Обработчики событий `webim.handlers`

После подключения скрипта и до вызова `webim.api.init()` (в схеме с iframe) на странице нужно определить глобальный объект `webimHandlers` с обработчиками событий. Внутри виджета эти функции доступны как `webim.handlers.*`. Далее для краткости используется нотация `webim.handlers.<имя_обработчика>`, но объявлять обработчики следует в объекте `webimHandlers`.

Ниже приведён перечень часто используемых обработчиков.

### `webim.handlers.onInit(event)` {: #on-init }

Вызывается после инициализации виджета.

Параметры `event`:

  * `status` — строковый статус операторов (`online`, `busy_online`, `offline`, `busy_offline`);

  * `online` — булево значение, устаревшее. Равно `true` только при статусе `online`, поэтому для состояния `busy_online` (операторы на месте, но все заняты) вернёт `false`. В новом коде используйте `status`.

Типичные действия в обработчике:

  * установить внешний вид кнопки старта чата в зависимости от статуса;

  * сделать кнопку видимой;

  * при необходимости выполнить дополнительную инициализацию интерфейса.

### `webim.handlers.onChatShownStateChanged(event)`

Вызывается при изменении необходимости показывать/скрывать виджет.

Параметры `event`:

  * `shown` — булево значение:

    * `true` — виджет должен быть показан;

    * `false` — виджет должен быть скрыт.

В режиме iframe:

  * при `shown: true` следует показать контейнер с iframe и, при необходимости, кнопку закрытия чата;

  * при `shown: false` — скрыть их.

Событие может приходить как в ответ на действие пользователя, так и по инициативе сервера (например, если оператор переоткрыл закрытый посетителем чат).

### `webim.handlers.onChatReadChanged(event)`

Вызывается при изменении состояния прочитанности чата на стороне посетителя.

Параметры `event`:

  * `read` — булево значение:

    * `true` — все сообщения прочитаны;

    * `false` — есть непрочитанные сообщения.

  * `unreadMsgCnt` — целое число, количество непрочитанных сообщений в текущем чате.

Типичные действия:

  * управление индикацией непрочитанных сообщений (подсветка кнопки, «мигание» заголовка страницы, показ бейджа количества и т. п., в том числе с использованием `event.unreadMsgCnt`).

### `webim.handlers.onTeleport(event)`

Вызывается при использовании оператором функции «Телепортация» (перевод посетителя на другую страницу).

Параметры `event`:

  * `url` — строка с целевым адресом.

Типичное поведение:

```
window.location.href = event.url;
```


При необходимости можно реализовать более сложную логику (например, маршрутизацию внутри SPA).

### `webim.handlers.onProvidedTokenNotFoundError()`

Вызывается при ошибке `provided-auth-token-not-found` на стороне сервера Webim, когда ожидаемый `auth_token` не обнаружен.

Особенности:

  * В интеграции через iframe данный обработчик не применяется (в статье по iframe это указано явно).

  * В стандартном виджете или мобильных приложениях в этом обработчике обычно инициируется повторная отправка `auth_token` с бэкенда организации (например, через Realtime API).

Рекомендуется:

  * логировать такие случаи для последующей диагностики;

  * инициировать повторную авторизацию и передачу токена.

## Взаимодействие с идентификацией и серверными API

Visitor JS API тесно связан с механизмом идентификации и серверными API:

  * объект `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` (см. [поля для маршрутизации](https://webim.ru/kb/dev/identification/id-2-0.html#chat-routing-fields));

  * при изменении `webim_visitor` необходимо вызывать `webim.api.onProvidedVisitorChanged()` и корректно обновлять подпись;

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

  * для работы с файлами из чата следует использовать эндпоинт `/file` [Stored Data API](https://webim.ru/kb/dev/api/stored-data/methods-description-v4.html);

  * для сложной серверной логики и интеграций используется [Webim Realtime API](https://webim.ru/kb/dev/api/realtime-2.0.html) и [API для обработчиков событий чата](https://webim.ru/kb/dev/chat-handlers/overview.html).

---

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

---

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