API
このガイドでは、API エンドポイントを通じて、カスタムの Quickchat AI アシスタントを自社プロダクトに統合するための手順を説明します。
すべてのリクエストに API Key と scenario_id を含めてください。
API キーの取得には、サブスクリプションを API Access 付きのプランへアップグレードしてください。
新しい会話 / 新しいユーザー履歴の初期化
Section titled “新しい会話 / 新しいユーザー履歴の初期化”curl https://chat.quickchat.ai/chat \ -H 'Content-Type: application/json' \ -d '{ "api_key": "<API_KEY>", "scenario_id": "<SCENARIO_ID>", "text": "Hello!"}'
import requests, jsonresponse = requests.post( url="https://chat.quickchat.ai/chat", json={ "api_key": "<API_KEY>", "scenario_id": "<SCENARIO_ID>", "text": "Hello!" })if response.status_code == 200: data = json.loads(response.content)else: raise ValueError( "Error code {}: {}".format( response.status_code, response.content.decode('utf-8')))
上記コマンドは次のような 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_key | string | アカウント作成と購読で API キーを取得してください |
scenario_id | Text | Quickchat API 実装に紐づく ID |
text | string | ユーザーの入力メッセージ |
AI アシスタントへメッセージを送る
Section titled “AI アシスタントへメッセージを送る”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!",}'
import requests, jsonresponse = requests.post( url="https://chat.quickchat.ai/chat", json={ "api_key": "<API_KEY>", "scenario_id": "<SCENARIO_ID>", "conv_id": "abcd1234", "text": "Hello!", })if response.status_code == 200: data = json.loads(response.content)else: raise ValueError( "Error code {}: {}".format( response.status_code, response.content.decode('utf-8')))
上記コマンドは次のような JSON を返します:
{ "ord_number": 236, "reply": "Hey, great to hear from you again! 😉"}
HTTP リクエスト
POST https://chat.quickchat.ai/chat
クエリパラメータ
パラメータ | 型 | 説明 |
---|---|---|
api_key | string | アカウント作成と購読で API キーを取得してください |
scenario_id | string | Quickchat API 実装に紐づく ID |
conv_id | string (任意) | 特定の会話/ユーザーを識別 |
text | string | ユーザーの入力メッセージ |
message_context | string (任意) | 各メッセージに付与する追加コンテキスト。AI にメッセージと一緒に渡されます。 |
client_metadata | dict (任意) | 例 {userId: 12, website: mywebsite.com} 。最大 5 キー。同パラメータは新規メッセージに付与され、Inbox の会話エクスポートで列として表示されます。 |
カスタムのコンテキストとメタデータ付きメッセージ
Section titled “カスタムのコンテキストとメタデータ付きメッセージ”上の表の通り、https://chat.quickchat.ai/chat
では任意パラメータ message_context
と client_metadata
を送信できます。
Client metadata は、各メッセージに付与され、Inbox の会話エクスポートで列として表示されるカスタム属性です。 同様の属性はウィジェット経由のメッセージにも付与できます。
Message context は、ユーザーごとの文脈などを付与し、よりパーソナライズされた会話を実現します。
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}}'
import requests, jsonresponse = requests.post( url="https://chat.quickchat.ai/chat", json={ "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'} })if response.status_code == 200: data = json.loads(response.content)else: raise ValueError( "Error code {}: {}".format( response.status_code, response.content.decode('utf-8')))
API からナレッジベースのタグフィルタを追加
Section titled “API からナレッジベースのタグフィルタを追加”Quickchat AI アプリ では、各 Article にタグを追加できます。タグはナレッジベースのフィルタとして利用でき、AI は指定トピックの Article のみを根拠に回答します。 現時点では、この機能は API 経由でのみサポートされています。
ナレッジベースのトピック(タグ)で絞り込むには、API 呼び出し時の client_metadata
に kb_topic
を追加してください。
重要:kb_topic
キーは、会話の初期化を含めたすべての API 呼び出しにおいて常に存在する必要があります。値自体は呼び出し間で変更可能ですが、キーが継続して存在しなければシステムに考慮されません。
以下は client_metadata
に kb_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 が不足しています | すべての必須パラメータが指定されていることをご確認ください。 |
400 | conv_id abcd1234 は存在しません | 参照している conv_id が正しいことをご確認ください。 |
400 | message context の上限は 1000 文字です | スペースを含め 1000 文字以内に短縮してください。 |
401 | Unauthorized | api_key と scenario_id が正しいことをご確認ください(アプリの Integrations - API を参照)。 |
500 | Internal Server Error | 弊社側の問題です。サポート にご連絡ください。 |
503 | Service Unavailable | サーバー過負荷または一時的なメンテナンス中です。問題が続く場合はサポートにご連絡ください。 |