Embedding the chat (iframe)

Two ways to use it

POST /v1/iframe: embedding the WazzaBee chat

This endpoint lets you embed the WazzaBee chat into your CRM or any web app through an <iframe>. It is a perfect fit for custom CRMs built on React, Vue, Angular or any other framework.

URL

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

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body parameters

Display modes (scope)

global: all conversations

Shows the full list of conversations, just like the main WazzaBee interface. A good fit for a dedicated “Chats” page in your CRM.

card: one contact's chat

Filters conversations by the contact's phone number. Perfect for embedding into a customer card: the agent sees only the conversation with that customer.

UI actions available in the conversation list header

The iframe comes with a built-in set of control buttons above the chat list. Which ones are visible depends on the scope you chose. The UI adapts to how the agent works inside the CRM:

Request examples

Example 1. All conversations (scope=global)

curl -X POST "https://api.wazzabee.com/api-gateway/v1/iframe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "id": "manager-42",
      "name": "Alex Manager"
    },
    "scope": "global"
  }'

Example 2. One customer's chat (scope=card)

curl -X POST "https://api.wazzabee.com/api-gateway/v1/iframe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "id": "manager-42",
      "name": "Alex Manager"
    },
    "scope": "card",
    "filter": {
      "phone": "77001234567"
    }
  }'

Example 3. Limited to specific channels

curl -X POST "https://api.wazzabee.com/api-gateway/v1/iframe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "id": "manager-42",
      "name": "Alex Manager"
    },
    "scope": "card",
    "filter": {
      "phone": "77001234567",
      "channelIds": ["550e8400-e29b-41d4-a716-446655440000"]
    }
  }'

Successful response (200 OK)

{
  "success": true,
  "url": "https://app.wazzabee.com/chat/embed/a1b2c3d4...64-character-token",
  "token": "a1b2c3d4...64-character-token",
  "expiresAt": "2026-03-13T10:00:00.000Z",
  "scope": "card"
}

Chat language

The embedded chat is shown in one of four languages: Russian (ru), English (en), Kazakh (kk) or Kyrgyz (ky). The language is chosen in this order:

1. the lang parameter in the chat URL, for example https://app.wazzabee.com/chat/embed/TOKEN?lang=en;
2. the options.lang field when you create the session with POST /v1/iframe;
3. the WazzaBee account language of the API key owner;
4. if none of these is set, the chat opens in Russian.

The simplest way is to pass your user's language in options.lang: then you can put the URL from the response into the <iframe> as is.

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

Embedding on the frontend

Plain HTML

<iframe
  src="https://app.wazzabee.com/chat/embed/SESSION_TOKEN"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write"
></iframe>

React component

import { useEffect, useState } from "react";

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

  useEffect(() => {
    // A call to your backend, which proxies the request to the 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>Loading chat...</div>;

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

postMessage events

The iframe sends events to the parent window through window.postMessage. You can listen to them and wire the chat into your CRM.

Available events

Handling events: an example

window.addEventListener("message", (event) => {
  // Check the origin
  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 chat loaded, user:", data.userId, "scope:", data.scope);
      break;

    case "WZ_CHAT_OPENED":
      // Recommended: data.phone, data.name
      console.log("Conversation opened:", data.conversationId, "phone:", data.phone);
      // You can refresh the customer card in your CRM here
      break;

    case "WZ_CHAT_CLOSED":
      console.log("Conversation closed");
      break;

    case "WZ_MESSAGE_SENT":
      console.log("The agent sent a message to chat:", data.chatId, data.phone);
      // You can add a record to the CRM history here
      break;

    case "WZ_MESSAGE_RECEIVED":
      console.log("New message:", data.content);
      console.log("Direction:", data.direction);
      break;

    case "WZ_MESSAGES_READ":
      console.log("The agent read the chat:", data.conversationId);
      break;

    case "WZ_CREATE_CONTACT":
      console.log("Request to create a contact:", data.phone, data.name);
      // You can create the contact in your CRM automatically
      break;

    case "WZ_CHAT_NOT_FOUND":
      console.warn("Chat not found:", data.phone, "reason:", data.reason);
      // For example, offer to create a contact
      break;

    case "WZ_ACTION_NOT_SUPPORTED":
      console.warn("Action not available:", data.action, "reason:", data.reason);
      break;
  }
});

Controlling the chat from your CRM

The exchange works both ways: the iframe does not just tell you what is happening, you can also control it. Send a postMessage to the iframe with the field source: "crm".

The number is normalized by its digits, so any format works: +7 (700) 123-45-67, 77001234567 and 87001234567 all behave the same way.

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

Scenario: customer card on the left, chat on the right

A typical task when embedding into a CRM: on the right the agent handles the conversation, on the left there is the customer card, a product catalog and action buttons. When the agent switches to another chat, the left side should load the new customer's data by itself.

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

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

    // The agent switched to another chat
    if (event.data.event === "WZ_CHAT_OPENED") {
      setActiveChat({
        chatId: event.data.chatId,
        phone: event.data.phone,
        name: event.data.name,
      });
      // Load the customer card by phone number from your CRM
      loadCustomerCard(event.data.phone);
    }
  };

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

The other direction: the agent opened a deal in the CRM and wants to jump straight to the conversation. Send OPEN_CHAT_BY_PHONE to the iframe, and the chat switches to the right conversation by itself.

Possible errors

Session lifetime

• A session is valid for 24 hours from the moment it is created
• Once it expires the iframe shows an error: you need to request a new token
• We recommend refreshing the token in advance (every 12 hours, for example)
• A separate session is created for every CRM user

Which agent replied to the customer

The name you pass in user.name when creating the session is the message author. Every outgoing message in the chat feed carries a signature like “from WazzaBee · Nazerke A.”, so the conversation itself shows which agent replied. The last name is shortened to an initial.

The signature works for everything an agent sends from the embedded chat: text, files, voice notes and WABA templates.

What you need to pass