公开潜在客户 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，请确保你的集成具备幂等性，避免形成循环。