コンテンツにスキップ

API

このガイドでは、API エンドポイントを通じて、カスタムの Quickchat AI アシスタントを自社プロダクトに統合するための手順を説明します。

すべてのリクエストに API Keyscenario_id を含めてください。

API キーの取得には、サブスクリプションを API Access 付きのプランへアップグレードしてください。

新しい会話 / 新しいユーザー履歴の初期化

Section titled “新しい会話 / 新しいユーザー履歴の初期化”
Terminal window
curl https://chat.quickchat.ai/chat \
-H 'Content-Type: application/json' \
-d '{
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"text": "Hello!"
}'

上記コマンドは次のような JSON を返します:

{
"ord_number": 2,
"conv_id": "abcd1234",
"reply": "Hey there! 🙂"
}

conv_id は任意パラメータです。conv_id を含まないリクエストは新しい会話を開始し、新規の conv_id が返されます。

継続的な会話コンテキストを維持するには、あなたのユーザーに conv_id を関連付けてください。

このエンドポイントは 1 往復の会話を実行します。

HTTP リクエスト

POST https://chat.quickchat.ai/chat

クエリパラメータ

パラメータ説明
api_keystringアカウント作成と購読で API キーを取得してください
scenario_idTextQuickchat API 実装に紐づく ID
textstringユーザーの入力メッセージ

AI アシスタントへメッセージを送る

Section titled “AI アシスタントへメッセージを送る”
Terminal window
curl https://chat.quickchat.ai/chat \
-H 'Content-Type: application/json' \
-d '{
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"conv_id": "abcd1234",
"text": "Hello!",
}'

上記コマンドは次のような JSON を返します:

{
"ord_number": 236,
"reply": "Hey, great to hear from you again! 😉"
}

HTTP リクエスト

POST https://chat.quickchat.ai/chat

クエリパラメータ

パラメータ説明
api_keystringアカウント作成と購読で API キーを取得してください
scenario_idstringQuickchat API 実装に紐づく ID
conv_idstring (任意)特定の会話/ユーザーを識別
textstringユーザーの入力メッセージ
message_contextstring (任意)各メッセージに付与する追加コンテキスト。AI にメッセージと一緒に渡されます。
client_metadatadict (任意){userId: 12, website: mywebsite.com}。最大 5 キー。同パラメータは新規メッセージに付与され、Inbox の会話エクスポートで列として表示されます。

カスタムのコンテキストとメタデータ付きメッセージ

Section titled “カスタムのコンテキストとメタデータ付きメッセージ”

上の表の通り、https://chat.quickchat.ai/chat では任意パラメータ message_contextclient_metadata を送信できます。

Client metadata は、各メッセージに付与され、Inbox の会話エクスポートで列として表示されるカスタム属性です。 同様の属性はウィジェット経由のメッセージにも付与できます。

Message context は、ユーザーごとの文脈などを付与し、よりパーソナライズされた会話を実現します。

Terminal window
curl https://chat.quickchat.ai/chat \
-H 'Content-Type: application/json' \
-d '{
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"conv_id": "abcd1234",
"text": "Hello!",
"message_context": "The users name is John.",
"client_metadata": {userId: 12, website: mywebsite.com}
}'

API からナレッジベースのタグフィルタを追加

Section titled “API からナレッジベースのタグフィルタを追加”

Quickchat AI アプリ では、各 Article にタグを追加できます。タグはナレッジベースのフィルタとして利用でき、AI は指定トピックの Article のみを根拠に回答します。 現時点では、この機能は API 経由でのみサポートされています。

ナレッジベースのトピック(タグ)で絞り込むには、API 呼び出し時の client_metadatakb_topic を追加してください。 重要:kb_topic キーは、会話の初期化を含めたすべての API 呼び出しにおいて常に存在する必要があります。値自体は呼び出し間で変更可能ですが、キーが継続して存在しなければシステムに考慮されません。

以下は client_metadatakb_topic を追加する例です。例では、タグ your-topic が付いた Article と、タグのない Article が回答候補に選ばれます。

json={
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"conv_id": "abcd1234",
"text": "Hello!",
"message_context": "The users name is John.",
"client_metadata": {'kb_topic': 'your-topic'}
}

以下は、API が返す可能性のあるエラーコードの一覧と、説明・対処法です。

コード説明対処
400必須パラメータ api_key, scenario_id, text が不足していますすべての必須パラメータが指定されていることをご確認ください。
400conv_id abcd1234 は存在しません参照している conv_id が正しいことをご確認ください。
400message context の上限は 1000 文字ですスペースを含め 1000 文字以内に短縮してください。
401Unauthorizedapi_keyscenario_id が正しいことをご確認ください(アプリの Integrations - API を参照)。
500Internal Server Error弊社側の問題です。サポート にご連絡ください。
503Service Unavailableサーバー過負荷または一時的なメンテナンス中です。問題が続く場合はサポートにご連絡ください。