公開潛在客戶 API:列出潛在客戶、管理標籤與 AI 處理
本文適用於使用 ABC Sales AI 公開 API,從外部系統管理潛在客戶的客戶和整合夥伴。
當你的 CRM、表單工具、工作流程工具或自建應用需要在 ABC Sales AI 中建立潛在客戶後繼續更新該潛在客戶時,可以參考本文。
列出與輪詢潛在客戶
使用 Bearer API 金鑰呼叫 GET /v1/leads,讀取您公司的潛在客戶和自訂欄位。例如:GET /v1/leads?limit=100&tags=VIP。回應的 data 包含潛在客戶,meta 包含分頁資訊。結果按 updated_at 升序排列,時間相同則按 id 排序。
篩選與分頁
search:部分符合姓名、電話或電子郵件;source:按潛在客戶來源篩選。tags:符合任一所列標籤,可重複傳入參數或用逗號分隔。automation_id:來自GET /v1/automations的數字自動化 ID,不是 slug。date_from和date_to:按建立日期篩選,格式為YYYY-MM-DD,包含起迄日期。timezone使用 IANA 時區,如Asia/Kuala_Lumpur,預設使用公司時區,其次為 UTC。ai_enabled和from_ad:布林值篩選。messaging_channel:渠道類型;messaging_channel_connection_ids:渠道連接 ID,可重複傳入或用逗號分隔。limit:每頁 1 至 100 筆,預設 50 筆。cursor:傳入上一頁的meta.next_cursor,直到meta.has_more為 false。游標包含初始篩選條件,後續分頁只需傳入游標。
使用 updated_since 輪詢
- 首次同步時不傳
updated_since,處理全部分頁,並按id新增或更新外部系統的記錄。 - 全部分頁成功處理後,原樣儲存最後一筆已處理記錄的
updated_at,包括微秒。 - 下次輪詢時,將該 RFC 3339 時間戳記作為
updated_since,只回傳嚴格晚於該時間的更新。請對值進行 URL 編碼,尤其是時區偏移中的+。 - 再次處理全部分頁後才推進已儲存的時間戳記。如果沒有回傳記錄,保留原時間戳記。游標僅用於完成本輪分頁,後續輪詢使用時間戳記。
updated_at,因此這些變更可以出現在之後的 updated_since 輪詢結果中。輪詢不回傳刪除記錄,也不能可靠追蹤對話活動;此介面不是完整的變更日誌。檔案類型的自訂欄位包含附件資料及附件 API 的 download_url。使用同一 API 金鑰下載,不要永久儲存重新導向後的短期連結。
列表查詢有獨立的頻率限制:每家公司每 10 分鐘 300 次請求。遇到 429 時請降低頻率並稍後重試。完整參考請查看開發者指南和互動式 API 參考。
你可以做什麼
公開潛在客戶 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,請確保你的整合具備冪等性,避免形成循環。