返回整合

公開潛在客戶 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 輪詢


  1. 首次同步時不傳 updated_since,處理全部分頁,並按 id 新增或更新外部系統的記錄。
  2. 全部分頁成功處理後,原樣儲存最後一筆已處理記錄的 updated_at,包括微秒。
  3. 下次輪詢時,將該 RFC 3339 時間戳記作為 updated_since,只回傳嚴格晚於該時間的更新。請對值進行 URL 編碼,尤其是時區偏移中的 +。
  4. 再次處理全部分頁後才推進已儲存的時間戳記。如果沒有回傳記錄,保留原時間戳記。游標僅用於完成本輪分頁,後續輪詢使用時間戳記。

ℹ️
最近 30 秒內寫入的記錄會延遲到之後的請求回傳。新增或移除標籤、指派或取消指派負責人都會更新潛在客戶的 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}/conversations
  • POST /v1/leads/{leadID}/conversations/reply
  • DELETE /v1/leads/{leadID}/tags
  • PUT /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 再次回覆該潛在客戶。


ℹ️
為單一潛在客戶開啟 AI 處理,不會覆蓋公司層級或渠道層級的 AI 設定。只有公司層級 AI、渠道層級 AI 和潛在客戶層級 AI 處理全部開啟時,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,請確保你的整合具備冪等性,避免形成循環。


還需要幫助?

我們的支援團隊隨時為你提供協助。

聯絡支援