跳转到主要内容
在接入与配置中配置转接及跟进行为,并在测试与评估中进行验证。在运行期间,Agent、人工支持工作流和后端自动化不能假定它们同时控制同一个会话。

检查对话轮次

使用对话轮次来调查单个 WhatsApp 用户的延迟、错误以及 LLM 与工具调用的执行顺序。 API 参考: GET 获取对话轮次
user_phone_number必须仅包含国家代码和数字。不要包含前导 +、空格或分隔符。时间戳边界为闭区间的 Unix 时间戳(毫秒)。请勿同时组合使用 before 和 after。 每个轮次都需要 conversation_id、turn_id 和 steps。message_id 为选填项,且响应中不包含 session_id。每个步骤的类型为 LLM_CALL 或 TOOL_CALL,其状态可以为 SUCCESS、ERROR 或 TIMEOUT。 只要存在 paging.next,即使当前的 data 数组为空或包含的项少于 limit,也请继续分页。

控制客户会话

在通用会话控制端点中使用 pass、release 或 take。将 to 作为 E.164 电话号码或 WhatsApp ID 提供。metadata 为选填项,最多支持 2,000 个字符。 API 参考: POST 控制会话
释放控制权会使 Agent 停止在该会话中回复。后续控制权返回给 Agent 时,对话上下文可能会丢失。当前的 REST 接口未公开可报告当前会话所有者的端点,因此您的集成系统必须自行跟踪请求的流转状态及其结果。

提交并跟踪业务事件

仅当 Agent 控制客户会话时才提交事件。 API 参考: POST 提交 Agent 事件 · GET 获取 Agent 事件状态
状态响应在可用时会包含 conversation_id,这是与对话轮次返回的相同的不透明标识符。请使用它来关联记录,而不是作为事件 ID 或消息送达凭据。该字段可能不存在。 保留响应中的 agent_event_id 并轮询 GET 获取 Agent 事件状态 以获取处理状态、时间戳、error_message 或 skipped_reason。成功提交仅确认该事件已被接受以进行异步处理;并不保证向客户发送响应。跳过的事件可能意味着 Agent 不再控制该会话。

检查连接器执行日志

当工具调用失败或变慢时,查询 GET 获取连接器日志列表。响应将日志条目与计数、成功率和延迟统计信息结合在一起。 连接器日志查询支持有界的时间范围。当前的上游限制为七天。在重试失败的操作之前,请检查凭据位置、证书状态、请求绑定和工具定义。

安全处理失败的请求

YCloud 会保留相关的上游 HTTP 状态,并返回安全的错误封套,而不是暴露原始的上游响应或凭据。 当上游服务未返回可用的错误时,YCloud 可能会返回 MBA_UPSTREAM_UNAVAILABLE。 针对 429、500 和 502,可使用有界的指数退避机制重试读取操作。在重试创建、更新、删除、事件、测试、工具运行、凭据或多部分(multipart)请求之前,请先确定原始写入是否已生效。上报重复出现的故障时,请同时记录请求 ID 和脱敏后的请求结构。

针对抢先体验阶段的限制做好规划

以下行为属于已知限制,并非 YCloud REST 契约的保证:
  • 某些资格验证失败会显示为 500,而非稳定的不符合资格响应。
  • 代理测试可能会受推送范围和受众设置的影响。
  • 在人工转接及交回后,对话上下文可能会丢失。
  • PDF 或 CSV 表格的解析可能不够可靠。
  • 代理向消费者发送文件或图片的功能可能不够稳定。
  • MCP 连接器不可用;请使用 HTTP 连接器和工具。
  • 在产品处于抢先体验阶段期间,计费和商业化行为可能会发生变动。

停用电话号码时删除代理

仅当需要从该 WhatsApp Business 电话号码中移除代理时,才发送 DELETE Delete Agent。成功的请求会返回 HTTP 200,并且在上游响应提供相应内容时,可包含 deleted_agent_id。 删除代理与停用推送范围不同。当需要可逆的暂停时,请使用 rollout.enabled=false。