> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 操作与故障排除

> 控制对话线程、处理事件、检查日志、处理故障，并安全地停用 Meta Business Agent。

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

## 检查对话轮次

使用对话轮次来调查单个 WhatsApp 用户的延迟、错误以及 LLM 和工具调用的顺序。

**API 参考：** [GET Get Conversation Turns](/api-reference/meta-business-agents/get-conversation-turns)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/control-thread)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/submit-agent-event) · [GET Get Agent Event Status](/api-reference/meta-business-agents/get-agent-event-status)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/get-agent-event-status) 以获取处理状态、时间戳、`error_message` 或 `skipped_reason`。成功提交仅确认事件已被接受进行异步处理；它不保证面向客户的响应。跳过的事件可能意味着代理不再控制该线程。

## 检查连接器执行日志

当工具调用失败或变慢时，查询 [GET List Connector Logs](/api-reference/meta-business-agents/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](/api-reference/meta-business-agents/delete-agent)。成功的请求将返回 HTTP `200`，并且在上游响应提供时可包含 `deleted_agent_id`。

删除代理与禁用发布不同。当您需要可逆的暂停时，请使用 `rollout.enabled=false`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.