聊天機器人 API 整合：REST、Zapier 與 Webhook 完整說明

聊天機器人 API 是一個 HTTP 介面，讓你能以程式設計方式傳送訊息給 AI 聊天機器人並接收回應——不需要使用視覺化小工具。與其讓使用者在聊天氣泡中輸入文字，你的程式碼可以直接發送請求、取得回覆，並對結果做進一步處理：渲染自訂介面、記錄答案、觸發動作，或把結果路由到另一個系統。

本指南會說明什麼是聊天機器人 API、什麼時候該選擇它而非嵌入式小工具、三種主要的連接方式（REST、Zapier 與 Webhook），以及建立實際整合的實用模式。

什麼是聊天機器人 API？

聊天機器人 API 會把你訓練好的 AI 聊天機器人，公開成一個任何程式碼都能透過 HTTP 呼叫的服務。你在請求主體中傳送使用者的訊息，API 就會回傳聊天機器人的答案——答案來自你用來訓練它的任何來源（網站內容、文件、問與答）。

與現成小工具最大的差異在於：API 回傳的是原始資料，如何呈現則由你的應用程式決定。這代表你可以把同一個聊天機器人嵌入行動應用程式、Slack 機器人、內部儀表板，以及後端自動化流程——全部共用同一套訓練好的知識庫。

大多數聊天機器人 API 都遵循類似的模式：

1. 驗證身分 —— 在 Authorization 標頭中加入 API 金鑰。
2. POST 一則訊息 —— 傳送使用者的文字內容、聊天機器人 ID，並可選擇性附上對話 ID 以維持多輪對話的脈絡。
3. 處理回應 —— 解析回覆內容，可選擇以串流方式即時顯示 token，並儲存 conversationId 供下一輪使用。

如果你的團隊還在比較各種聊天機器人選項、尚未決定平台，可參考網站最佳 AI 聊天機器人總覽，了解該關注哪些重點。

什麼時候該用 API，什麼時候該用小工具

嵌入式小工具能處理多數的網站使用情境。當你需要小工具無法提供的功能時，API 才是正確的選擇。

如果你的使用情境落在右欄，API 就是正確的工具。完整的嵌入選項——小工具、React 元件、iframe 與 WordPress 外掛程式——可參考聊天機器人整合指南。

連接方式與方案適用範圍

有三種方式能把你的聊天機器人連接到外部系統，各自有不同用途，也適用於不同方案。

REST API 給你最完整的掌控權。如果你不需要自訂程式碼，Zapier 的設定速度更快。Webhook 則能同時補足兩者——它會主動把資料推送給你，而不是等你去拉取。

想完整了解每個方案包含的內容，可參考聊天機器人成本與定價指南。

方案需求

年繳方案能讓每個方案的價格降低約 20%。API 送出的訊息，會和小工具的訊息一樣計入你的每月額度。

身分驗證

每個 API 請求都需要 Bearer 權杖。你可以在 Agentkit 儀表板的工作區設定中產生 API 金鑰。

產生 API 金鑰

1. 開啟你的 Agentkit 工作區。
2. 前往設定，接著點選 API 金鑰。
3. 點選建立 API 金鑰。
4. 為它取一個描述性的名稱（例如「Slack Bot Production」）。
5. 立即複製金鑰，之後將不會再顯示。

在請求中使用金鑰

在 Authorization 標頭中加入你的 API 金鑰：

Authorization: Bearer ak_live_your_api_key_here

所有請求都必須透過 HTTPS 傳送。沒有附上有效權杖的請求，會收到 401 Unauthorized 回應。

金鑰管理最佳做法

• 把 API 金鑰儲存在環境變數中，絕對不要放在用戶端程式碼裡。
• 定期輪換金鑰，尤其是在團隊成員異動之後。
• 為不同的整合建立各自獨立的金鑰，這樣你就能撤銷其中一個，而不影響其他整合。
• 刪除不再使用的金鑰。

完整的驗證細節，可參考身分驗證說明文件。

聊天端點

這個 API 的核心，是一個單一端點，能把使用者的訊息傳送給你的聊天機器人，並回傳 AI 的回應。

請求

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer ak_live_your_api_key_here

請求主體：

{
  "chatbotId": "your-chatbot-id",
  "message": "What are your shipping options?",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id",
  "metadata": {
    "page": "/products/shoes",
    "userTier": "premium"
  }
}

回應

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "message": "We offer three shipping options: Standard (5-7 business days, free over $50), Express (2-3 business days, $9.99), and Overnight ($24.99). All orders include tracking.",
  "sources": [
    {
      "title": "Shipping Policy",
      "url": "https://example.com/shipping"
    }
  ],
  "createdAt": "2026-02-22T14:30:00Z"
}

回應中的 conversationId 很重要，請儲存它並在後續請求中傳回，以維持對話脈絡。如果沒有它，每則訊息都會開啟新對話，聊天機器人也會失去上下文。

錯誤回應

完整的端點參考資料，可參考 API 說明文件。

