Nhúng vào hệ thống nội bộ

SotaAgents có thể chạy ngay bên trong trang web của công ty bạn, dưới dạng bong bóng nổi hoặc panel gắn liền trong trang. Người dùng vẫn đăng nhập bằng hệ thống của bạn và không bao giờ thấy màn hình đăng nhập SotaAgents: backend của bạn xác nhận họ là ai, và nền tảng tin vào chữ ký đó chứ không tin bất cứ thứ gì người dùng gõ vào.

Hai cách nhúng#

Trang này nói về cách thứ hai. Cách thứ nhất xem tại Workspace.

Chuẩn bị trước khi bắt đầu#

• API key và secret tạo tại Console → Tổ chức của bạn → API Keys. Secret chỉ hiện một lần — xem API key.
• Mọi người sẽ dùng embed đều phải là thành viên đang hoạt động của tổ chức. Hệ thống không tự tạo tài khoản: người lạ bị từ chối chứ không được tạo mới. Hãy mời họ trước, hoặc cấp tài khoản qua SSO.
• Một backend do bạn kiểm soát. Secret ký request ở phía server và tuyệt đối không được lộ ra trình duyệt.

Luồng handshake#

Backend của bạn cần làm gì#

Ba việc, và hai việc đầu là chỗ các tích hợp hay sai nhất.

Ký request#

Công thức giống nhau ở mọi ngôn ngữ: dựng chuỗi canonical 5 dòng, HMAC-SHA256 bằng API secret, rồi gửi kết quả dưới dạng v1=<hex chữ thường>. Năm dòng gồm: method, path, timestamp Unix tính bằng giây, nonce, và SHA-256 của body — nối bằng \n, không có newline ở cuối.

POST
/api/embed/auth/tickets
1786800000
3f1c9a7e-5b02-4d6f-9a11-0c8e2d4b7f30
9b2a4c1d8e3f5a70b6c9d2e4f8a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f3a5

import { createHash, createHmac, randomUUID } from 'node:crypto';

const body = JSON.stringify({ externalUserId, email, name }); // serialize ONCE
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomUUID();
const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');

const canonical = ['POST', PATH, timestamp, nonce, bodyHash].join('\n');
const signature = 'v1=' + createHmac('sha256', apiSecret).update(canonical).digest('hex');

import hashlib, hmac, json, time, uuid

body = json.dumps({"externalUserId": external_user_id, "email": email})  # serialize ONCE
timestamp = str(int(time.time()))
nonce = str(uuid.uuid4())
body_hash = hashlib.sha256(body.encode("utf-8")).hexdigest()

canonical = "\n".join(["POST", PATH, timestamp, nonce, body_hash])
signature = "v1=" + hmac.new(
    api_secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256
).hexdigest()

String body = objectMapper.writeValueAsString(payload); // serialize ONCE
String timestamp = String.valueOf(Instant.now().getEpochSecond());
String nonce = UUID.randomUUID().toString();
String bodyHash = HexFormat.of().formatHex(
    MessageDigest.getInstance("SHA-256").digest(body.getBytes(StandardCharsets.UTF_8)));

String canonical = String.join("\n", "POST", PATH, timestamp, nonce, bodyHash);

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = "v1=" + HexFormat.of().formatHex(
    mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8)));

var body = JsonSerializer.Serialize(payload); // serialize ONCE
var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
var nonce = Guid.NewGuid().ToString();
var bodyHash = Convert.ToHexString(
    SHA256.HashData(Encoding.UTF8.GetBytes(body))).ToLowerInvariant();

var canonical = string.Join("\n", "POST", Path, timestamp, nonce, bodyHash);

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = "v1=" + Convert.ToHexString(
    hmac.ComputeHash(Encoding.UTF8.GetBytes(canonical))).ToLowerInvariant();

body, err := json.Marshal(payload) // serialize ONCE
timestamp := strconv.FormatInt(time.Now().Unix(), 10)
nonce := uuid.NewString()
sum := sha256.Sum256(body)
bodyHash := hex.EncodeToString(sum[:])

canonical := strings.Join([]string{"POST", path, timestamp, nonce, bodyHash}, "\n")

