對話中繼資料

對話中繼資料可讓您將自訂鍵值資料附加至對話，在自己的系統與 AI Agent 之間建立強大的連結。中繼資料會貫穿整個 Quickchat 工作流程：

• 透過 API 提供：使用這些端點，以程式方式將中繼資料附加至任意對話，例如來自 CRM、客服系統或後端的資料
• 透過 Widget/嵌入區塊提供：載入 Widget 時以初始化參數傳入中繼資料，或在進行中的對話使用 JavaScript SDK 動態注入
• 顯示於控制台：自訂中繼資料會出現在收件匣的對話詳細資料。內部鍵會被篩除，而收集的聯絡資料與 Action 記憶有各自的呈現方式
• 包含在匯出中：從控制台匯出對話時包含中繼資料，可供離線分析
• 用於 AI Actions：中繼資料值可直接以 {{metadata_<key>}} 占位符注入 AI Actions。完整的可用占位符參照請見 AI Action 變數
• 獲准時提供給 AI Agent：模型脈絡使用經篩選的中繼資料子集。儲存一個鍵不保證模型會收到或提及它

中繼資料可用於客戶參照、帳戶脈絡、分析與 Action 輸入。儲存、收件匣顯示、Action 值替換與模型脈絡，是同一份資料的不同用途。

如果已在控制台設定 JSON schema，中繼資料會依該結構描述驗證。

選用範例檢查

• 預覽中繼資料鍵。檢查提供的欄位名稱如何轉為變數鍵，包括重複名稱與保留鍵錯誤。不會檢查值或帳戶專屬權限。

• 檢查 Action 執行條件。使用提供的範例中繼資料評估條件，不會執行 Action。

相容瀏覽器也能將這些檢查作為網站工具使用。連結會開啟一般表單。

模型脈絡與授權

在網站 Widget 與嵌入區塊等訪客可控制的通路，模型脈絡允許訪客聯絡鍵（visitor_name、visitor_email、visitor_phone_number）以及啟用中 Actions 引用或擷取的合格鍵。內部與保留值會被篩除，也會套用設定與大小限制。其他整合有各通路專屬的脈絡規則。自訂的 customer_tier 或 customer_id 鍵，不會僅因您傳送了它就自動對模型可見。

Action 建立請求時可替換 {{metadata_<key>}}，不必要求 AI 產生該值。這不代表一般中繼資料是秘密：合格的值可能另外進入模型脈絡，或出現在 Action 回應中。請勿將 API 金鑰或密碼儲存於自訂中繼資料。

瀏覽器提供的中繼資料不是身分或權限的證明。接收請求的服務必須驗證身分，並授權對私人紀錄的存取；瀏覽器傳來的客戶 ID 或方案等級並不足夠。請針對自己的設定，同時測試產生的 Action 請求與 Agent 回覆。

取得中繼資料

權限範圍：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()

回應 200 OK

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

設定中繼資料

建立或更新對話的中繼資料。

權限範圍：write_all

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

請求本文

參數	說明
metadata 物件，必填	要儲存的鍵值中繼資料

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()

回應 200 OK

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

---