操作与故障排除

在 Onboard and configure 中配置交接和跟进行为，并在 Test and evaluate 中进行验证。在运行期间，代理、人工支持工作流和后端自动化不得假设它们同时控制同一个线程。

检查对话轮次

使用对话轮次来调查单个 WhatsApp 用户的延迟、错误以及 LLM 和工具调用的顺序。 API 参考： GET Get Conversation Turns

curl --get \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/conversationTurns" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --data-urlencode "user_phone_number=14155550123" \
  --data-urlencode "start_timestamp_ms=1788134400000" \
  --data-urlencode "end_timestamp_ms=1788220800000" \
  --data-urlencode "limit=50"

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 Control Thread

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/threadControl" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "release",
    "to": "+14155550123",
    "metadata": "Escalated to order support"
  }'

释放控制权会停止代理在该线程中响应。当控制权稍后返回给代理时，对话上下文可能会丢失。当前的 REST 表面没有公开报告当前线程所有者的端点，因此您的集成必须跟踪请求的转换及其结果。

提交和跟踪业务事件

仅在代理控制客户线程时提交事件。 API 参考： POST Submit Agent Event · GET Get Agent Event Status

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/events" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+14155550123",
    "event": {
      "type": "order_status_changed",
      "description": "The customer order moved to shipped.",
      "payload": "{\"order_id\":\"ORD-1001\",\"status\":\"shipped\"}"
    }
  }'

字段	限制	含义
`to`	E.164	消费者 WhatsApp 电话号码。
`event.type`	256 个字符	稳定的事件类型。
`event.description`	1,024 个字符	事件的通俗含义。
`event.payload`	4,096 个字符	序列化为字符串的不透明 JSON。

保留响应中的 agent_event_id，并轮询 GET Get Agent Event Status 以获取处理状态、时间戳、error_message 或 skipped_reason。成功提交仅确认事件已被接受进行异步处理；它不保证面向客户的响应。跳过的事件可能意味着代理不再控制该线程。

检查连接器执行日志

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

安全处理失败的请求

YCloud 保留相关的上游 HTTP 状态并返回安全的错误包络，而不是暴露原始上游响应或凭据。

字段	含义
`status`	HTTP 状态码。
`code`	YCloud 错误代码。
`message`	面向开发者的摘要。
`target`	相关的请求目标（如果可用）。
`docUrl`	相关的 YCloud 文档 URL（如果可用）。
`requestId`	用于支持和日志关联的 YCloud 标识符。
`metaBusinessAgentApiError.title`	上游错误标题（如果安全且可用）。
`metaBusinessAgentApiError.detail`	可操作的上游详细信息。
`metaBusinessAgentApiError.type`	上游错误类别或 URI。
`metaBusinessAgentApiError.status`	上游状态。
`metaBusinessAgentApiError.requestId`	上游请求标识符。

当上游服务未返回可用的错误时，YCloud 可能会返回 MBA_UPSTREAM_UNAVAILABLE。

症状	检查内容
`401`	验证 YCloud API 密钥和租户访问权限。不要发送 Meta 访问令牌。
`403`	验证所属企业的的产品访问权限和条款接受情况。
`404`	验证电话号码 ID 和租户的活动公共 API 代理绑定。
测试未返回响应	检查推出、受众、允许列表、资格和 `no_response_reason`。
网站保持待处理状态	抓取是异步的；稍后再次检索网站资源。
连接器调用失败	检查日志、凭据、证书状态和参数绑定。

对于 429、500 和 502，使用有界指数退避重试读取。在重试创建、更新、删除、事件、测试、工具运行、凭据或多部分请求之前，确定原始写入是否已生效。在升级重复故障时，记录请求 ID 和经过清理的请求形状。

规划抢先体验限制

以下行为属于限制，而非 YCloud REST 契约的保证：

某些资格验证失败会显示为 500，而不是稳定的不符合资格响应。
代理测试可能取决于发布和受众设置。
在转交人工客服并返回后，对话上下文可能会丢失。
PDF 或 CSV 表格可能无法被可靠地解析。
代理可能无法可靠地向消费者发送文件或图像。
MCP 连接器不可用；请使用 HTTP 连接器和工具。
在产品处于抢先体验阶段时，计费和商业行为可能会发生变化。

在停用电话号码时删除代理

仅当应从该 WhatsApp 商业电话号码中移除代理时，才发送 DELETE Delete Agent。成功的请求将返回 HTTP 200，并且在上游响应提供时可包含 deleted_agent_id。删除代理与禁用发布不同。当您需要可逆的暂停时，请使用 rollout.enabled=false。

开始使用

指南

接口

Webhooks

操作与故障排除

检查对话轮次

控制客户线程

提交和跟踪业务事件

检查连接器执行日志

安全处理失败的请求

规划抢先体验限制

在停用电话号码时删除代理

​检查对话轮次

​控制客户线程

​提交和跟踪业务事件

​检查连接器执行日志

​安全处理失败的请求

​规划抢先体验限制

​在停用电话号码时删除代理

检查对话轮次

控制客户线程

提交和跟踪业务事件

检查连接器执行日志

安全处理失败的请求

规划抢先体验限制

在停用电话号码时删除代理