Встраивание чата (iframe)

Два варианта использования

POST /v1/iframe — встраивание чата WazzaBee

Этот эндпоинт позволяет встроить чат WazzaBee в вашу CRM-систему или любое веб-приложение через <iframe>. Идеально подходит для кастомных CRM на React, Vue, Angular или любом другом фреймворке.

URL

POST https://api.wazzabee.com/api-gateway/v1/iframe

Заголовки

Authorization: Bearer ВАШ_API_КЛЮЧ
Content-Type: application/json

Параметры тела запроса

Режимы отображения (scope)

global — все чаты

Показывает полный список диалогов, как в основном интерфейсе WazzaBee. Подходит для отдельной страницы «Чаты» в вашей CRM.

card — чат конкретного контакта

Фильтрует диалоги по телефону контакта. Идеально для встраивания в карточку клиента — менеджер видит только переписку с этим клиентом.

Доступные UI-действия в шапке списка диалогов

В iframe есть встроенный набор управляющих кнопок над списком чатов. Их видимость зависит от выбранного scope — UI автоматически адаптируется под сценарий менеджера в CRM:

Примеры запросов

Пример 1. Все чаты (scope=global)

curl -X POST "https://api.wazzabee.com/api-gateway/v1/iframe" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "id": "manager-42",
      "name": "Алексей Менеджер"
    },
    "scope": "global"
  }'

Пример 2. Чат конкретного клиента (scope=card)

curl -X POST "https://api.wazzabee.com/api-gateway/v1/iframe" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "id": "manager-42",
      "name": "Алексей Менеджер"
    },
    "scope": "card",
    "filter": {
      "phone": "77001234567"
    }
  }'

Пример 3. С ограничением по каналам

curl -X POST "https://api.wazzabee.com/api-gateway/v1/iframe" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "id": "manager-42",
      "name": "Алексей Менеджер"
    },
    "scope": "card",
    "filter": {
      "phone": "77001234567",
      "channelIds": ["550e8400-e29b-41d4-a716-446655440000"]
    }
  }'

Успешный ответ (200 OK)

{
  "success": true,
  "url": "https://app.wazzabee.com/chat/embed/a1b2c3d4...64-символьный-токен",
  "token": "a1b2c3d4...64-символьный-токен",
  "expiresAt": "2026-03-13T10:00:00.000Z",
  "scope": "card"
}

Встраивание на фронтенде

Простой HTML

<iframe
  src="https://app.wazzabee.com/chat/embed/ТОКЕН_СЕССИИ"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write"
></iframe>

React-компонент

import { useEffect, useState } from "react";

function WazzaBeeChat({ contactPhone }) {
  const [iframeUrl, setIframeUrl] = useState(null);

  useEffect(() => {
    // Запрос к вашему бэкенду, который проксирует вызов к WazzaBee API
    fetch("/api/wazzabee/iframe", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        phone: contactPhone,
        scope: "card"
      })
    })
      .then(res => res.json())
      .then(data => setIframeUrl(data.url));
  }, [contactPhone]);

  if (!iframeUrl) return <div>Загрузка чата...</div>;

  return (
    <iframe
      src={iframeUrl}
      style={{ width: "100%", height: "600px", border: "none" }}
      allow="clipboard-write"
    />
  );
}

События postMessage

iframe отправляет события в родительское окно через window.postMessage. Вы можете слушать их для интеграции с вашей CRM.

Доступные события

Пример обработки событий

window.addEventListener("message", (event) => {
  // Проверяем источник
  if (event.origin !== "https://app.wazzabee.com") return;
  if (event.data?.source !== "wazzabee") return;

  const { event: type, ...data } = event.data;

  switch (type) {
    case "WZ_READY":
      console.log("Чат WazzaBee загружен, user:", data.userId, "scope:", data.scope);
      break;

    case "WZ_CHAT_OPENED":
      // Рекомендуется: data.phone, data.name
      console.log("Открыт диалог:", data.conversationId, "телефон:", data.phone);
      // Можно обновить карточку клиента в CRM
      break;

    case "WZ_CHAT_CLOSED":
      console.log("Диалог закрыт");
      break;

    case "WZ_MESSAGE_SENT":
      console.log("Менеджер отправил сообщение в чат:", data.chatId, data.phone);
      // Можно добавить запись в историю CRM
      break;

    case "WZ_MESSAGE_RECEIVED":
      console.log("Новое сообщение:", data.content);
      console.log("Направление:", data.direction);
      break;

    case "WZ_MESSAGES_READ":
      console.log("Менеджер прочитал чат:", data.conversationId);
      break;

    case "WZ_CREATE_CONTACT":
      console.log("Запрос на создание контакта:", data.phone, data.name);
      // Можно автоматически создать контакт в вашей CRM
      break;

    case "WZ_CHAT_NOT_FOUND":
      console.warn("Чат не найден:", data.phone, "причина:", data.reason);
      // Например, предложить создать контакт
      break;

    case "WZ_ACTION_NOT_SUPPORTED":
      console.warn("Действие недоступно:", data.action, "причина:", data.reason);
      break;
  }
});

Управление чатом из вашей CRM

Обмен двусторонний: не только iframe сообщает вам о происходящем, но и вы можете управлять им. Отправьте в iframe postMessage с полем source: "crm".

Номер нормализуется по цифрам — формат любой: +7 (700) 123-45-67, 77001234567, 87001234567 сработают одинаково.

iframeRef.current?.contentWindow?.postMessage({
  source: "crm",
  action: "OPEN_CHAT_BY_PHONE",
  phone: "+77001234567",
}, "*");

Сценарий: карточка клиента слева, чат справа

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

const [activeChat, setActiveChat] = useState(null);

useEffect(() => {
  const handler = (event) => {
    if (event.origin !== "https://app.wazzabee.com") return;
    if (event.data?.source !== "wazzabee") return;

    // Менеджер переключился на другой чат
    if (event.data.event === "WZ_CHAT_OPENED") {
      setActiveChat({
        chatId: event.data.chatId,
        phone: event.data.phone,
        name: event.data.name,
      });
      // Тянем карточку клиента по номеру из своей CRM
      loadCustomerCard(event.data.phone);
    }
  };

  window.addEventListener("message", handler);
  return () => window.removeEventListener("message", handler);
}, []);

Обратный ход — менеджер открыл сделку в CRM и хочет сразу перейти к переписке: пошлите в iframe OPEN_CHAT_BY_PHONE, и чат сам переключится на нужный диалог.

Возможные ошибки

Время жизни сессии

• Сессия действует 24 часа с момента создания
• После истечения iframe покажет ошибку — нужно запросить новый токен
• Рекомендуем обновлять токен заранее (например, каждые 12 часов)
• Для каждого пользователя CRM создаётся отдельная сессия

Кто из менеджеров ответил клиенту

Имя, которое вы передаёте в user.name при создании сессии, — это автор сообщений. Под каждым исходящим сообщением в ленте чата видна подпись вида «из WazzaBee · Назерке А.»: так по переписке понятно, кто из менеджеров ответил. Фамилия сокращается до инициала.

Подпись работает для всего, что оператор отправляет из встроенного чата: текста, файлов, голосовых и WABA-шаблонов.

Что нужно передавать