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

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 для передачи данных авторизованного посетителя. Его формат описан в статье по идентификации через подписанные поля.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Виджет в iframe

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

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

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

  3. Определяются объекты webim и webim_visitor (при необходимости).

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

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

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

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

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

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:

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