API

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

認証

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

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

チャット

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

Shell
Python

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

import requests, json
response = 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	ユーザーの入力メッセージ

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, json
response = 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 の会話エクスポートで列として表示されます。

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

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

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

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

Shell
Python

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, json
response = 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 からナレッジベースのタグフィルタを追加

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	サーバー過負荷または一時的なメンテナンス中です。問題が続く場合はサポートにご連絡ください。

API

認証

チャット

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

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

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

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

エラー

Get started

Conversations

AI Agent

Channels