Чатты кіріктіру (iframe)

Қолданудың екі нұсқасы

POST /v1/iframe: WazzaBee чатын кіріктіру

Бұл эндпоинт WazzaBee чатын CRM жүйеңізге немесе кез келген веб-қосымшаға <iframe> арқылы кіріктіруге мүмкіндік береді. React, Vue, Angular немесе кез келген басқа фреймворкте жазылған жеке CRM үшін өте ыңғайлы.

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"
}

Чат тілі

Кіріктірілген чат төрт тілдің бірінде көрсетіледі: орыс (ru), ағылшын (en), қазақ (kk) немесе қырғыз (ky). Тіл мына ретпен таңдалады:

1. чат мекенжайындағы lang параметрі, мысалы https://app.wazzabee.com/chat/embed/ТОКЕН?lang=en;
2. POST /v1/iframe арқылы сессия жасағанда берілетін options.lang өрісі;
3. API кілті иесінің WazzaBee кабинетіндегі тіл;
4. бұлардың ешқайсысы берілмесе, чат орыс тілінде ашылады.

Пайдаланушыңыздың тілін options.lang өрісінде беру ең ыңғайлы: сонда жауаптағы сілтемені <iframe> ішіне өзгертпей қоя бересіз.

{
  "user": { "id": "manager-42", "name": "Alex" },
  "scope": "global",
  "options": { "lang": "en" }
}

Фронтендке кіріктіру

Қарапайым 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-ге source: "crm" өрісі бар postMessage жіберіңіз.

Нөмір цифрлар бойынша қалыпқа келтіріледі, сондықтан пішімі кез келген болуы мүмкін: +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 үлгілеріне.

Нені беру керек