聊天

選用範例檢查

• 預覽 API Action 請求。以合成範例值呈現提供的請求範本，但不傳送。請省略憑證標頭。

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

聊天

即時聊天端點將訪客訊息傳送給 AI Agent，並在一次往返中傳回 AI 回覆。若要在 Quickchat AI 上建立自訂聊天介面，請使用此端點。

它與其他端點有兩個差異：位於 app.quickchat.ai/chat，不在 /v1/api/ 與 /v1/api_core/ 基底路徑內；而且從請求本文而非 Token 讀取 scenario_id。它使用與其他 API 相同的 Bearer Token 驗證。

注意

每個請求都應傳至 https://app.quickchat.ai/chat。本文中的 scenario_id 必須與 Bearer Token 綁定的 AI Agent 相符。

傳送訊息

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

請求本文

參數	說明
scenario_id 字串，必填	AI Agent ID，必須與 Bearer Token 綁定的 scenario_id 相符
text 字串，必填	使用者輸入的訊息
conv_id 字串	對話 ID。首次請求省略以開始新對話，後續請求則傳回收到的 conv_id 以繼續對話
client_metadata 物件	附加至每則訊息的自訂鍵值組，建議最多 5 個鍵。在收件匣匯出的對話中顯示為資料欄位

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

回應 200 OK

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

欄位	說明
conv_id 字串	對話識別碼，一律傳回。將它放入本文的 conv_id 欄位傳回，即可繼續對話
reply 字串	AI Agent 的回覆。可能包含 <br> 換行等 HTML
ord_number 整數	對話中的訊息流水號
src 整數	內部來源指標。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 參數：這些自訂屬性會指派給每則新訊息，並在收件匣匯出的對話中顯示為資料欄位。也可透過 Widget 附加相同屬性。建議每次最多傳送 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()

知識庫標籤篩選

您可以為知識庫文章新增標籤，並用來限制 AI 取用的文章，讓回答僅依據知識庫的一部分。目前此篩選僅支援 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"},
}

錯誤

聊天端點傳回純文字錯誤訊息及適當的 HTTP 狀態碼。

狀態	說明	處理方式
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 Token 或 API 金鑰是否對此 scenario_id 有效
404	未知的 scenario_id（No implementation found for scenario_id <id>）	確認 scenario_id，以及 Bearer Token 是否綁定該 ID
500	伺服器內部錯誤	我們的系統發生問題。請聯絡支援
503	服務無法使用	伺服器暫時過載或正在維護。如果問題持續，請聯絡支援