Nhúng avatar AI vào website trong 1 dòng code

“Nhúng AI vào website” thường nghe nặng ký hơn thực tế. Với widget của Avatin, phần trình duyệt chỉ cần hai dòng: nạp script và đặt thẻ phần tử. Phần cần suy nghĩ nằm ở backend — nơi giữ API key và cấp token phiên. Bài viết đi qua cả hai.

Phía trình duyệt: hai dòng

<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>

<avatin-widget> là Web Component — chạy được trên mọi stack: WordPress, Next.js, Laravel, site tĩnh. Thẻ hiển thị nút tròn ở góc màn hình; khách bấm vào sẽ qua màn công bố AI, rồi mới vào phiên hội thoại. Widget tự lo: xin quyền micro, hiển thị phụ đề, chip trích dẫn, đánh giá cuối phiên, và tự chuyển sang chỉ chat khi micro bị từ chối.

Phía backend: token một lần

Widget không mang API key của bạn trong trình duyệt — nguyên tắc bảo mật mặc định. Thay vào đó, nó gọi token-endpoint do bạn khai báo, trỏ tới một route nhỏ trên backend của bạn:

1. Route của bạn gọi POST /v1/sessions/token của Avatin bằng Authorization: Bearer avk_… (API key, giữ ở server).
2. Avatin trả về token ES256 dùng một lần, hết hạn sau 10 phút.
3. Route của bạn trả token đó cho trình duyệt.
4. Widget đổi token ở POST /v1/public/sessions/exchange để nhận thông tin kết nối phiên hội thoại.

Việc đổi token được Core API kiểm tra origin trước khi tiêu token: trang lạ sao chép mã nhúng cũng không dùng được agent của bạn. Token đã tiêu thì dùng lại chỉ nhận lỗi — không có nguy cơ phát lại.

Ba điều đáng cấu hình ngay từ đầu

• Allowlist origin: khai báo đúng các domain được phép nhúng agent trong Studio — lớp kiểm tra server sẽ ép theo đó.
• Biến ngữ cảnh: đặt tên khách, phân khúc khách qua variables khi backend cấp token; lời chào dùng biến như {{customer_name}}. Nhớ lấy giá trị từ phiên đăng nhập của bạn, không tin dữ liệu trình duyệt gửi lên.
• Webhook session.ended: nhận thông báo khi phiên kết thúc để thống kê số phiên và thời lượng trong hệ thống của bạn.

Khi cần nhiều hơn widget

Widget phủ hầu hết trường hợp trên website. Khi cần kiểm soát giao diện hoàn toàn hoặc nhúng vào app native, bước tiếp theo là SDK Web (@avatin/sdk-web) và REST API — cùng bộ token, sự kiện và webhook như trên, chỉ thay đổi lớp hiển thị. Toàn bộ hợp đồng được mô tả trong tài liệu tích hợp, với quickstart cho từng mức.

Tóm lại

Từ một dòng script tới một tích hợp full-stack, đường đi là liền mạch: cùng agent, cùng tri thức, cùng sự kiện. Bắt đầu bằng widget để xác nhận giá trị với khách thật, rồi nâng cấp lớp tích hợp khi cần — không phải dựng lại từ đầu.