串流回應

如果你想在即時應用程式中，讓回應隨著生成過程逐字顯示（也就是使用者對 AI 聊天所期待的打字機效果），可以使用 Server-Sent Events（SSE）。

在你的請求中加入 stream: true 參數：

{
  "chatbotId": "your-chatbot-id",
  "message": "Explain your return policy",
  "conversationId": "conv_xyz789",
  "stream": true
}

回應會以一連串的 SSE 事件形式送達：

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "token", "content": " allows"}
...
data: {"type": "sources", "sources": [{"title": "Return Policy", "url": "https://example.com/returns"}]}
data: {"type": "done", "conversationId": "conv_xyz789", "messageId": "msg_def456"}

在 JavaScript 中處理串流

const response = await fetch('https://api.agentkit.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ak_live_your_api_key_here'
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    message: 'Explain your return policy',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'token') {
      appendToUI(data.content);
    }
  }
}

對任何面向使用者的整合來說，都建議使用串流——即使在生成較長的答案時，也能讓聊天機器人感覺反應靈敏。

Webhook

聊天端點讓你能把訊息傳送給聊天機器人，Webhook 則反過來，讓聊天機器人把資料傳送給你。當特定事件發生時，Agentkit 會對你設定的 URL 發送一個 HTTP POST 請求。Webhook 從 Hobby 方案起提供。

設定 Webhook

1. 前往你工作區的設定，接著點選 Webhook。
2. 輸入你的端點網址（必須是 HTTPS）。
3. 選擇要訂閱的事件。
4. 儲存。Agentkit 會發送一個驗證請求，確認你的端點可以正常連線。

可用事件

Webhook 酬載

每個 Webhook POST 請求，都會包含結構一致的 JSON 主體：

{
  "event": "lead.captured",
  "timestamp": "2026-02-22T15:45:00Z",
  "chatbotId": "your-chatbot-id",
  "conversationId": "conv_xyz789",
  "data": {
    "name": "Alex Chen",
    "email": "[email protected]",
    "message": "Interested in the enterprise plan"
  },
  "signature": "sha256=abc123..."
}

務必用你的 Webhook 簽署祕密驗證 signature 欄位，確認這個請求確實來自 Agentkit，而非第三方。

重試行為

如果你的端點回傳非 2xx 狀態碼，Agentkit 會以指數退避的方式重試：分別在 1 分鐘、5 分鐘、30 分鐘後重試，之後便會停止。傳送失敗的紀錄可以在儀表板的 Webhook 紀錄中查看。

常見整合模式

模式一：Slack 機器人

把來自網站聊天機器人的客戶問題轉發到 Slack 頻道，在 AI 無法回答時，讓你的團隊接手回覆。

1. 建立一個啟用傳入 Webhook 的 Slack 應用程式。
2. 為 conversation.completed 事件設定一個 Agentkit Webhook。
3. 在你的 Webhook 處理程序中，檢查對話是已解決還是已升級。
4. 如果已升級，就把包含對話紀錄的格式化訊息 POST 到你的 Slack Webhook 網址。

這樣一來，你的客服團隊不需要盯著 Agentkit 儀表板，也能掌握對話狀況。

模式二：自訂聊天介面

用內建在你應用程式裡的聊天體驗，取代預設的小工具。

1. 用你偏好的框架建立聊天介面。
2. 在訊息送出時，以 stream: true 呼叫聊天端點。
3. 隨 token 抵達逐步渲染，提供即時回饋。
4. 把 conversationId 儲存在本地狀態中，以維持跨訊息的對話脈絡。

這種做法適合行動應用程式、桌面應用程式，或任何浮動小工具不符合設計需求的產品。如果你的團隊想繼續使用小工具、但需要對顯示位置有更多掌控，可參考在網站上嵌入聊天機器人指南，其中涵蓋所有四種嵌入方式。

模式三：後端自動化

把聊天機器人當作更大工作流程中的 AI 層，完全不需要聊天介面。

範例：處理支援工單。

1. 新工單進入你的工單系統。
2. 你的後端把工單內容傳送到聊天端點。
3. 聊天機器人根據你訓練好的知識庫，產生建議回覆。
4. 你的系統可以自動回覆（如果信心程度夠高），或把建議排入佇列供真人審核。

這種模式之所以有效，是因為聊天機器人使用的是與你客服團隊相同的知識庫。API 讓你能以程式設計方式存取這份智慧。想進一步了解能用什麼內容訓練聊天機器人——網站檢索、PDF、CSV、問與答——可參考如何訓練聊天機器人。

模式四：分析流程

擷取每一次對話以供分析。

1. 訂閱 message.received 與 message.sent 這兩個 Webhook 事件。
2. 你的 Webhook 處理程序把事件寫入你的資料倉儲（BigQuery、Snowflake 等）。
3. 建立儀表板，呈現常見問題、解決率、尖峰時段與對話趨勢。

