Nhúng khung chat Hubz vào phần mềm của bạn

Nhúng khung chat Hubz vào phần mềm của bạn để nhân viên trả lời khách ngay trên hồ sơ khách hàng: khung chat của một hội thoại, hoặc cả app Hubz của nhân viên.

1. Cho phép trang chứa khung

Trang chứa iframe phải nằm trong danh sách được nhúng, thêm bằng PUT /v1/embed-origins (dạng https://ten-mien) hoặc trong mục Tích hợp của Hubz:

curl -X PUT https://api.hubz.vn/v1/embed-origins \
  -H "Authorization: Bearer hbz_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"origins": ["https://crm.example.com"]}'

2. Xin địa chỉ nhúng

Từ máy chủ của bạn, gọi POST /v1/embed-token dưới tên nhân viên đang xem (X-Hubz-User). Gửi {"conversationId": "…"} để nhúng một hội thoại, hoặc {"app": true} để nhúng cả app (trừ các phần mật khẩu, xác thực hai lớp, chuyển công ty, khóa tích hợp):

curl -X POST https://api.hubz.vn/v1/embed-token \
  -H "Authorization: Bearer hbz_live_xxx" \
  -H "X-Hubz-User: lan@example.com" \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "…"}'

{"url": "…", "token": "…", "expiresAt": "2026-11-06T10:15:02Z"}

Đặt url vào iframe. Địa chỉ dùng được 60 phút. Khóa không có quyền send thì khung chỉ để xem.

3. Gia hạn không cần tải lại

Khi token sắp hết hạn, khung gửi {type: "hubz:embed-expired"} lên trang chứa. Trang xin token mới từ máy chủ của bạn rồi gửi vào khung {type: "hubz:embed-token", token} bằng postMessage tới origin của Hubz:

// The page that holds the iframe. Your backend calls POST /v1/embed-token with the key and
// returns { url, token }: never put the key in the browser.
const { url } = await fetch("/my-backend/hubz/embed-token").then((res) => res.json());
const hubzOrigin = new URL(url).origin;
const frame = document.querySelector("#hubz-frame");
frame.src = url;

window.addEventListener("message", async (event) => {
  if (event.origin !== hubzOrigin || event.data?.type !== "hubz:embed-expired") return;
  const { token } = await fetch("/my-backend/hubz/embed-token").then((res) => res.json());
  frame.contentWindow.postMessage({ type: "hubz:embed-token", token }, hubzOrigin);
});