mac := hmac.New(sha256.New, []byte(apiSecret))
mac.Write([]byte(canonical))
signature := "v1=" + hex.EncodeToString(mac.Sum(nil))

$body = json_encode($payload); // serialize ONCE
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$bodyHash = hash('sha256', $body);

$canonical = implode("\n", ['POST', $path, $timestamp, $nonce, $bodyHash]);
$signature = 'v1=' . hash_hmac('sha256', $canonical, $apiSecret);

Request thực tế trên đường truyền#

Dù ký bằng ngôn ngữ nào, đây là thứ SotaAgents nhận được. Header timestamp và nonce phải mang đúng giá trị đã đưa vào chuỗi canonical; mỗi nonce chỉ được chấp nhận một lần, và request lặp lại bị từ chối trong vòng 5 phút.

POST https://app.sotaagents.ai/api/embed/auth/tickets
content-type: application/json
x-sota-key: sota_ek_...
x-sota-timestamp: 1786800000
x-sota-nonce: 3f1c9a7e-5b02-4d6f-9a11-0c8e2d4b7f30
x-sota-signature: v1=4d5e...

{"externalUserId":"e-1042","email":"an.tran@company.com"}

SotaAgents trả 201 kèm bao ngoài chuẩn — { success: true, data: { ticket, expiresAt }, timestamp }. Hãy bóc lớp bao: trả object data bên trong về cho trình duyệt, vì SDK đọc ticket ở cấp cao nhất và coi cả bao ngoài là ticket không hợp lệ — lỗi này biểu hiện thành 200 trên đường truyền và một khung chat quay mãi không lên. Response lỗi thì không được bọc; chúng về phẳng dạng { statusCode, code, message }, nên đọc code ở cấp cao nhất. Ticket sống 60 giây và chỉ đổi được một lần.

Giới hạn tần suất. Tạo ticket bị giới hạn 60 request mỗi phút cho mỗi API key và 120 request mỗi phút cho mỗi IP nguồn; bước đổi ticket bên trong iframe bị giới hạn 10 lần mỗi phút, tính theo cả IP người dùng cuối lẫn theo ticket. Vượt ngưỡng sẽ nhận 429 kèm Retry-After — hãy chuyển nguyên nó cho SDK để SDK tự giãn cách và thử lại, đừng gộp vào một lỗi 4xx chung. Toàn bộ backend của bạn dùng chung một IP nguồn, và mọi người sau cùng một NAT văn phòng dùng chung hạn mức đổi ticket, nên hãy ước lượng đợt đăng nhập cao điểm theo các con số này và báo trước cho chúng tôi nếu không đủ.

Frontend của bạn cần làm gì#

Nạp <script src="https://app.sotaagents.ai/embed/sdk.js"></script> rồi khởi tạo. Hai điểm quan trọng: lời gọi xin ticket phải kèm cookie phiên của bạn, và khi đăng xuất phải thu hồi phiên SotaAgents trước.

Origin trong các ví dụ dưới đây chỉ là minh hoạ. Người phụ trách SotaAgents sẽ cấp origin embed riêng cho tenant của bạn, và production khác staging — hãy để origin đó, URL script SDK và base URL của API cấp ticket trong cấu hình chứ không hard-code. SDK từ chối mọi embedUrl không phải HTTPS.

const embed = window.SotaEmbedSDK.createSotaEmbed({
  embedUrl: 'https://app.sotaagents.ai/embed',
  mode: 'bubble',
  getTicket: async () => {
    const response = await fetch('/api/sota/embed-ticket', {
      method: 'POST',
      credentials: 'include',
    });
    if (!response.ok) {
      // Status rides along so the SDK can fast-fail a 401 or 409 instead of
      // retrying a permanent failure four times.
      throw Object.assign(new Error('ticket_failed'), { status: response.status });
    }
    return response.json(); // { ticket, expiresAt }
  },
});

// On sign-out: revoke the SotaAgents session BEFORE clearing your own.
const revoked = await embed.logout();
if (!revoked) console.warn('SotaAgents session may still be active');
await fetch('/api/logout', { method: 'POST', credentials: 'include' });

Tuỳ biến theo thương hiệu của bạn#

