公開潛在客戶 API：管理潛在客戶標籤和 AI 處理
本文適用於使用 ABC Sales AI 公開 API，從外部系統管理潛在客戶的客戶和整合夥伴。
當你的 CRM、表單工具、工作流程工具或自建應用需要在 ABC Sales AI 中建立潛在客戶後繼續更新該潛在客戶時，可以參考本文。
你可以做什麼
公開潛在客戶 API 支援這些潛在客戶管理操作：
- 在支援的潛在客戶 API 路由中，直接使用建立潛在客戶時回傳的潛在客戶 ID
- 從單一潛在客戶移除標籤
- 為單一潛在客戶開啟或關閉 AI 處理
完整 API 導覽、身分驗證方式和 Swagger 文件，請先查看公開 API 總覽。
使用回傳的潛在客戶 ID
透過 POST /v1/webhooks/leads 建立潛在客戶時，回應會包含 data.id。
你可以把這個值作為 {leadID} 用在以下支援的路由中：
GET /v1/leads/{leadID}/conversationsPOST /v1/leads/{leadID}/conversations/replyDELETE /v1/leads/{leadID}/tagsPUT /v1/leads/{leadID}/ai-handling
如果需要明確指定 ID 類型，可以加入以下其中一個查詢參數：
?id_type=lead_id?id_type=external_id
例如，當 customer-123 是你的外部潛在客戶 ID 時，可以使用 GET /v1/leads/customer-123/conversations?id_type=external_id。
建立潛在客戶後的重要說明
建立潛在客戶是非同步處理的。這表示 POST /v1/webhooks/leads 可能會在該潛在客戶完全可用於其他潛在客戶 API 路由之前就回傳。
如果你在建立潛在客戶後立刻呼叫潛在客戶 API 路由並收到 404，請先重試，不要馬上判斷該潛在客戶不存在。
建議的重試時間：
- 1 秒
- 2 秒
- 4 秒
- 8 秒
從潛在客戶移除標籤
使用 DELETE /v1/leads/{leadID}/tags 從一個潛在客戶移除一個或多個標籤。
請求內容：{"tags":["VIP","Follow Up"]}
回應範例：{"data":{"lead_id":123,"external_id":"customer-123","removed":["VIP"],"not_attached":["Follow Up"],"tags":["Interested"]},"meta":null}
removed 表示該標籤原本已附加在潛在客戶上，並已被移除。
not_attached 表示該標籤沒有附加在潛在客戶上，或該標籤不存在於該公司。
重複傳送同一個請求是安全的。如果標籤已經不存在，它會出現在 not_attached 中。
開啟或關閉 AI 處理
使用 PUT /v1/leads/{leadID}/ai-handling 控制 AI 員工是否可以回覆某一個潛在客戶。
請求內容：{"handled_by_ai":false}
回應範例：{"data":{"lead_id":123,"external_id":"customer-123","handled_by_ai":false},"meta":null}
將 handled_by_ai 設為 false，即可停止 AI 回覆該潛在客戶。
將 handled_by_ai 設為 true，即可允許 AI 再次回覆該潛在客戶。
潛在客戶 ID 不明確
外部 ID 不一定唯一。
如果 API 無法安全判斷你指的是哪一個潛在客戶，它會回傳 409 Conflict，並帶有 error_code: lead_ambiguous。
發生這種情況時，不會更新任何潛在客戶。
為了避免不明確的情況，當你的系統知道傳入的是哪一種 ID 時，請使用 ?id_type=lead_id 或 ?id_type=external_id。
頻率限制
移除標籤和更新 AI 處理共用一個更新頻率限制：每家公司和每個用戶端 IP 位址每 10 分鐘 600 次請求。
如果收到 429，請降低整合呼叫頻率，並稍後重試。
常見錯誤
400：ID 類型無效、請求內容無效、缺少必填欄位，或標籤列表無效401：API 金鑰缺失或無效404：找不到潛在客戶，或非同步建立後潛在客戶尚未可用409：潛在客戶識別不明確429：超過頻率限制500：內部錯誤
Webhook 循環提醒
移除標籤或變更 AI 處理可能會觸發潛在客戶更新事件。
如果你的系統監聽潛在客戶更新，並在收到更新後再次呼叫同一個 API，請確保你的整合具備冪等性，避免形成循環。