Quick StartIntegrationAPI ReferenceCustomizationArchitecture

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
}

エラーコード

コードステータス説明
400Bad Request必須フィールドが不足しています
403Forbiddenドメインが許可リストにありません
404Not Foundウィジェットが見つからないか無効です
429Rate Limitedメッセージクォータを超過しました
500Server 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;
  }
}