JavaScript API виджета Webim

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

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

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

Серверные API (Stored Data API, Custom Channel API, Realtime API) описаны в отдельном разделе Webim API и не относятся к данному документу.

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

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

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

Также может использоваться отдельный объект webim_visitor для передачи данных авторизованного посетителя. Его формат описан в статье по Идентификации через подписанные поля.

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

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

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

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

accountName — имя аккаунта Webim. Для облачных клиентов входит в поддомен вида <account_name>.webim.ru.
domain — домен сервиса Webim для данного аккаунта (например, mycompany.webim.ru или произвольный домен для hosted-установки).
location — ключ (идентификатор) размещения, если в аккаунте используется несколько размещений.

Примеры подключения кнопки чата с использованием этого объекта приведены в этой статье.

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

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

Встроенный виджет (стандартная кнопка/окно чата) — виджет и JS-код находятся в одной странице.
Виджет в iframe — виджет загружается в iframe, а логика управления находится в родительской странице.

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

В стандартной схеме установка виджета выполняется по инструкции из этой статьи. На страницу добавляется:

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

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

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

Виджет в iframe

Для размещения чата в iframe используется схема из этой статьи. В родительской странице:

Создаётся контейнер <iframe id="webim-chat-iframe">, скрытый при загрузке.
Добавляются элементы интерфейса (кнопка старта, кнопка закрытия), которые вызывают webim.api.chat.start() и webim.api.chat.close() соответственно.
Определяются объекты webim и webim_visitor (при необходимости).
Имплементируются обработчики событий в объекте webim.handlers.
Подключается скрипт iframe-helper.js.
После полной загрузки страницы вызывается 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 рекомендуется:

Корректно пересчитать подпись полей посетителя (см. идентификация через подписанные поля).
Вызвать 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(url)`

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

Параметры:

url — строка с новым URL (обычно window.location.href).

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

корректное обновление контекста посещения в сервисе 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()`

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

Применение:

при клике на кнопку «Начать чат»;
при автоматическом открытии чата (например, при входе на определённую страницу — хотя массовое автозапускание на всех страницах не рекомендуется).

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

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

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

`webim.api.chat.close()`

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

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

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

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

`webim.api.chat.isActive()`

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

Ожидаемая семантика:

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)`

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

Параметры event:

online — булево значение, отражающее доступность операторов;
onlineStatus — строковый статус (online, busy_online, offline, busy_offline).

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

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

`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 и подпись полей описаны в разделе Идентификация авторизованных клиентов;
при изменении webim_visitor необходимо вызывать webim.api.onProvidedVisitorChanged() и корректно обновлять подпись;
при изменении webim_auth_token необходимо вызывать webim.api.onAuthTokenChanged(), чтобы виджет начал использовать актуальное значение токена без перезагрузки страницы;
для работы с файлами из чата следует использовать эндпоинт /file Stored Data API;
для сложной серверной логики и интеграций используется Webim Realtime API и API для обработчиков событий чата.

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

Последнее обновление страницы: 4 мая 2026 г.

JavaScript API виджета Webim

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

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

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

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

Виджет в iframe

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

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

webim.api.init()

webim.api.onProvidedVisitorChanged()

webim.api.onAuthTokenChanged()

webim.api.onUrlChange(url)

webim.api.setFocusState(isFocused)

webim.api.changeLocation(location)

webim.api.changeLang(lang)

Объект webim.api.chat

webim.api.chat.start()

webim.api.chat.close()

webim.api.chat.isActive()

Объект webim.api.button

Объект webim.api.invitation

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

webim.handlers.onInit(event)

webim.handlers.onChatShownStateChanged(event)

webim.handlers.onChatReadChanged(event)

webim.handlers.onTeleport(event)

webim.handlers.onProvidedTokenNotFoundError()

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

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

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

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

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

`webim.api.init()`

`webim.api.onProvidedVisitorChanged()`

`webim.api.onAuthTokenChanged()`

`webim.api.onUrlChange(url)`

`webim.api.setFocusState(isFocused)`

`webim.api.changeLocation(location)`

`webim.api.changeLang(lang)`

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

`webim.api.chat.start()`

`webim.api.chat.close()`

`webim.api.chat.isActive()`

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

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

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

`webim.handlers.onInit(event)`

`webim.handlers.onChatShownStateChanged(event)`

`webim.handlers.onChatReadChanged(event)`

`webim.handlers.onTeleport(event)`

`webim.handlers.onProvidedTokenNotFoundError()`