Quickstart — Widget một dòng script

<avatin-widget> là Web Component (Lit) nhúng avatar hội thoại vào bất kỳ trang nào — không phụ thuộc framework. Widget tự lo: công bố AI + đồng ý, xin quyền micro (đúng thứ tự cho iOS Safari), phụ đề, chip trích dẫn, đánh giá CSAT cuối phiên.

1. Thêm script và thẻ

<script type="module" src="https://cdn.avatin.ai/avatin-widget.js"></script>
<avatin-widget
  api-url="https://api.avatin.ai"
  token-endpoint="/api/avatin-session">
</avatin-widget>

• api-url — gốc URL Core API.
• token-endpoint — route của backend trang chủ (giữ API key) trả { "token": "…" }.

2. Route token phía backend của bạn

Widget gọi token-endpoint của bạn; route đó gọi POST /v1/sessions/token của Avatin bằng API key:

// Ví dụ Node/Next.js route handler
const res = await fetch(`${AVATIN_API_URL}/v1/sessions/token`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.AVATIN_API_KEY}`, // avk_…
  },
  body: JSON.stringify({
    agentId: process.env.AVATIN_AGENT_ID, // lấy từ Studio
    channel: "widget",
    variables: { customer_name: "Minh" }, // giá trị lấy từ phiên đăng nhập của bạn
  }),
});
const { token, expiresAt, expiresIn } = await res.json();
return new Response(JSON.stringify({ token, expiresAt, expiresIn }), {
  headers: { "content-type": "application/json" },
});

Quan trọng: giá trị variables lấy từ phiên đăng nhập của chính bạn — không tin dữ liệu trình duyệt gửi lên.

3. Cho phép domain nhúng

Trong Studio, đặt allowlist origin của agent theo domain trang nhúng. Core API kiểm tra origin trước khi tiêu token — trang lạ sao chép mã nhúng không dùng được agent, token cũng không bị đốt.

4. API của widget trên trang

const widget = document.querySelector("avatin-widget");

// Đăng ký client action (agent gọi để điều khiển trang của bạn)
widget.registerAction("open_screen", (args) => {
  router.push(String(args.screen));
});

// Lắng nghe sự kiện
widget.on("message.final", ({ role, text }) => console.log(role, text));
widget.on("lead.created", (lead) => console.log("lead:", lead));

Lỗi thường gặp

Mã lỗi	Nguyên nhân	Xử lý
ORIGIN_NOT_ALLOWED	Trang nhúng không nằm trong allowlist của agent	Thêm origin trong Studio
INVALID_SESSION_TOKEN	Token sai/hết hạn/đã dùng	Kiểm tra route token, thời hạn 10 phút
TOKEN_*	Route token lỗi cấu hình	Route phải trả { token } dạng JSON
Micro bị từ chối	Người dùng không cấp quyền	Widget tự chuyển sang chế độ chat