Ask AI

ⓘ

この機能をご利用いただける方

Pro または Plus プランの管理者が API キーを作成できます。キーには conversations:write が必要です。
ストアの AI アシスタントが有効で、AI の利用枠が残っている必要があります。

Public API のベース URL で POST /ai/ask を使用します。このエンドポイントは回答を生成し、質問と回答の両方を Chatty に保存します。既存のライブチャットの会話に返信を送る操作とは別です。

リクエスト

X-Api-Key と Content-Type: application/json を指定してください。

フィールド	必須	内容
`message`	はい	空白だけではないテキスト。前後の空白を除去する前の長さが 5,000 文字以内である必要があります。
`conversationId`	いいえ	最初の質問では省略します。続けて質問する場合は、以前に成功した `/ai/ask` が返した ID を指定します。
`customer`	いいえ	最初の質問時の連絡先情報です。`email`、`phone`、`name` はそれぞれ任意です。メールアドレスを指定する場合は有効な形式が必要です。2 回目以降の質問では連絡先は更新されません。

curl -s -X POST "https://app.chatty.net/v1/ai/ask" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is your return policy?","customer":{"name":"Example customer","email":"[email protected]"}}'

200 レスポンスの例：

{
  "data": {
    "answer": "Here is the return policy for this store.",
    "conversationId": "conv_123",
    "sources": {},
    "traceId": "trace_123",
    "handoffRequested": false
  }
}

answer の内容はストアのナレッジによって異なります。sources には参照元のデータが入りますが、空の場合もあります。traceId は null の場合があります。handoffRequested は AI が有人対応を要求したことを示します。担当者が引き継ぎを受け付けた、または完了したことを示すものではありません。

会話を続ける

CRM のスレッドに data.conversationId を保存し、次の質問と一緒に送信します。

curl -s -X POST "https://app.chatty.net/v1/ai/ask" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"conv_123","message":"Does that also apply to discounted items?"}'

レスポンスの形式は同じです。Chatty はメモなどの内部コンテンツを除く直近 30 件までのメッセージを読み込み、続きの回答を準備します。解決済みの Public API の会話は、新しい質問を受け取ると再開されます。

このエンドポイントが返した ID を使用してください。 会話が存在しない場合、別のストアの会話の場合、通常のライブチャットの会話の場合は 404 NOT_FOUND を返します。Webhook の conversationId が、そのまま有効な AI セッションになるわけではありません。ライブチャットの ID と AI セッションの ID は別々に保持してください。

最初の質問では、配信チャネルのない会話が作成されます。回答はサーバーに返され、Chatty に保存されます。メールや、顧客との元のライブチャットに自動送信されることはありません。確認した回答をそこへ送るには、Chat Conversations API を使用してください。

エラーと利用枠

HTTP	コード	対処
`400`	`VALIDATION_FAILED`	メッセージ、顧客のメールアドレス、または ID の形式を修正してください。
`401`	`UNAUTHENTICATED` / `INVALID_API_KEY`	API キーとヘッダーを確認してください。
`402`	`AI_USAGE_LIMIT_REACHED`	AI の自動再試行を止め、チームに対応を引き継いでください。利用枠が使えるようになってから再開します。
`403`	`AI_DISABLED`	AI アシスタントを有効にしてから再試行してください。
`403`	`FORBIDDEN`	このスコープ付きキーに `conversations:write` を付与してください。
`404`	`NOT_FOUND`	同じストアの AI セッションであることを確認してください。自動的に別のセッションを開始すると、それまでの文脈が失われます。
`429`	`RATE_LIMITED`	待機時間を延ばしながら再試行してください。レート制限の期間は 60 秒です。このエンドポイントには、Public API 共通の制限に加え、キーごとに 1 分間 20 質問の制限があります。
`500`	`EMPTY_AI_ANSWER`	空白以外の回答が生成されませんでした。空の返信を成功として表示しないでください。
`500`	`INTERNAL_ERROR`	AI プロバイダーまたは他のサービスでエラーが発生しました。処理結果が不明なリクエストを再試行する前に、保存済みメッセージを確認してください。

利用枠の上限に達した場合の例：

{"error":{"code":"AI_USAGE_LIMIT_REACHED","message":"AI usage limit reached"}}

AI が有効かどうかと利用枠の確認は、質問への回答生成や保存の前に実行されます。課金対象の使用量は会話のライフサイクルを通じて確定され、質問のたびに 1 回ずつ加算されるものではありません。今回成功しても、次の質問に必要な利用枠が残っているとは限りません。

この書き込みには冪等性キーがありません。タイムアウト後に再試行すると、質問と回答が重複して作成される場合があります。conversationId を省略した場合は、別の会話が作成される可能性もあります。CRM 連携の例と Errors and rate limits もご覧ください。

MCP から利用する

MCP の ask_ai では message と任意の conversationId を指定できます。API キーでは customer も指定できますが、OAuth ではこのフィールドが無視され、指定した顧客情報は紐付きません。どちらも conversations:write が必要で、OAuth ではメンバーの現在の会話編集権限も確認されます。返り値は HTTP のレスポンスではなく MCP のツールレスポンスです。セッション ID を保存する前にエラーを確認してください。MCP tool reference で詳細をご案内しています。

Help Center CRM Integration