Методы виджета#

После подключения скрипта виджет публикует глобальный объект window.apxChat для управления чатом из кода страницы. Метод init() доступен сразу, остальные — после монтирования React-компонента.

Подключение#

<script src="https://api.apx.chat/static/widget.js" async></script>
<script>
  window.addEventListener('load', function () {
    window.apxChat.init('ВАШ_ТОКЕН');
  });
</script>

Два разных токена#

Часто путают токен в init() и токен в setToken() — это разные вещи с разным назначением:

init(token, client?, options?)#

Первичная инициализация виджета. Делает HTTP-запрос на сервер, получает конфиг (тема, дизайн, аналитика, операторы), создаёт DOM-контейнер #apx-chat-root и монтирует в него React-приложение.

window.apxChat.init(
  '1430a564bc7ccfeb0093d2302548a0fb',
  'user-42',
  {
    proxyApiUrl: 'https://yourdomain.com/chat-api',
    proxyWidgetUrl: 'https://yourdomain.com/chat-widget',
  },
);

open()#

Открывает окно чата. Полезно, когда нужно открыть чат по своей кнопке на сайте (например, «Связаться с нами» в шапке), а не только по дефолтной круглой кнопке виджета.

document.getElementById('support-btn').onclick = () => window.apxChat.open();

close()#

Закрывает окно чата.

window.apxChat.close();

toggle()#

Переключает состояние чата (открыт ↔ закрыт).

window.apxChat.toggle();

changeTheme(theme)#

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

// у вас на сайте переключили тёмную тему — синхронизируем виджет
window.apxChat.changeTheme('dark');

setToken(token)#

Передаёт токен вашего пользователя AI-оператору, чтобы тот мог дёргать ваше API от его имени. Не путать с init(token) — здесь токен идентифицирует клиента на вашем сайте, а не виджет.

Зачем это нужно#

В админ-панели для AI-оператора можно настроить API-интеграции — список endpoint'ов вашего бэкенда (заказы, профиль, баланс и т.д.), которые AI вызывает как tools во время диалога. У каждого endpoint есть флаг useUserToken:

• useUserToken: false — AI вызывает endpoint без авторизации (публичные данные).
• useUserToken: true — сервер берёт токен, сохранённый через setToken(), и подставляет его в заголовок Authorization при вызове.

Так AI «понимает», от чьего имени делать запросы:

Клиент: «Где мой заказ?» AI вызывает GET https://yourshop.com/api/orders с Authorization: Bearer <user_jwt> Ваш бэкенд возвращает заказы конкретно этого пользователя AI отвечает: «Заказ #1234 в пути, прибудет завтра»

Без setToken() AI имеет доступ только к публичным/анонимным endpoint'ам и не может работать с персональными данными.

Что происходит под капотом#

1. Виджет отправляет socket.emit('set_client_token', { token }).
2. Сервер сохраняет токен в Redis по ключу <channelUuid>:<clientUuid>:token с TTL 7 дней.
3. При вызове AI-инструмента с useUserToken: true сервер достаёт токен из Redis и подставляет в заголовок Authorization: <prefix> <token> (префикс настраивается в интеграции, по умолчанию Bearer).
4. При отключении сокета токен удаляется.

Если сокет ещё не подключён, метод выводит warning и ничего не делает — вызывайте после готовности виджета.

// после логина у вас на сайте
window.apxChat.setToken(myJwtFromBackend);

popup.toggle(uuid?)#

Управление поп-апом — это отдельная маркетинговая фича (всплывающее окно с акцией / формой / CTA, не путать с чатом). Конфигурируется в админке, может срабатывать по триггерам (время на странице, скролл и т.д.). Метод позволяет открыть/закрыть поп-ап программно.

Внутри просто диспатчит CustomEvent('apx-popup-toggle') — можно делать то же самое напрямую без обёртки.

window.apxChat.popup.toggle();
window.apxChat.popup.toggle('a3f7c2e1-...');

Событие apx-popup-toggle#

Кастомное событие на window. Виджет слушает его и переключает состояние поп-апа. Можно диспатчить вручную — без обёртки popup.toggle().

window.dispatchEvent(
  new CustomEvent('apx-popup-toggle', {
    detail: { uuid: 'a3f7c2e1-...' },
  }),
);

Примеры#

Открыть чат по клику на свою кнопку#

document
  .getElementById('support-btn')
  .addEventListener('click', () => window.apxChat.open());

Дать AI-оператору доступ к данным залогиненного пользователя#

window.apxChat.init('ВАШ_ТОКЕН', 'user-42');

// JWT вашего пользователя — AI будет ходить с ним в API-интеграции,
// у которых в админке включён флаг useUserToken
window.apxChat.setToken(jwt);

Синхронизация темы с сайтом#

const theme = document.documentElement.dataset.theme; // 'light' | 'dark'
window.apxChat.changeTheme(theme);