Conversation Metadata

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

• API 経由で供給 — これらのエンドポイントを使って、任意の会話にプログラムからメタデータを付与します（例：CRM、ヘルプデスク、バックエンドから）
• ウィジェット / embed 経由で供給 — ウィジェットの読み込み時に初期化パラメータとしてメタデータを渡すか、アクティブな会話中に JavaScript SDK を使って動的に注入します
• Dashboard で表示 — メタデータは Inbox の会話詳細ビューに表示されるため、チームは常にコンテキストを把握できます
• エクスポートに含まれる — Dashboard から会話をエクスポートする際にメタデータが含まれ、オフライン分析に利用できます
• AI Actions で使用 — メタデータの値は、{{metadata_<key>}} プレースホルダーとして AI Actions に直接注入できます。利用可能なプレースホルダーの完全なリファレンスは AI Action Variables を参照してください
• AI Agent が利用可能 — AI Agent はメタデータの値を認識しており、会話中にそれらを参照できます。たとえば、顧客の名前やプラン階層を渡すと、AI はそれに応じて応答をパーソナライズします

メタデータは、各会話を動的に誘導しパーソナライズする手段です。顧客 ID、アカウント階層、参照元、A/B テストのバリアント、その他 AI Agent が必要とする任意のコンテキストを渡せます。この機能は今後のリリースで大幅に拡張される予定です。

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

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"
  }
}

---