Mọi tuỳ chọn ở đây đều không bắt buộc và mặc định đều là bản gốc của SotaAgents — không đặt gì thì giao diện y như hiện tại. Đặt vào thì khung chat mang tên bạn thay vì tên chúng tôi.

createSotaEmbed({
  embedUrl: 'https://app.sotaagents.ai/embed',
  getTicket,

  // Inside the iframe
  language: 'vi',                  // 'en' | 'vi' | 'ja'
  branding: {
    logoUrl: 'https://intranet.acme.com/logo.svg',
    showUser: false,
    greeting: 'How can the Acme assistant help?',
    placeholder: 'Ask about policies, invoices, anything',
  },

  // The bubble chrome, drawn on your own page
  mode: 'bubble',
  title: 'Acme Assistant',
  primaryColor: '#0b5cff',
  position: 'bottom-left',
  width: 420,
  height: 640,
  openOnLoad: false,
});

Hai kiểu gắn. mode chỉ nhận đúng hai giá trị. 'bubble' là mặc định: SDK tự vẽ nút nổi và panel của nó lên trang bạn, còn container bị bỏ qua. 'inline' đặt thẳng iframe vào phần tử bạn chỉ định — không nút nổi, không panel — và ở đó container là bắt buộc, thiếu thì lệnh khởi tạo ném lỗi. Một khác biệt nên tính trước: bubble tạo iframe theo kiểu lười, tới lần bấm đầu tiên mới tạo, nên chưa ai mở chat thì chưa có gì xác thực; inline tạo ngay lúc tải trang, nên endpoint cấp ticket hỏng sẽ lộ ra lập tức và mỗi lượt xem trang tiêu một ticket.

Bên trong khung chat. Các giá trị này đi kèm URL của iframe chứ không chờ đăng nhập xong mới tới, nên khung hình đầu tiên người dùng thấy đã là của bạn — không có cảnh loé lên logo SotaAgents rồi mới đổi.

Greeting và placeholder bị cắt còn 120 ký tự — đủ cho một câu, và đủ ngắn để không đẩy ô soạn tin ra khỏi màn hình.

Khung bubble. Nút nổi và panel do SDK vẽ trên trang của bạn, nằm ngoài iframe. Mọi thứ ở đây trừ title đều bị bỏ qua ở mode: 'inline', nơi container bạn truyền vào quyết định kích thước và trang của bạn quyết định phần xung quanh.

Hai tuỳ chọn nữa thuộc về chính iframe. allowMicrophone mặc định tắt; nhập bằng giọng nói cần bật. sandbox thay cho mặc định allow-scripts allow-same-origin allow-forms allow-popups — và ở đây nó ngược với quy ước HTML quen thuộc: sandbox: '' không phải mức hạn chế chặt nhất, mà gỡ bỏ hẳn thuộc tính, kéo theo mất luôn lớp cách ly của iframe. Muốn siết chặt hơn thì truyền danh sách token hẹp hơn, tuyệt đối không truyền chuỗi rỗng. Đừng động vào cả hai trừ khi có lý do.

Cookie bên thứ ba#

Khi embed chạy trên một site khác với cổng thông tin của bạn, cookie phiên của nó là cookie bên thứ ba.

Cơ chế dự phòng vẫn chạy được, nhưng cứ vài phút lại phải xác thực lại. Phục vụ embed từ một subdomain của chính site bạn qua reverse proxy — ví dụ ai.congty.com đứng trước SotaAgents — sẽ biến cookie thành first-party và xoá bỏ vấn đề này trên mọi trình duyệt. Nếu làm vậy, nhớ hai điều: đừng để proxy sửa Set-Cookie, và phải tắt buffering vì câu trả lời của trợ lý được stream.

Kiểm tra trước khi go-live#

• Secret nằm trong secret manager, không nằm trong source control.
• Mọi người dùng dự kiến đều là thành viên đang hoạt động của tổ chức.
• Endpoint cấp ticket chỉ đọc danh tính từ session.
• logout() được gọi trước khi đăng xuất, trên mọi luồng kết thúc phiên.
• Workspace còn đủ credit — hội thoại nhúng vẫn tiêu credit như mọi hội thoại khác.
• Liên hệ bộ phận hỗ trợ để giới hạn những origin được phép nhúng embed về đúng tên miền của bạn.