Hướng dẫn tích hợp website

Nhúng widget chat khách hàng và portal quản lý đa kênh Double Boss vào website của bạn. Public key và domain cụ thể lấy trong Double Boss sau khi tạo kênh website.

Các đoạn mã bên dưới dùng placeholder YOUR_PUBLIC_KEY và domain mẫu example.com. Thay bằng giá trị thật của kênh trong Double Boss trước khi đưa lên production.
Kênh website
Website của bạn
Domain đăng ký: example.com
Hướng dẫn tích hợp vào website khách hàng
  1. Sao chép đoạn mã nhúng bên dưới.
  2. Dán vào website khách, ngay trước thẻ </body> trên các trang cần hiển thị chat.
  3. Đảm bảo domain website khớp với example.com đã đăng ký.
  4. Sau khi khách đăng nhập, trang phải có id khách trên DOM (xem bảng bên dưới). Nếu không tìm thấy id, widget báo «Cần đăng nhập để sử dụng tính năng chat» và không cho gửi tin.
  5. Khách đã đăng nhập sẽ thấy icon chat góc dưới phải; tin nhắn đồng bộ về mục Hội thoại khách hàng trên Double Boss.
Nhận diện khách đã đăng nhập

Widget đọc id, tên và avatar khách từ attribute trên trang (phần tử đầu tiên khớp). Không tạo id ẩn danh.

Id khách (bắt buộc)

  1. data-trade-visitor-id — ưu tiên
  2. data-uid — dùng nếu không có data-trade-visitor-id

Tên khách (sau khi đã có id)

  1. data-trade-visitor-name — ưu tiên
  2. data-user-fullname — dùng nếu không có tên ở bước trên
  3. Nội dung text trong thẻ chứa id khách — dùng nếu vẫn chưa có tên

Avatar khách (tuỳ chọn)

  1. data-trade-visitor-avatar — ưu tiên (URL tuyệt đối http/https)
  2. data-user-avatar — dùng nếu không có data-trade-visitor-avatar

Avatar được lưu vào hồ sơ kênh và hiển thị trên màn Hội thoại khách hàng.

Nút mở chat tuỳ chỉnh (tuỳ chọn)

Nếu trang có phần tử id="trade_web_open_chat", widget ẩn nút tròn góc phải và mở popup khi click phần tử đó. 

<button type="button" id="trade_web_open_chat">Chat với chúng tôi</button>

Ví dụ nhận diện khách

<!-- Cách 1: id + tên + avatar trên cùng một thẻ -->
<span data-trade-visitor-id="12345"
      data-trade-visitor-name="Nguyễn Văn A"
      data-trade-visitor-avatar="https://cdn.example.com/avatars/12345.jpg"></span>

<!-- Cách 2: dùng attribute sẵn có của website -->
<a data-uid="12345" data-user-fullname="Nguyễn Văn A" data-user-avatar="https://cdn.example.com/a.jpg" href="/profile">…</a>

<!-- Cách 3: chỉ có id — tên lấy từ nội dung thẻ -->
<span data-uid="12345">Nguyễn Văn A</span>

<!-- Mã nhúng widget (trước </body>) -->
<script src="…/js/trade_web_client.js" data-token="PUBLIC_KEY" data-api-base="https://TRADE_HOST"></script>
Mã nhúng 
<!-- Sau đăng nhập: gắn data-trade-visitor-id (hoặc data-uid) + data-trade-visitor-name (hoặc data-user-fullname) + data-trade-visitor-avatar (hoặc data-user-avatar) -->
<script src="https://doubleboss.online/js/trade_web_client.js?v=20260916-mobile-chat-ux" data-token="YOUR_PUBLIC_KEY" data-api-base="https://doubleboss.online"></script>
Tích hợp portal quản lý đa kênh

Nhúng toàn bộ cổng quản trị Double Boss (hội thoại đa kênh, nhân viên AI, kênh, phân quyền…) vào trang admin nội bộ của website khách. Nhân viên đăng nhập trên website khách sẽ được đồng bộ sang Double Boss và mở portal theo quyền được cấp.

  1. Sao chép đoạn mã nhúng bên dưới và dán vào trang admin nội bộ (chỉ staff truy cập).
  2. Tạo API nội bộ trên server website khách để cấp session portal (xem hướng dẫn bên dưới).
  3. Public key (YOUR_PUBLIC_KEY chỉ lưu trên server — không đưa vào HTML/JavaScript trình duyệt. Giá trị thật lấy trong Double Boss ở màn chi tiết kênh website sau khi tạo kênh.
  4. Phân quyền menu trên Double Boss (bộ phận / chức năng). Nhân viên chưa được cấp quyền sẽ thấy màn chào mừng, không mở được nghiệp vụ.
Luồng tích hợp

Mỗi Public key gắn với đúng một kênh website. Trình duyệt chỉ gọi API nội bộ của website khách; server website khách mới gọi Double Boss bằng Public key.

Bước 1 — Tạo API nội bộ trên server website khách

Endpoint ví dụ GET /api/admin/trade-portal-session — chỉ trả JWT khi staff đã đăng nhập trên website khách. Trong handler, gọi Double Boss (server → server) rồi trả nguyên phản hồi về trình duyệt. 

// GET /api/admin/trade-portal-session (sau khi xác thực session staff)

// 1. Gọi Double Boss:
POST https://doubleboss.online/api/portal/session
X-Trade-Public-Key: YOUR_PUBLIC_KEY
Content-Type: application/json

{
  "externalUserId": "shop-staff-42",
  "displayName": "Nguyễn Văn A",
  "email": "user@merchant.com",
  "phone": "090…",
  "avatarUrl": "https://…"
}

// 2. Double Boss trả (proxy nguyên về trình duyệt):
// {
//   "accessToken": "eyJhbG…",
//   "hubUrl": "/hubs/chat",
//   "expiresInSeconds": 28800,
//   "portalState": "active" | "welcome",
//   "menu": [ … ],
//   "functionKeys": [ … ],
//   …
// }

Bước 2 — Nhúng script trên trang admin website khách

Chỉ cần một thẻ chứa portal và một thẻ script. CSS/JS phụ thuộc được tải tự động từ Double Boss. Script tự GET API nội bộ (Bước 1) kèm cookie session staff.

Thuộc tínhCách dùng
#trade_portal_root Container portal — bắt buộc có trên trang admin. Đặt dưới menu top của website khách, trong một khối position: relative có chiều cao xác định (ví dụ height: calc(100vh - chiều cao header)). Không để portal phủ lên header — nếu không menu cấp 2 của website khách sẽ không sổ ra được.
data-token-url URL API nội bộ trên domain website khách (ví dụ /api/admin/trade-portal-session). Khuyến nghị.
Mã nhúng 
<!-- Đặt portal trong vùng nội dung dưới menu top. Phần tử cha cần position:relative và chiều cao xác định (không phủ lên header). -->
<div style="position:relative;height:calc(100vh - 64px);min-height:480px;">
<div id="trade_portal_root"></div>
</div>
<script src="https://doubleboss.online/js/trade_portal.js?v=20260917-phone-link-parity"
        data-token-url="/api/admin/trade-portal-session"></script>
Liên hệ tư vấn tích hợp