Chat

Chat

リアルタイムの Chat エンドポイントは、訪問者のメッセージを AI Agent に送信し、1 回のラウンドトリップで AI の応答を返します。Quickchat AI の上にカスタムチャット UI を構築する際に使用するエンドポイントです。

このエンドポイントは 2 つの点で他のエンドポイントと異なります。/v1/api/ および /v1/api_core/ ベースパスの外側の app.quickchat.ai/chat に位置し、scenario_id をトークンからではなくリクエストボディから読み取ります。認証には、この API の他のエンドポイントと同じ Bearer トークンを使用します。

ノート

すべてのリクエストを https://app.quickchat.ai/chat に送信してください。ボディ内の scenario_id は、Bearer トークンが紐づいている AI Agent と一致している必要があります。

Send Message

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

Request Body

Parameter	Description
scenario_id string, required	AI Agent の ID。Bearer トークンに紐づく scenario_id と一致している必要があります
text string, required	ユーザーの入力メッセージ
conv_id string	会話 ID。最初のリクエストでは省略して新しい会話を開始し、その後返された conv_id を渡して会話を継続します
client_metadata object	すべてのメッセージに付与するカスタムキーバリューペア（5 キー以内を推奨）。Inbox の会話エクスポートにデータ列として表示されます

conv_id を含まないリクエストは新しい会話を開始し、生成された conv_id がレスポンスで返されます。その conv_id を保存し、以降のリクエストで送り返すことで、複数のユーザー操作にわたって会話コンテキストを維持できます。

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Response 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Field	Description
conv_id string	会話識別子。常に返されます。conv_id ボディフィールドに渡し返して会話を継続します
reply string	AI Agent の応答。<br> 改行などの HTML を含む場合があります
ord_number integer	会話内の連番メッセージ番号
src integer	内部的なソース識別子。API クライアントはこのフィールドを無視できます

既存の会話を継続するには、受け取った conv_id を渡し返します：

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Client Metadata

Chat エンドポイントは任意の client_metadata パラメータを受け付けます。これは、すべての新規メッセージに割り当てられ、Inbox の会話エクスポートにデータ列として表示されるカスタム属性です。同じ属性をウィジェット経由で付与することもできます。1 回につき最大 5 キーの送信を推奨します（例：{"userId": 12, "website": "mywebsite.com"}）。これは推奨であり、API が強制する上限ではありません。

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Knowledge Base Tag Filtering

Knowledge Base の記事に tags を追加し、それを使って AI が参照する記事を制限できます。これにより、AI は Knowledge Base の一部のみに基づいて回答します。このフィルタリングは現在 API 経由でのみサポートされています。

タグでフィルタするには、client_metadata に kb_topic キーを追加します。kb_topic キーは、会話を開始するリクエストを含め、会話内のすべてのリクエストに存在している必要があります。その値はリクエスト間で変更できますが、フィルタを適用するにはキー自体が会話全体を通じて存在している必要があります。

以下の例では、your-topic のタグが付いた記事、またはタグがまったく付いていない記事が、応答のための知識の候補プールに含まれます。

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Errors

Chat エンドポイントは、適切な HTTP ステータスコードとともにプレーンテキストのエラーメッセージを返します。

Status	Description	Action
400	scenario_id の欠落、または認証情報が提供されていない	ボディに scenario_id を含め、有効な Authorization: Bearer <API_TOKEN> ヘッダーを指定してください
400	無効な conv_id（Conversation conv_id <id> is not valid.）	conv_id を省略して新しい会話を開始するか、以前のレスポンスで返された conv_id を渡してください
401	無効な認証情報（Unauthorized.）	Bearer トークンまたは API キーがこの scenario_id に対して有効か確認してください
404	不明な scenario_id（No implementation found for scenario_id <id>）	scenario_id と、Bearer トークンがそれに紐づいているか確認してください
500	内部サーバーエラー	当社側の問題です。サポートまで ご連絡ください
503	サービス利用不可	サーバーが一時的に過負荷状態か、メンテナンス中です。問題が解決しない場合はサポートまで ご連絡ください