適用方案：Advanced、Enterprise 以及部分 Legacy 方案可用。測試對所有使用者開放，但發布需符合方案資格。

Make HTTP requests 動作可讓您的 AI 代理在對話期間呼叫外部 API。這可讓 AI 代理根據聯絡人的請求擷取即時資料或在外部系統觸發操作。例如，它可以檢查訂單狀態、擷取帳戶資訊或在其他系統建立記錄。在本文中，您將學習如何設定 HTTP 請求動作並使用 AI 代理測試它。

AI 代理：

分析聯絡人的訊息，以判斷是否符合您在動作說明中定義的意圖。
收集任何所需資訊。
發送 HTTP 請求。
解析 API 回應。
自然回覆聯絡人。

新增發出 HTTP 請求動作

開啟該動作，然後點選「Add action」按鈕以開始設定您的 HTTP 請求。

定義動作執行時機

在 動作名稱 欄位為該動作提供描述性名稱。

在 何時以及如何執行此動作？ 欄位，描述：

AI 代理何時應使用此動作
它會擷取或傳送的內容
要處理的任何條件或結果

範例：

當聯絡人詢問訂單時，使用此動作擷取其訂單狀態。 若 API 回傳 404 錯誤，請告知聯絡人無法找到該訂單。

AI 代理會使用此描述來決定何時觸發請求。

AI 代理可能需要的資訊（可選）

在呼叫 API 之前，於此區段定義所需的輸入。

這些是 AI 必須收集的結構化變數。只有在所有必要輸入可用後才會觸發該請求。

若某個值為：

已在對話中提及 → AI 會使用該值。
缺少 → AI 會向聯絡人詢問。

此處建立的變數可於 API 設定中使用。聯絡人變數（例如 $contact.email）會自動可用，無需額外新增。

欄位設定

欄位	註解
名稱	在 API 請求中使用的變數識別符。 - 每個動作唯一 - 僅限字母、數字與底線 - 區分大小寫 - 最多 30 個字元使用方式：$agent.variable_name 範例：$agent.order_id
格式	定義預期的資料類型： - 文字（預設） - 數字 - 布林值 - 日期選擇正確的格式以減少歧義並提升可靠性。
說明	說明該值代表何意，並協助 AI 清楚地詢問該值。範例：確認郵件中的 8 位數訂單編號。
陣列（可選）	啟用此選項以收集多個值而非單一值。每個項目皆遵循所選格式。若預期下列情況，請使用此選項： - 多個產品 ID - 多個追蹤編號 • 多項選擇

API 設定

定義 AI 代理應如何呼叫您的 API。

您可以設定：

方法
URL
查詢參數
標頭
JSON 主體（適用於 POST、PUT、PATCH）

引用變數

您可以在 URL、參數、標頭或主體中使用 $ 插入變數。

有兩種類型：

聯絡人變數 — 現有的聯絡人欄位
- $contact.email
AI 代理變數 — 在 AI 代理可能需要的資訊 中定義的欄位
- $agent.order_id

當請求執行時，變數會被替換為實際值。若缺少必要的 AI 代理變數，AI 將在觸發 API 呼叫前詢問該值。

AI 處理 API 回應的方式

範例主體：

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

AI 代理會自動解析 API 的 JSON 回應並產生自然回覆。

範例 API 回應：

{
  "status": "shipped",
  "eta": "2025-12-12"
}

AI 回覆：「好消息！您的訂單已出貨，預計將於 2025 年 12 月 12 日抵達。」

測試

您可以在發布前於 測試 AI 代理 面板測試您的 HTTP 請求動作。

如何測試

開始一個符合您動作條件的測試對話。
當意圖被偵測且必要輸入可用時，AI 代理會執行 HTTP 請求。
執行事件會顯示在測試面板中：
1. {AI Agent name} 已執行 {Action name}
2. 2xx 回應顯示為成功
3. 其他所有狀態碼顯示為失敗
點擊該事件以查看：
1. 回應分頁（預設）— 完整的 API 回應主體
2. 請求分頁 — 完整的 cURL 請求有效負載
3. 供除錯使用的複製選項
在收到 API 回應後，AI 代理會根據回傳的資料產生回覆。

重要說明

執行事件僅顯示於 測試 AI 代理面板。不會顯示在收件匣或聯絡人活動中。
若缺少必要輸入，AI 代理會在觸發請求前詢問這些資訊。

最佳實踐

在動作描述上要精確。模糊的指示會導致模糊的觸發條件。
清楚定義必要輸入。若 AI 必須詢問某項資訊，請讓之明顯易懂。
在說明中處理錯誤情況。
發布前務必先測試。
避免重複已由工作流程處理的邏輯，除非刻意如此設計。

限制

每個 AI 代理最多 10 個 HTTP 請求動作。
每個動作上限：
- 20 個資料輸入欄位
- 50 個參數
- 50 個標頭
AI 代理會根據您撰寫的描述決定何時呼叫 API。寫得不佳的指示可能導致意外觸發。
API 回應會自動處理。無法手動對應回應欄位 — AI 會依 JSON 內容進行語境化解讀。
HTTP 請求執行事件僅顯示於測試 AI 代理面板，不會出現在聯絡人活動中。
語音 AI 代理可以觸發發出 HTTP 請求的動作。不過，回傳的 API 回應不會回傳給語音 AI 代理以產生回覆，意即語音對話無法根據 API 結果做動態回應。

常見問題與疑難排解

我可以觸發多個 API 端點嗎？

是的。每個 AI 代理最多可配置 10 個獨立的 HTTP 請求動作。

我可以將聯絡人資料傳入 API 嗎？

是的。在 URL、標頭、參數或主體中使用 $contact.field_name。

若缺少必要資料會發生什麼情況？

AI 代理會在觸發請求前向聯絡人詢問缺少的資訊。

AI 會等待 API 回應嗎？

是的。 AI 代理會等待回應、解析它，並根據回傳資料自然回覆。

AI 代理操作：發出 HTTP 請求