Nhúng vào trang web

Đưa khung chat của ứng dụng lên website mà không cần tự dựng giao diện. Có hai kiểu nhúng:

Kiểu nhúng	Trải nghiệm	Phù hợp khi
Bong bóng chat	Nút tròn nổi ở góc màn hình, bấm để mở khung chat	Website đã có nội dung, muốn thêm trợ lý hỗ trợ
Trang toàn màn hình	Khung chat chiếm trọn trang, mở qua đường dẫn hoặc iframe	Trang chuyên để trò chuyện, hoặc nhúng vào một khu vực riêng

Cả hai đều dùng chung access token của ứng dụng và URL nền tảng (PLATFORM_URL, xem Môi trường).

1. Chuẩn bị

Lấy access token và URL nền tảng

Vào Ứng dụng → chọn ứng dụng chat → Nhúng vào trang web. Hệ thống hiển thị sẵn đoạn mã kèm access token (token) và URL nền tảng (baseUrl).

Môi trường dev

Trên môi trường Development, Simplize sẽ cung cấp sẵn access token và URL nền tảng cho bạn. Access token là định danh công khai, không phải khóa bí mật.

Publish và bật chia sẻ ứng dụng

Đảm bảo ứng dụng đã publish và bật chia sẻ. Nếu chưa, khung chat sẽ báo lỗi 404 khi tải.

2. Bong bóng chat

Dán đoạn mã sau vào ngay trước thẻ </body> của trang. Thay APP_ACCESS_TOKEN và https://app.simplize.dev bằng giá trị của bạn.

<script>
  window.simplizeChatbotConfig = {
    token: 'APP_ACCESS_TOKEN',
    baseUrl: 'https://app.simplize.dev',
  };
</script>
<script src="https://app.simplize.dev/embed.js" id="APP_ACCESS_TOKEN" defer></script>

Dán đúng ở hai chỗ

Access token xuất hiện hai lần: trong token và trong thuộc tính id của thẻ <script> tải embed.js. Hai giá trị này phải giống nhau, nếu không bong bóng sẽ không hiện.

Tùy chọn cấu hình

Thêm các trường sau vào window.simplizeChatbotConfig khi cần:

Trường	Kiểu	Mô tả
`token`	string	Bắt buộc. Access token của ứng dụng.
`baseUrl`	string	Bắt buộc. URL nền tảng (`PLATFORM_URL`).
`clientId`	string	Bật đăng nhập SSO (xem mục 4).
`systemVariables`	object	Biến hệ thống: `user_id`, `conversation_id` (nếu có, phải là UUID hợp lệ).
`userVariables`	object	Thông tin hiển thị: `name`, `avatar_url`.

<script>
  window.simplizeChatbotConfig = {
    token: 'APP_ACCESS_TOKEN',
    baseUrl: 'https://app.simplize.dev',
    systemVariables: {
      user_id: '45',
    },
    userVariables: {
      name: 'Nguyễn Văn A',
      avatar_url: 'https://example.com/avatar.png',
    },
  };
</script>
<script src="https://app.simplize.dev/embed.js" id="APP_ACCESS_TOKEN" defer></script>

3. Trang chat toàn màn hình

Có hai đường dẫn, chọn theo mục đích:

Đường dẫn	Dùng cho
`{PLATFORM_URL}/chat/{token}`	Trang chat độc lập — mở qua liên kết hoặc tab mới.
`{PLATFORM_URL}/chatbot/{token}`	Khung chat để nhúng iframe vào trang của bạn.

Link trực tiếp
Nhúng iframe

Mở khung chat độc lập bằng đường dẫn:

https://app.simplize.dev/chat/APP_ACCESS_TOKEN

Dùng làm liên kết trong menu, nút bấm, hoặc mở ở tab mới.

Nhúng khung chat vào một khu vực trên trang (dùng đường dẫn /chatbot/):

<iframe
  src="https://app.simplize.dev/chatbot/APP_ACCESS_TOKEN"
  style="width: 100%; height: 100%; min-height: 700px"
  frameborder="0"
  allow="microphone">
</iframe>

Thuộc tính allow="microphone" cần thiết nếu ứng dụng dùng nhập bằng giọng nói.

4. Tự động đăng nhập người dùng (SSO)

Mặc định khung chat mở ở chế độ ẩn danh. Nếu người dùng đã đăng nhập trên website của bạn, bạn có thể cho họ vào chat với đúng danh tính mà không phải đăng nhập lại.

Cách làm: backend của bạn ký một identity assertion (JWT ngắn hạn) rồi truyền cho khung chat. Khung chat tự đổi assertion lấy phiên đăng nhập — bạn không phải gọi API xác thực nào của nền tảng.

Cần làm trước ở backend

SSO cần một endpoint ở backend của bạn để phát assertion (ví dụ /agent-assertion) và một clientId. Cách tạo connection, ký assertion và bảo mật xem tại Tích hợp đăng nhập (SSO). Trang này chỉ hướng dẫn phần truyền assertion vào khung chat.

Quyết định luồng nào

Endpoint phát assertion phải yêu cầu đăng nhập: nếu người dùng đã đăng nhập, nó trả { "jwt": "..." }; nếu chưa, nó trả HTTP 401. Dựa vào đó, xử lý như sau:

Trạng thái người dùng	Bạn làm gì	Kết quả trong khung chat
Đã đăng nhập (endpoint trả `jwt`)	Truyền assertion vào khung chat	Mở chat với đúng danh tính người dùng
Chưa đăng nhập (endpoint trả `401`)	Không truyền assertion (hoặc truyền `null`)	Chat mở ẩn danh, hoặc bạn tự hiện form đăng nhập của mình

