總覽

Quickchat AI 提供 REST API，讓您以程式方式存取 AI Agent 設定、知識庫、對話、AI Actions 等資源。

選用範例檢查

• 比較部署方式。將您提供的通路、網站存取權與所需功能對照 Quickchat AI 設定選項。不會檢查您的網站或帳戶。

• 檢查範例 MCP 連線。僅會在 Cloudflare 文件或 Microsoft Learn 端點初始化並列出工具。不會登入或執行工具。

驗證

所有 API 端點均使用 Bearer Token 驗證。請在每個請求的 Authorization 標頭加入 API Token：

Authorization: Bearer <API_TOKEN>

Token 可在 Quickchat 控制台的外部應用程式 > API建立。每個 Token 都是包含 scenario_id 的 JWT，因此不需額外的識別標頭。

• Token 有效期：建立後 52 週
• 可隨時在控制台撤銷 Token
• 每個 Token 的範圍限於單一 AI Agent（scenario）
• 建立 Token 需要 Business 方案或更高等級；較低方案會停用此選項，端點則傳回 402 Payment Required

注意

即時聊天端點（POST https://app.quickchat.ai/chat）接受與其他 API 相同的 Bearer Token，但位於 /v1/api/ 基底路徑之外，且請求本文必須包含 scenario_id。完整參照請見聊天頁面。

Token 權限範圍

建立 API Token 時，可選擇兩種權限範圍之一：

權限範圍	存取層級	說明
read_all	唯讀	可讀取所有資源，但無法建立、更新或刪除
write_all	讀取與寫入	可完整存取所有端點，包含寫入操作

• 在控制台的外部應用程式 > API建立 Token 時指定權限範圍
• write_all 自動包含所有 read_all 權限
• 使用 read_all Token 呼叫寫入端點會傳回 403 與 "Insufficient token scope. Required: write_all"

提示

監控、分析與唯讀整合請使用 read_all Token。只有整合需要建立或修改資源時，才使用 write_all Token。

各端點群組所需權限範圍：

端點群組	讀取操作	寫入操作
聊天機器人設定	read_all	write_all
知識庫設定	read_all	write_all
文章	read_all	write_all
文章語言 URL	read_all	write_all
標籤	read_all	無
上傳檔案	無	write_all
匯入外部內容	無	write_all
Intercom 知識庫	read_all	write_all
Widget 設定	read_all	write_all
對話	read_all	無
對話中繼資料	read_all	write_all
轉接設定	read_all	write_all
對話評分	read_all	write_all
AI Actions	read_all	write_all

基底 URL

端點群組	基底 URL
知識庫、AI Actions、上傳檔案、匯入、聊天機器人設定、Widget、轉接、對話評分	https://app.quickchat.ai/v1/api/
對話	https://app.quickchat.ai/v1/api_core/
即時聊天	https://app.quickchat.ai/chat

速率限制

速率限制依每個 Token、每個端點分別套用。

類別	限制	適用操作
READ	每分鐘 120 次請求	GET 與清單操作
WRITE	每分鐘 60 次請求	POST、PATCH、PUT、DELETE
HEAVY	每分鐘 20 次請求	檔案上傳、匯入、擷取

超過速率限制時，API 傳回 HTTP 429 Too Many Requests。

Webhook

Quickchat AI 不會傳送對外 webhook。您無法訂閱事件，要求我們在收到訊息、對話轉接或對話關閉時，向您的端點發送 POST。

可用的替代方式各有不同用途：

• AI Actions 在對話期間呼叫您的 API。API Actions 提供由 AI 決定、首次回覆前與中繼資料符合條件時模式。自動模式會依文件所述條件，在每段對話嘗試呼叫一次；不是訂閱每則訊息或每次轉接。可用於記錄潛在客戶，或在必要資料備齊時通知您的系統。
• Google Sheets 在其 Action 執行時新增一列，不會自動記錄每則訊息或每次轉接。
• 輪詢對話 API 可取得已儲存的對話與事件，包括訊息與已記錄的轉接標記。請遵守分頁規則與上述 READ 速率限制。輪詢會造成延遲；比較兩次輪詢間的對話狀態可能遺漏中間變更。請勿假設這能提供每次轉接或指派變更的完整歷史。

API 存取需要 Business 方案，請參閱方案與限制。

分頁

清單端點透過查詢參數支援分頁：

參數	說明
limit 整數	每頁項目數
offset 整數	要略過的項目數

分頁回應採用以下結構：

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

錯誤處理

所有錯誤均以下列 JSON 格式傳回：

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

狀態	代碼	說明
400	BAD_REQUEST	輸入無效或缺少必填欄位
401	PERMISSION_DENIED	Token 無效、已過期或已撤銷
402	PAYMENT_REQUIRED	需要有效訂閱
403	PERMISSION_DENIED	Token 缺少此操作所需權限範圍
404	NOT_FOUND	找不到資源
409	CONFLICT	操作衝突，例如同時修改
422	VALIDATION_ERROR	請求本文未通過結構描述驗證
429	TOO_MANY_REQUESTS	超過速率限制
500	UNKNOWN	伺服器內部錯誤
503	SERVICE_UNAVAILABLE	暫時無法使用

---