Quickstart — SDK Web

@avatin/sdk-web bọc livekit-client và toàn bộ logic phiên (token, origin, cold start, mic, phụ đề, citation, CSAT) — bạn tự vẽ giao diện. livekit-client được nạp lười, không nằm trong bundle chính.

Cài đặt

pnpm add @avatin/sdk-web

Kết nối phiên

import { createAvatinClient, createTokenSessionProvider } from "@avatin/sdk-web";

const client = createAvatinClient({
  sessionProvider: createTokenSessionProvider({
    apiUrl: "https://api.avatin.ai", // Core API
    tokenProvider: async () => {
      // Route backend của bạn (giữ API key ở server) trả { token }
      const res = await fetch("/api/avatin-session", { method: "POST" });
      if (!res.ok) throw new Error("token endpoint lỗi");
      return res.json(); // { token, exchangeUrl? }
    },
    getConsentGivenAt: () => new Date().toISOString(), // thời điểm người dùng tích đồng ý AI
  }),
});

// 2. Lắng nghe trước khi connect
client.on("state.changed", (s) => console.log("state:", s));
client.on("message.final", ({ role, text }) => renderMessage(role, text));
client.on("citations", (citations) => renderCitationChips(citations));

// 3. Nối phòng (gọi trong handler chạm nếu dùng micro trên iOS)
await client.connect();

Thứ tự gọi để iOS Safari chịu: unlockAudio() rồi acquireMic() đồng bộ trong handler chạm, trước mọi await mạng, sau đó mới connect().

Client action — agent điều khiển app của bạn

client.registerAction("open_screen", async (args) => {
  router.push(String(args.screen));
  return { ok: true }; // kết quả đưa lại cho agent
});

Agent gửi yêu cầu action qua data channel và chờ kết quả tối đa 15 giây; quá hạn agent nói câu chờ và tiếp tục. Kết quả trả về từ trình duyệt được coi là dữ liệu không tin cậy — agent gắn nhãn và giới hạn độ dài trước khi đưa vào hội thoại.

Kết thúc phiên và CSAT

await client.disconnect(); // gọi /end bằng endToken, nhả slot ngay

// Đánh giá cuối phiên (mỗi phiên một lần)
await client.submitCsat(5, "Nhanh và đúng biểu phí");

Sự kiện chính

Sự kiện	Khi nào
state.changed	Trạng thái kết nối/cold start thay đổi
message.final	Mỗi lượt hội thoại hoàn tất (role agent/user)
citations	Câu trả lời có mốc trích dẫn tri thức
lead.created	Agent thu được lead từ người dùng

Dev/test không cần Core API

import { createMockSessionProvider } from "@avatin/sdk-web";

const client = createAvatinClient({
  sessionProvider: createMockSessionProvider(), // phiên giả để dựng UI
});