Khi nào phải bắt đăng nhập

Nếu ứng dụng được cấu hình bắt buộc đăng nhập, khung chat sẽ không mở ở chế độ ẩn danh — lúc này với người dùng chưa đăng nhập, bạn nên chuyển hướng sang trang đăng nhập của mình thay vì nhúng chat.

Mã nhúng theo từng cách

Các đoạn dưới đây là trang HTML hoàn chỉnh, dán chạy được ngay (chỉ cần thay APP_ACCESS_TOKEN, YOUR_CLIENT_ID, và đường dẫn endpoint phát assertion của bạn).

Bong bóng
Iframe
Link trực tiếp

<!doctype html>
<html lang="vi">
  <body>
    <!-- Nội dung website của bạn ... -->

    <script>
      window.simplizeChatbotConfig = {
        token: 'APP_ACCESS_TOKEN',
        baseUrl: 'https://app.simplize.dev',
        clientId: 'YOUR_CLIENT_ID',
      };
    </script>
    <script src="https://app.simplize.dev/embed.js" id="APP_ACCESS_TOKEN" defer></script>

    <script>
      // Hỏi backend của bạn xem người dùng đã đăng nhập chưa và lấy assertion.
      fetch('/your-backend/agent-assertion', { credentials: 'include' })
        .then(function (res) {
          if (res.status === 401) return null; // Chưa đăng nhập
          return res.json();
        })
        .then(function (data) {
          if (data && data.jwt) {
            // Đã đăng nhập -> đưa danh tính vào khung chat
            window.simplizeChatbot.setIdentityToken(data.jwt);
          }
          // Chưa đăng nhập -> không làm gì: khung chat chạy ẩn danh.
          // Nếu muốn bắt đăng nhập, thay bằng:
          // window.location.href = '/login?redirect=' + encodeURIComponent(location.href);
        });
    </script>
  </body>
</html>

<!doctype html>
<html lang="vi">
  <body>
    <iframe
      id="simplize-chat"
      src="https://app.simplize.dev/chatbot/APP_ACCESS_TOKEN"
      style="width: 100%; height: 100vh; border: 0"
      allow="microphone">
    </iframe>

    <script>
      (function () {
        var frame = document.getElementById('simplize-chat');
        var origin = 'https://app.simplize.dev';

        window.addEventListener('message', function (event) {
          // Chỉ nhận thông điệp từ đúng khung chat
          if (event.source !== frame.contentWindow || event.origin !== origin) return;
          if (!event.data || event.data.type !== 'simplize-chat:ready') return;

          // Khung chat đã sẵn sàng -> lấy assertion từ backend rồi gửi vào
          fetch('/your-backend/agent-assertion', { credentials: 'include' })
            .then(function (res) {
              if (res.status === 401) return null; // Chưa đăng nhập
              return res.json();
            })
            .then(function (data) {
              frame.contentWindow.postMessage(
                {
                  type: 'simplize-chat:identity',
                  jwt: data ? data.jwt : null, // null -> khung chat chạy ẩn danh
                  clientId: 'YOUR_CLIENT_ID',
                },
                origin,
              );
            });
        });
      })();
    </script>
  </body>
</html>

mẹo

Luôn gửi thông điệp trả lời khi nhận simplize-chat:ready (kể cả khi jwt là null) để khung chat không phải chờ. Endpoint phát assertion nên phản hồi nhanh.

Cách này không cần JavaScript ở trình duyệt — backend của bạn dựng sẵn đường dẫn cho người dùng đã đăng nhập:

https://app.simplize.dev/chat/APP_ACCESS_TOKEN?token=<assertion>&cid=YOUR_CLIENT_ID

<assertion> là JWT do backend của bạn ký (thay tại chỗ khi tạo link).
Trang chat tự đổi assertion lấy phiên rồi xoá token khỏi URL.
Vì token nằm trên URL, hãy để assertion dùng một lần và ngắn hạn.

Với người dùng chưa đăng nhập, chỉ cần trỏ tới đường dẫn không có token để vào chat ẩn danh:

https://app.simplize.dev/chat/APP_ACCESS_TOKEN

5. Xử lý sự cố

Hiện tượng	Nguyên nhân thường gặp	Cách xử lý
Bong bóng không xuất hiện	Access token trong `token` và thuộc tính `id` không khớp	Đặt cùng một access token ở cả hai vị trí
Khung chat báo 404	Ứng dụng chưa publish hoặc chưa bật chia sẻ	Publish và bật chia sẻ ứng dụng
Không kết nối được	`baseUrl` không trỏ đúng URL nền tảng	Kiểm tra lại URL nền tảng ở trang Nhúng vào trang web
Vẫn vào chat ẩn danh dù đã đăng nhập	Endpoint phát assertion trả `401`, hoặc gọi `setIdentityToken` quá muộn	Kiểm tra endpoint có nhận đúng cookie đăng nhập (`credentials: 'include'`) và phản hồi nhanh
Chat báo cần đăng nhập	Ứng dụng bắt buộc đăng nhập nhưng chưa truyền assertion	Truyền assertion, hoặc chuyển hướng người dùng sang trang đăng nhập của bạn

Cần cấu hình connection và cách ký assertion? Xem Tích hợp đăng nhập (SSO).

1. Chuẩn bị​

Lấy access token và URL nền tảng

Publish và bật chia sẻ ứng dụng

2. Bong bóng chat​

Tùy chọn cấu hình​

3. Trang chat toàn màn hình​

4. Tự động đăng nhập người dùng (SSO)​

Quyết định luồng nào​

Mã nhúng theo từng cách​

5. Xử lý sự cố​