Nhúng vào trang web

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

Kiểu nhúng	Trải nghiệm	Định danh công khai cần có
Bong bóng chat AI	Nút tròn nổi ở góc màn hình, bấm để mở trợ lý AI	Access token của ứng dụng
Trang chat AI toàn màn hình	Khung chat chiếm trọn trang, mở qua đường dẫn hoặc iframe	Access token của ứng dụng
Live chat	Bong bóng ở góc màn hình nối tới tư vấn viên (và chatbot kịch bản)	Channel ID của kênh

Cả ba đều dùng URL nền tảng (PLATFORM_URL, xem Môi trường). Mọi đường dẫn nhúng nằm dưới {PLATFORM_URL}/chat/….

1. Chuẩn bị

Lấy định danh công khai

Chat AI: Ứng dụng → chọn ứng dụng → Nhúng vào trang web — Portal hiển thị sẵn đoạn mã kèm access token (token) và baseUrl.
Live chat: Live chat → Kênh → tab Nhúng — đoạn mã kèm channelId và baseUrl.

Môi trường dev

Trên môi trường Development, Simplize cung cấp sẵn access token / channel ID và URL nền tảng. Đây là định danh công khai, không phải khoá bí mật.

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

Ứng dụng chat AI phải đã publish và bật chia sẻ, nếu không khung chat báo 404. Kênh live chat phải đang bật.

2. Bong bóng chat AI

Dán đoạn mã sau vào ngay trước thẻ </body>. 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/chat/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ị phải giống nhau, nếu không bong bóng không hiện.

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

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	`client_id` của Ứng dụng OAuth — bật đăng nhập SSO (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`.
`draggable`	boolean	Cho kéo khung chat.

<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/chat/embed.js" id="APP_ACCESS_TOKEN" defer></script>

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

Đườ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}/chat/embed/chatbot/{token}`	Khung chat để nhúng iframe vào trang của bạn.

Link trực tiếp
Nhúng iframe

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. Người đã đăng nhập trên nền tảng (khách hàng) vào đúng danh tính; còn lại vào ẩn danh.

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

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, cho họ vào chat với đúng danh tính mà không đăng nhập lại.

Cách làm: backend của bạn ký một identity assertion (JWT RFC 7523, ngắn hạn) rồi truyền { jwt, clientId } cho khung chat. Khung chat tự đổi assertion lấy phiên ở POST {PLATFORM_URL}/api/oauth2/token — 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

Một endpoint phát assertion (ví dụ /agent-assertion) và clientId của Ứng dụng OAuth. Cách tạo ứng dụng OAuth, 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: người đã đăng nhập nhận { "jwt": "...", "clientId": "..." }; chưa đăng nhập nhận HTTP 401.

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
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 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 chat AI được cấu hình bắt buộc đăng nhập, khung chat không mở ẩn danh — với người chưa đăng nhập, hãy chuyển hướng sang trang đăng nhập của bạn. Kênh live chat bắt đăng nhập sẽ phát sự kiện simplize-livechat:sign-in-required trên window để bạn hiện form đăng nhập.

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

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

Bong bóng chat AI
Iframe chat AI
Live chat

<!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/chat/embed.js" id="APP_ACCESS_TOKEN" defer></script>

    <script>
      // embed.js tải với `defer` nên chỉ sẵn sàng từ DOMContentLoaded.
      window.addEventListener('DOMContentLoaded', function () {
        // Hỏi backend của bạn: người dùng đã đăng nhập chưa, 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 assertion vào khung chat; khung chat tự đổi lấy phiên
              window.simplizeChatbot.setIdentityToken(data.jwt);
            }
            // Chưa đăng nhập -> không làm gì: khung chat chạy ẩn danh.
            // Muốn bắt đăng nhập:
            // window.location.href = '/login?redirect=' + encodeURIComponent(location.href);
          });
      });
    </script>
  </body>
</html>

setIdentityToken gọi được bất kỳ lúc nào sau khi embed.js đã tải (khung chat chưa mở thì nó đợi); gọi setIdentityToken(null) để về ẩn danh.

<!doctype html>
<html lang="vi">
  <body>
    <iframe
      id="simplize-chat"
      src="https://app.simplize.dev/chat/embed/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 trả lời khi nhận simplize-chat:ready (kể cả jwt: null) để khung chat không phải chờ hết thời gian đợi danh tính (2 giây) rồi mới mở ẩn danh.

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

    <script>
      window.simplizeLivechatSettings = {
        baseUrl: 'https://app.simplize.dev',
        channelId: 'CHANNEL_ID',
        // identity: { jwt: '...', clientId: 'YOUR_CLIENT_ID' }  -- điền sau khi lấy assertion
      };
    </script>
    <script defer src="https://app.simplize.dev/chat/livechat-embed.js"></script>

    <script>
      fetch('/your-backend/agent-assertion', { credentials: 'include' })
        .then(function (res) {
          if (res.status === 401) return null; // Chưa đăng nhập -> live chat chạy ẩn danh
          return res.json();
        })
        .then(function (data) {
          if (!data || !data.jwt) return;
          window.simplizeLivechatSettings.identity = { jwt: data.jwt, clientId: 'YOUR_CLIENT_ID' };
          // Khung live chat đọc settings lúc khởi động; đã lên rồi thì khởi động lại
          if (window.simplizeLivechat) {
            window.simplizeLivechat.shutdown();
            window.simplizeLivechat.boot();
          }
        });

      // Kênh bắt buộc đăng nhập: khung chat báo về, bạn hiện form đăng nhập của mình
      window.addEventListener('simplize-livechat:sign-in-required', function () {
        window.location.href = '/login?redirect=' + encodeURIComponent(location.href);
      });
    </script>
  </body>
</html>

Khách vãng lai đã chat trước khi đăng nhập giữ nguyên hội thoại sau khi đăng nhập: nền tảng gộp cuộc trò chuyện của khách vãng lai vào tài khoản.

Không đưa assertion lên URL

Đừng dựng liên kết kiểu …/chat/{token}?token=<assertion> — assertion trên URL lọt vào lịch sử trình duyệt, log proxy và header Referer. Dùng setIdentityToken / postMessage / identity như trên.

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; hoặc tải `/embed.js` thay vì `/chat/embed.js`	Đặt cùng một access token ở hai vị trí; đúng đường dẫn `{PLATFORM_URL}/chat/embed.js`
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 `baseUrl` ở 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 assertion bị nền tảng từ chối (`invalid_grant`: sai `aud`, hết hạn, `jti` dùng lại)	Kiểm tra endpoint nhận đúng cookie (`credentials: 'include'`); ký assertion đúng claim theo trang SSO
Chat báo cần đăng nhập	Ứng dụng / kênh bắt buộc đăng nhập nhưng chưa truyền assertion	Truyền assertion, hoặc chuyển hướng sang trang đăng nhập của bạn
Khung chat nhúng bị chặn (trang trắng)	Website của bạn chưa được thêm vào danh sách origin cho phép nhúng	Báo Simplize thêm origin website của bạn

Cần tạo Ứng dụng OAuth và cách ký assertion? Xem Tích hợp đăng nhập (SSO).

1. Chuẩn bị​

Lấy định danh công khai

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

2. Bong bóng chat AI​

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

3. Trang chat AI 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ố​