Conversation Metadata

Conversation Metadata を使うと、会話にカスタムキーバリューデータを付与でき、自社システムと AI Agent の間に強力な橋を架けられます。メタデータは Quickchat のワークフロー全体を流れます：

• API 経由で供給 — これらのエンドポイントを使って、任意の会話にプログラムからメタデータを付与します（例：CRM、ヘルプデスク、バックエンドから）
• ウィジェット / embed 経由で供給 — ウィジェットの読み込み時に初期化パラメータとしてメタデータを渡すか、アクティブな会話中に JavaScript SDK を使って動的に注入します
• Dashboard で表示：カスタムメタデータは受信箱の会話詳細に表示されます。内部キーは除外され、取得した連絡先情報と Action のメモリはそれぞれ専用の形式で表示されます
• エクスポートに含まれる — Dashboard から会話をエクスポートする際にメタデータが含まれ、オフライン分析に利用できます
• AI Actions で使用 — メタデータの値は、{{metadata_<key>}} プレースホルダーとして AI Actions に直接注入できます。利用可能なプレースホルダーの完全なリファレンスは AI Action Variables を参照してください
• 許可された場合に AI Agent が利用可能：モデルのコンテキストには、フィルタリングされたメタデータの一部が使われます。キーを保存しても、モデルがその値を受け取ったり言及したりするとは限りません

メタデータは、顧客の参照情報、アカウントのコンテキスト、分析、Action への入力に利用できます。保存、受信箱への表示、Action での値の置換、モデルのコンテキストへの組み込みは、同じデータの別々の用途です。

メタデータは、Dashboard で設定されている場合は JSON スキーマに対してバリデーションされます。

モデルのコンテキストと認可

Web サイトのウィジェットや Embed など、訪問者が入力を制御できるチャネルでは、訪問者の連絡先キー（visitor_name、visitor_email、visitor_phone_number）と、有効な Action が参照または取得するキーのうち条件を満たすものが、モデルのコンテキストに含まれます。内部用の値や予約済みの値は除外され、設定やサイズによる制限も適用されます。他の連携には、チャネル固有のコンテキストルールがあります。customer_tier や customer_id などのカスタムキーは、送信しただけで自動的にモデルから見えるようになるわけではありません。

Action はリクエストを組み立てる際に、AI に値を生成させずに {{metadata_<key>}} を置換できます。ただし、通常のメタデータが秘密になるわけではありません。条件を満たす値は、別途モデルのコンテキストに含まれたり、Action のレスポンスに現れたりする可能性があります。カスタムメタデータに API キーやパスワードを保存しないでください。

ブラウザから送られたメタデータは、本人確認や権限の証明にはなりません。受信側のサービスで、非公開レコードへのアクセスを認証・認可する必要があります。ブラウザから送信された顧客 ID やプラン階層だけでは不十分です。ご自身の設定で、実際の Action リクエストと Agent の返信の両方をテストしてください。

Get Metadata

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

Set Metadata

会話のメタデータを作成または更新します。

Scope: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Request Body

Parameter	Description
metadata object, required	保存するキーバリューメタデータ

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---