API 레퍼런스

Widget API와 REST 엔드포인트의 전체 레퍼런스입니다.

Widget API

전역 객체 window.LaunchChatWidget은 위젯을 프로그래밍 방식으로 제어하는 메서드를 제공합니다.

메서드

open()

채팅 창을 프로그래밍 방식으로 엽니다.

window.LaunchChatWidget.open();

close()

채팅 창을 닫습니다.

window.LaunchChatWidget.close();

destroy()

위젯을 페이지에서 완전히 제거합니다. SPA에서 페이지 이동 시 유용합니다.

window.LaunchChatWidget.destroy();

init(config)

새로운 설정으로 위젯을 다시 초기화합니다.

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

on(event, callback)

위젯 이벤트를 구독합니다.

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

off(event, callback)

위젯 이벤트 구독을 해제합니다.

이벤트

이벤트	페이로드	설명
`open`	`{ timestamp }`	채팅 창이 열림
`close`	`{ timestamp }`	채팅 창이 닫힘
`message`	`{ content, role }`	메시지가 전송 또는 수신됨
`escalate`	`{ email, message }`	사용자가 상담원 연결을 요청함
`feedback`	`{ messageId, type }`	사용자가 피드백(긍정/부정)을 제출함

REST API

POST /api/widget/chat

메시지를 전송하고 AI가 생성한 응답을 수신합니다.

요청 본문

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

응답

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

오류 코드

코드	상태	설명
`400`	Bad Request	필수 필드가 누락되었습니다
`403`	Forbidden	도메인이 허용 목록에 없습니다
`404`	Not Found	위젯을 찾을 수 없거나 비활성 상태입니다
`429`	Rate Limited	메시지 할당량을 초과했습니다
`500`	Server Error	내부 처리 오류

TypeScript 타입

완전한 타입 안전성을 위해 이 타입들을 프로젝트에 복사하세요:

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