# 智慧體 API

> 用你自己的程式碼執行 Waslo 智慧體：一個 REST 端點負責回覆，另有知識庫、商品目錄、記憶與日曆——無需控制台。

Source: https://waslo.io/zh-TW/docs/agent-api · Last updated: 2026-10-12

智慧體回覆引擎能做的一切，你的程式碼也能做——包括它的知識庫、記憶、商品目錄、日曆、設定與用量。智慧體 API 對外提供的，正是在 WhatsApp 與 Instagram 上回覆的同一個引擎——同一套知識庫、同樣的按客戶記憶、同樣的日曆與目錄工具——以一個可從你自己產品呼叫的 REST API 呈現。

完整參考與金鑰管理見[開發者入口](/developers)。

## 什麼時候用

- 你已經有 App 或網站，希望 Waslo 在其中回覆，而不是在某個渠道上。
- 你是代理商，想以自己的品牌為客戶執行這個智慧體。
- 你只想單獨用分類、記憶或知識庫檢索，不需要訊息層。

如果你只是想在 WhatsApp 或 Instagram 上有個智慧體，那不需要這個——去[整合](/docs/connecting-channels)裡連接渠道即可。

## 一次呼叫

傳送一則訊息和一個使用者 ID，回傳的回覆已經套用了記憶、知識庫引用與工具動作。

```bash
curl https://api.waslo.io/v1/agent/reply \
  -H "Authorization: Bearer wsk_live_..." \
  -d '{
    "message": "Do you have a morning slot Thursday?",
    "userId": "customer_8842",
    "tools": ["calendar"]
  }'
```

`userId` 由你決定，它是智慧體在多次呼叫之間記住同一個人的依據。沿用它對話就繼續，換掉它就重新開始。

## API 還涵蓋什麼

| 領域 | 你可以做什麼 |
| --- | --- |
| 回覆 | 文字、媒體（圖片、音訊、影片、PDF）與語音輸出 |
| 分類 | 單獨把一則訊息評為 HOT / WARM / COLD |
| 記憶 | 讀取或刪除智慧體對某位使用者的記憶 |
| 知識庫 | 上傳、列出與刪除文件——與控制台共用 |
| 商品目錄 | 對商品的完整增刪改查——與控制台共用 |
| 日曆 | 無需開啟控制台即可連接 Google Calendar 或 Cal.com |
| 設定 | 按請求或長期設定系統提示詞與行為 |
| 用量 | 已消耗額度、目前餘額、支出上限 |

你透過 API 上傳的一切都會出現在控制台，你在控制台新增的一切 API 也看得到。這是同一個工作區，不是兩個。

## API 金鑰

金鑰在[開發者入口](/developers)建立，且**只顯示一次**——它以雜湊形式儲存，我們無法替你找回。每個金鑰帶有權限範圍——`agent`、`memory`、`kb`、`catalog`、`config`、`usage`，以及 `tenants`（僅限 White-label 金鑰）——只能做其權限允許的事。每個組織最多可保留 10 個有效金鑰，可隨時撤銷。

請把金鑰當作密碼：僅限伺服器端，絕不要放進瀏覽器打包產物或行動應用。

## 額度與限流

**API 在所有方案下都按額度計費**——它與渠道訂閱是兩個產品，因此 Growth 訂閱並不會讓 API 呼叫免費。費率高於渠道回覆，因為每次呼叫承擔的工作更多：

| 事件 | 額度 |
| --- | --- |
| 文字回覆 | 2 |
| 呼叫了工具的回覆 | 3 |
| 讀取了媒體（圖片、音訊、影片或 PDF）的回覆 | 5 |
| 語音輸出 | +2 |
| 分類 | 1 |

開發者方案決定你的限流額度，並在你購買之外每月額外贈送一部分額度。沒有方案時，將回落到預設的每分鐘與每日限制。你還可以設定每月支出上限，避免失控的迴圈耗盡餘額——達到上限後請求會以 `spend_cap_reached` 被拒絕。

## 錯誤

所有錯誤都以同一種信封回傳，並帶有一個 `request_id`，聯繫支援時值得一併提供。

| 狀態碼 | 含義 |
| --- | --- |
| 400 | 請求內容未通過驗證 |
| 401 | 缺少或無效的 API 金鑰 |
| 402 | 額度不足，或已達支出上限 |
| 403 | 金鑰的權限範圍不包含此端點 |
| 413 | 請求內容過大 |
| 429 | 觸發限流——請在回應標頭給出的間隔後重試 |

在回覆請求上帶 `Idempotency-Key` 標頭：24 小時內的重複呼叫會回傳原始回應，而不會重複扣費。

## 你的 API 使用者不會進入營運收件匣

透過 API 產生的對話屬於你 App 的使用者，而不屬於盯著 Waslo 收件匣的那個人——因此它們預設在「客戶」和「收件匣」中隱藏。想看時加上 `?includeApi=true`。

## 白標

租戶只存在於 White-label 方案。在該方案下，主金鑰可以建立彼此隔離的租戶工作區，每個都有自己的金鑰、知識庫與商品目錄。母帳戶支付全部用量，並取得按租戶計量的資料用於二次計費；租戶永遠看不到母帳戶餘額。租戶按設計沒有控制台權限——API 就是他們的全部介面，包括[連接日曆](/docs/integrations)。

## 下一步

- [開發者入口](/developers)——建立金鑰、閱讀完整參考、選擇方案
- [知識庫](/docs/knowledge-base)——智慧體作答前會讀什麼
- [商品目錄](/docs/product-catalog)——它能從哪裡成交
- [為什麼這樣回答](/docs/why-this-reply)——每個答案背後的推理軌跡

## 主題

當你的組織定義了主題標籤（2–8 個）後，`POST /v1/agent/reply` 與 `POST /v1/agent/classify` 會包含 `topic` 欄位，`GET/PUT /v1/config` 可讀寫 `topicLabels`——完全 headless，包括 white-label。參見[主題與團隊路由](/docs/team-routing)。

`GET/PUT /v1/config` 也可讀寫 `replyLanguage`：`"auto"` 用每位終端使用者的語言回覆；語言代碼（`"es"`、`"ar"`、`"zh-Hans"`…）一律用該語言回覆；`null` 沿用組織在控制台中的設定（未固定語言時即終端使用者的語言）。