聊天端點中的 metadata 欄位，讓你能附加情境資訊（頁面網址、使用者區隔、A/B 測試變體），豐富你的分析資料。

速率限制

為了確保服務對所有使用者都穩定可靠，API 會強制實施速率限制。

當你達到限制時，API 會回傳 429 狀態碼，並附上 Retry-After 標頭，告訴你需要等待幾秒。請在你的整合中加入重試邏輯：

async function sendMessage(payload, retries = 3) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
  });

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendMessage(payload, retries - 1);
  }

  return response.json();
}

安全性考量

在建立 API 整合時，請留意以下做法：

• 絕對不要在用戶端程式碼中暴露 API 金鑰。 如果你正在為網頁應用程式建立自訂聊天介面，請透過你自己的後端代理請求。
• 驗證 Webhook 簽章。 在處理 Webhook 酬載之前，務必先驗證 HMAC 簽章。
• 使用網域限制。 在你的聊天機器人設定中，限制哪些網域能與你的聊天機器人互動。
• 監控用量。 定期在儀表板檢查你的 API 用量，及早發現可能代表金鑰外洩的異常尖峰。
• 遵循最小權限原則。 如果一個整合只需要傳送訊息，就不要給它擁有管理員權限的金鑰。

如果你的團隊正在探索 AI 聊天機器人 API 如何連接更大的工具生態系，值得了解一下 MCP（Model Context Protocol）——這是一個讓 AI 模型能以結構化方式存取外部工具與資料的新興標準。

開始使用

從零開始建立一個能運作的整合，最快的路徑是：

1. 註冊 Agentkit 帳號，並建立你的第一個聊天機器人。
2. 用你的內容訓練聊天機器人（參考如何訓練聊天機器人）。
3. 升級到 Hobby 方案（$29.99／月）以啟用 API 存取權限。
4. 在你的工作區設定中產生一組 API 金鑰。
5. 使用 cURL 或 Postman 發送你的第一個測試請求。
6. 接下來就能依你的需求繼續打造：自訂介面、Slack 機器人、自動化，或任何你需要的情境。

常見問題

什麼是聊天機器人 API 金鑰？

聊天機器人 API 金鑰是一組祕密權杖，用來在你的應用程式向聊天機器人 API 發出請求時驗證身分。你可以在工作區設定中產生它，並在每個請求的 Authorization: Bearer 標頭中附上它——把它當成密碼一樣對待：儲存在環境變數中，絕不放進用戶端程式碼，若懷疑外洩就立即輪換。每組金鑰都能限定用於特定整合，讓你能撤銷其中一個，而不影響其他整合。

有免費的聊天機器人 API 嗎？

Agentkit 的 Free 方案（$0／月）不包含 REST API 存取權限，這需要 $29.99／月的 Hobby 方案。Free 方案確實包含可嵌入的 JS 小工具、潛在客戶收集，以及網域限制，不需要任何程式碼就能涵蓋多數網站使用情境。如果你從第一天就需要程式化存取，Hobby 方案就是入門選項，而且升級前你可以先免費測試整個平台。

使用聊天機器人 API 需要會寫程式嗎？

不一定。如果你需要 REST API 存取權限來建立自訂整合，就需要寫程式——或使用 Postman 之類的工具手動測試呼叫。但如果你的目標只是在無程式碼的情況下把聊天機器人連接到其他應用程式，Hobby 方案以上提供的 Zapier 整合，能透過無程式碼介面連接 7,000+ 個應用程式。至於網站嵌入，除了貼上一段 <script> 標籤之外，完全不需要寫程式碼。

聊天機器人 API 支援哪些 AI 模型？

底層的 AI 模型是在儀表板中依聊天機器人個別設定的。Agentkit 支援來自三家供應商的模型：OpenAI（GPT-5.6 Sol、GPT-5.6 Terra、GPT-5.6 Luna）、Anthropic（Claude Opus 5、Claude Sonnet 5、Claude Haiku 4.5），以及 Google（Gemini 3.7 Flash、Gemini 3.1 Pro）。預設模型為 GPT-5.6 Luna。你的 API 呼叫會使用該聊天機器人所選定的模型——你不需要在 API 呼叫層級指定模型。

我可以用聊天機器人 API 把聊天功能嵌入我的網站嗎？

可以，但對網站使用情境來說，JS 小工具嵌入方式通常更簡單。小工具會透過單一 <script> 標籤非同步載入，並自動處理介面、對話狀態與串流。當你需要完全自訂的介面、行動應用程式整合，或後端自動化時，才需要使用 API。所有嵌入選項的並列比較，可參考在網站上嵌入聊天機器人指南。

聊天機器人 API 把一套訓練好的知識庫，變成一個可呼叫的服務——出現在小工具中的相同 AI 答案，任何能發出 HTTP 請求的系統都能取得。無論你是要打造自訂介面、自動化客服流程，還是把聊天機器人連接到更大的工具生態系，API 都能給你現成小工具無法提供的掌控權。

免費建立你的聊天機器人 → 不需信用卡。