Chat API リファレンス

認証

すべてのリクエストは、X-API-Key ヘッダー（または api_key パラメーター）で送信するワークスペースの API キーで認証されます。キーは ck_live_... のような形式です。キーはパスワードと同じように扱ってください。キーを持っている人は誰でも、あなたのワークスペースに課金されるメッセージを送信できます。キーは 設定 -> API アクセス からいつでもローテーションできます。前のキーは即座に無効になります。

メッセージを送信

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

パラメーター:

• message（文字列）- 訪問者のメッセージ。files が添付されていない限り必須です。
• ticket_id（文字列、任意）- 既存の会話を続行します。省略すると新しい会話を開始します。
• visitor_email / visitor_name（文字列、任意）- チケットに連絡先情報を添付します。
• files（マルチパート、任意）- 訪問者の添付ファイル。ファイルアップロードに対応したプランが必要です。

レスポンス

メッセージが保存されるとすぐに 202 Accepted が返されます。AI の返信は非同期で生成されます。

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

会話を継続するには、次の呼び出しで data.ticket_id を ticket_id として渡します。AI の返信を受け取るには、data.id をキーとするチャンネルに WebSocket（ActionCable）で購読します。これは埋め込みウィジェットが使用するのと同じ訪問者ハッシュです。

会話を読み取る

同じ X-API-Key でチケットとそのメッセージを取得できます。すべての読み取りエンドポイントはワークスペースにスコープされており、Business プランで利用できます。

• GET /api/v1/chat/tickets - チケットを新しい順に一覧表示します。クエリパラメータ: status、limit（最大 100）、offset。tickets と pagination を返します。
• GET /api/v1/chat/tickets/:id - 単一のチケット。
• GET /api/v1/chat/tickets/:id/messages - チケットのメッセージを順番に取得します。それぞれに role、content、attachments が含まれます。

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

レート制限とクォータ

リクエストはキーごと（および IP ごと）におおよそ 1 分あたり 20 件に制限されます。生成される各返信は、プランの月間メッセージ枠からも消費されます。枠を使い切ると、エンドポイントは返信を生成せず、data.limit_reached: true を含む 200 を返します。

エラー

• 401 - API キーが指定されていません。
• 404 - キーがどのワークスペースにも一致しません（例: ローテーション後）。
• 403 plan_upgrade_required - ワークスペースが Business プランではありません。
• 403 - サブスクリプションが無効、またはウィジェットの設定で許可されていないドメインからのリクエストです。
• 422 - メッセージがありません（かつファイルも添付されていません）。