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

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

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

<script src="https://cdn.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 в пути, прибудет завтра»

Сервер подставляет токен в заголовок Authorization: <prefix> <token> при вызове ручки — префикс настраивается в интеграции, по умолчанию Bearer.

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

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

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

Жизненный цикл токена#

Что гарантируется#

• Токен хранится только в оперативной памяти браузера и в зашифрованном виде на нашем сервере. В localStorage он не попадает.
• Его не видит ни оператор в чате, ни AI-модель: заголовок Authorization формируется на сервере в момент вызова, модель не может его прочитать или переслать.
• Он уходит только на те адреса, которые вы сами прописали в API-интеграции. Переадресации при вызове ваших ручек запрещены — токен не может «уехать» на сторонний домен по редиректу.

clearToken()#

Отзывает токен пользователя. Вызывайте при выходе из аккаунта на вашем сайте — иначе AI сможет обращаться к вашему API от имени этого пользователя, пока открыта вкладка.

// пользователь разлогинился у вас на сайте
window.apxChat.clearToken();

setIdentity(identity) / clearIdentity()#

Альтернатива setToken() для тех, кто не хочет отдавать токены пользователей. Ваш бэкенд подписывает идентификатор пользователя, а мы передаём его в ваше API вместе с подписью запроса — самого токена у нас не существует. Работает при авторизации через httpOnly-куки.

Полное описание, включая формат подписи и проверку на вашей стороне — Подписанная личность.

window.apxChat.setIdentity(identityJwtFromBackend);
window.apxChat.clearIdentity(); // при выходе из аккаунта

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