Перейти до змісту

Інтеграція Віджета

Інтегруйте віджет ChatHub у ваш веб-сайт, щоб надавати клієнтам можливість спілкування з підтримкою (чату) в режимі реального часу.

Огляд

Віджет ChatHub — це JavaScript-компонент, який:

  • Легко вбудовується (embed) на будь-який веб-сайт.
  • Пропонує інтерфейс живого чату.
  • З'єднує клієнтів із вашими операторами.
  • Для роботи вимагає JWT токен оператора (Operator Auth Token).
  • Завантажується як ES-модуль.

Швидкий Старт

1. Отримайте Токен Оператора

Спершу вам потрібно згенерувати токен оператора, слідуючи інструкціям з авторизації:

// 1. Отримати Company Token
const companyToken = await getCompanyToken(login, password);

// 2. Отримати Організацію
const organizations = await getOrganizations(companyToken);
const orgId = organizations[0].id;

// 3. Отримати Оператора
const operators = await getOperators(companyToken, orgId);
const operatorId = operators[0].id;

// 4. Згенерувати токен Оператора
const operatorToken = await getOperatorToken(
  companyToken,
  operatorId,
  expiresAt
);

// 5. Перевірити (валідувати) токен
const isValid = await validateToken(companyToken, operatorToken);

2. Вбудуйте Віджет

Додайте скрипт віджета до вашого HTML-коду:

<!DOCTYPE html>
<html lang="uk">
<head>
    <title>Ваш Чудовий Сайт</title>
</head>
<body>
    <!-- Контент вашого сайту -->

    <!-- ChatHub Віджет -->
    <script type="module" id="operator-chat-panel-script"
      src="https://widget.smsbat.com/operator-chat-panel/widget-script.js"
      token="Ваш_Токен_Оператора_Тут"></script>
</body>
</html>

Параметри Скрипта

Атрибут Значення Обов'язково Опис
type module Так Тип скрипта ES-модуль
id operator-chat-panel-script Так Унікальний ідентифікатор скрипта (заборонено змінювати)
src URL Так Адреса, за якою знаходиться скрипт віджета
token JWT токен Так Токен аутентифікації оператора

Методи Інтеграції

Статичний HTML

Для статичних веб-сайтів скрипт можна вставити безпосередньо:

<!DOCTYPE html>
<html lang="uk">
<head>
    <meta charset="UTF-8">
    <title>Мій Сайт</title>
</head>
<body>
    <h1>Ласкаво просимо!</h1>

    <!-- ChatHub Віджет -->
    <script type="module" id="operator-chat-panel-script"
      src="https://widget.smsbat.com/operator-chat-panel/widget-script.js"
      token="YOUR_OPERATOR_TOKEN"></script>
</body>
</html>

Динамічна ін'єкція (JavaScript / SPA-додатки)

Для SPA (Single-page applications) вбудовуйте динамічно:

function loadChatHubWidget(operatorToken) {
  // Видалити старий скрипт, якщо він уже був завантажений
  const existing = document.getElementById('operator-chat-panel-script');
  if (existing) {
    existing.remove();
  }

  // Створити елемент скрипта
  const script = document.createElement('script');
  script.type = 'module';
  script.id = 'operator-chat-panel-script';
  script.src = 'https://widget.smsbat.com/operator-chat-panel/widget-script.js';
  script.setAttribute('token', operatorToken);

  // Додати скрипт до секції body
  document.body.appendChild(script);
}

// Запуск
const token = await fetchOperatorTokenFromServer();
loadChatHubWidget(token);

React

Для фреймворків, як React, можна використати хук useEffect:

import { useEffect } from 'react';

function ChatHubWidget({ operatorToken }) {
  useEffect(() => {
    if (!operatorToken) return;

    // Створити скрипт
    const script = document.createElement('script');
    script.type = 'module';
    script.id = 'operator-chat-panel-script';
    script.src = 'https://widget.smsbat.com/operator-chat-panel/widget-script.js';
    script.setAttribute('token', operatorToken);

    document.body.appendChild(script);

    // Очищення після видалення компоненту (unmount)
    return () => {
      const existing = document.getElementById('operator-chat-panel-script');
      if (existing) {
        existing.remove();
      }
    };
  }, [operatorToken]);

  return null;
}

Управління Токенами

НІКОЛИ не розкривайте свій логін і пароль компанії, або Company Token у клієнтському коді (Frontend). Усі токени операторів мають генеруватися на стороні вашого сервера (напр. PHP, Python, NodeJS):

// Приклад NodeJS + Express
app.get('/api/chathub/token', async (req, res) => {
  try {
    const operatorId = 123;
    const companyToken = process.env.CHATHUB_COMPANY_TOKEN; // Захищено

    // Генерація токена на сервері
    const operatorToken = await generateOperatorToken(
      companyToken,
      operatorId
    );

    res.json({ token: operatorToken });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});

Кілька Організацій

Якщо вам треба завантажити віджет для різних організацій в залежності від обраного користувачем розділу сайту (наприклад "Продажі" / "Підтримка"), вам потрібно завантажити різні токени й відповідно перебудувати скрипт.

Вирішення Проблем

Віджет не завантажується

  1. Перевірте, чи токен оператора актуальний і не минув (expiresAt).
  2. Впевніться, що атрибут id в скрипті не змінено (operator-chat-panel-script).
  3. Подивіться в консоль браузера (F12) на наявність помилок CORS чи 401 Unauthorized.
  4. Перевірте мережеве з'єднання і наявність блокувальників реклами (AdBlockers).

Токен протерміновано (Expired)

Налаштуйте автоматичний обробник (webhook) або інтервал для перезавантаження токена (refreshing token) до того, як закінчиться термін його дії. Максимальний час життя токена становить 24 години, тож його слід оновлювати заздалегідь.

Наступні Кроки