Tài liệu API

Tài liệu tham khảo đầy đủ cho Widget API và REST endpoints.

Widget API

Đối tượng window.LaunchChatWidget toàn cục cung cấp các phương thức để điều khiển widget bằng mã lệnh.

Phương thức

open()

Mở cửa sổ chat bằng mã lệnh.

window.LaunchChatWidget.open();

close()

Đóng cửa sổ chat.

window.LaunchChatWidget.close();

destroy()

Xóa widget khỏi trang hoàn toàn. Hữu ích cho SPA khi chuyển trang.

window.LaunchChatWidget.destroy();

init(config)

Khởi tạo lại widget với cấu hình mới.

window.LaunchChatWidget.init({ widgetId: "new-widget-id" });

on(event, callback)

Đăng ký nhận sự kiện widget.

window.LaunchChatWidget.on('message', (data) => {
  console.log('New message:', data);
});

off(event, callback)

Hủy đăng ký nhận sự kiện widget.

Sự kiện

Sự kiện	Payload	Mô tả
`open`	`{ timestamp }`	Cửa sổ chat đã mở
`close`	`{ timestamp }`	Cửa sổ chat đã đóng
`message`	`{ content, role }`	Tin nhắn đã gửi hoặc nhận
`escalate`	`{ email, message }`	Người dùng yêu cầu hỗ trợ viên
`feedback`	`{ messageId, type }`	Người dùng đã phản hồi (tích cực/tiêu cực)

REST API

POST /api/widget/chat

Gửi tin nhắn và nhận phản hồi do AI tạo.

Request Body

{
  "widgetId": "string",      // Required
  "message": "string",       // Required - user's question
  "conversationId": "string", // Optional - for context
  "visitorId": "string",     // Optional - track visitor
  "pageUrl": "string"        // Optional - current page
}

Response

{
  "conversationId": "uuid",
  "messageId": "uuid",
  "answer": "string",
  "citations": [
    {
      "pageId": "string",
      "pageTitle": "string",
      "pageUrl": "string",
      "excerpt": "string"
    }
  ],
  "relatedArticles": [...],
  "confidenceScore": 0.85,
  "wasRefused": false
}

Mã lỗi

Mã	Trạng thái	Mô tả
`400`	Bad Request	Thiếu trường bắt buộc
`403`	Forbidden	Tên miền không nằm trong danh sách cho phép
`404`	Not Found	Không tìm thấy widget hoặc không hoạt động
`429`	Rate Limited	Vượt quá hạn mức tin nhắn
`500`	Server Error	Lỗi xử lý nội bộ

TypeScript Types

Sao chép các type này vào dự án của bạn để đảm bảo type safety đầy đủ:

interface LaunchChatConfig {
  widgetId: string;
  primaryColor?: string;
  greeting?: string;
  placeholder?: string;
  position?: 'bottom-right' | 'bottom-left';
  theme?: 'light' | 'dark' | 'auto';
}

interface WidgetAPI {
  open(): void;
  close(): void;
  destroy(): void;
  init(config: { widgetId: string }): Promise<void>;
  on<E extends keyof WidgetEvents>(
    event: E,
    callback: (data: WidgetEvents[E]) => void
  ): void;
  off<E extends keyof WidgetEvents>(
    event: E,
    callback: (data: WidgetEvents[E]) => void
  ): void;
}

interface WidgetEvents {
  open: { timestamp: number };
  close: { timestamp: number };
  message: { content: string; role: 'user' | 'assistant' };
  escalate: { email: string; message: string };
  feedback: { messageId: string; type: 'positive' | 'negative' };
}

declare global {
  interface Window {
    LaunchChatConfig?: LaunchChatConfig;
    LaunchChatWidget?: WidgetAPI;
  }
}