> ## 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.

# Operate and troubleshoot

> Control conversation threads, process events, inspect logs, handle failures, and retire a Meta Business Agent safely.

Configure handoff and follow-up behavior in [Onboard and configure](/en/documentation/meta-business-agent/onboard-and-configure) and validate it in [Test and evaluate](/en/documentation/meta-business-agent/test-and-evaluate). During operation, the agent, human-support workflow, and backend automation must not assume that they control the same thread at the same time.

## Inspect conversation turns

Use conversation turns to investigate latency, errors, and the sequence of LLM and tool calls for one WhatsApp user.

**API reference:** [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` must contain the country code and digits only. Do not include a leading `+`, spaces, or separators. Timestamp boundaries are inclusive Unix epoch milliseconds. Do not combine `before` and `after`.

Each turn requires `conversation_id`, `turn_id`, and `steps`. `message_id` is optional, and the response does not contain `session_id`. Each step has type `LLM_CALL` or `TOOL_CALL` and can have status `SUCCESS`, `ERROR`, or `TIMEOUT`.

Continue pagination while `paging.next` is present, even when the current `data` array is empty or contains fewer items than `limit`.

## Control a customer thread

Use `pass`, `release`, or `take` with the general thread-control endpoint. Provide `to` as an E.164 phone number or WhatsApp ID. `metadata` is optional and supports up to 2,000 characters.

**API reference:** [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"
  }'
```

Releasing control stops the agent from responding in that thread. Conversation context can be lost when control later returns to the agent. The current REST surface does not expose an endpoint that reports the current thread owner, so your integration must track requested transitions and their outcomes.

## Submit and track business events

Submit an event only while the agent controls the customer thread.

**API reference:** [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\"}"
    }
  }'
```

| Field | Limit | Meaning |
| - | - | - |
| `to` | E.164 | Consumer WhatsApp phone number. |
| `event.type` | 256 characters | Stable event type. |
| `event.description` | 1,024 characters | Plain-language meaning of the event. |
| `event.payload` | 4,096 characters | Opaque JSON serialized as a string. |

Retain `agent_event_id` from the response and poll [GET Get Agent Event Status](/api-reference/meta-business-agents/get-agent-event-status) for processing state, timestamps, `error_message`, or `skipped_reason`. A successful submission confirms only that the event was accepted for asynchronous processing; it does not guarantee a customer-facing response. A skipped event can mean that the agent no longer controls the thread.

## Inspect connector execution logs

Query [GET List Connector Logs](/api-reference/meta-business-agents/list-connector-logs) when a tool call fails or becomes slow. The response combines log entries with counts, success rate, and latency statistics.

Connector log queries support a bounded time range. The current upstream limit is seven days. Check credential placement, certificate state, request bindings, and tool definitions before retrying a failing operation.

## Handle failed requests safely

YCloud preserves the relevant upstream HTTP status and returns a safe error envelope instead of exposing raw upstream responses or credentials.

| Field | Meaning |
| - | - |
| `status` | HTTP status code. |
| `code` | YCloud error code. |
| `message` | Developer-facing summary. |
| `target` | Related request target, when available. |
| `docUrl` | Related YCloud documentation URL, when available. |
| `requestId` | YCloud identifier used for support and log correlation. |
| `metaBusinessAgentApiError.title` | Upstream error title, when safe and available. |
| `metaBusinessAgentApiError.detail` | Actionable upstream detail. |
| `metaBusinessAgentApiError.type` | Upstream error category or URI. |
| `metaBusinessAgentApiError.status` | Upstream status. |
| `metaBusinessAgentApiError.requestId` | Upstream request identifier. |

When the upstream service does not return a usable error, YCloud can return `MBA_UPSTREAM_UNAVAILABLE`.

| Symptom | What to check |
| - | - |
| `401` | Verify the YCloud API key and tenant access. Do not send a Meta access token. |
| `403` | Verify product access and terms acceptance for the owning business. |
| `404` | Verify the Phone Number ID and the tenant's active Public API agent binding. |
| Test returns no response | Check rollout, audience, allowlist, eligibility, and `no_response_reason`. |
| Website remains pending | Crawling is asynchronous; retrieve the website resource again later. |
| Connector call fails | Check logs, credentials, certificate state, and parameter bindings. |

Retry reads with bounded exponential backoff for `429`, `500`, and `502`. Before retrying a create, update, delete, event, test, tool-run, credential, or multipart request, determine whether the original write already took effect. Record both request IDs and a sanitized request shape when escalating a repeated failure.

## Plan for early-access limitations

The following behaviors are limitations, not guarantees of the YCloud REST contract:

* Some eligibility failures appear as `500` instead of a stable ineligibility response.
* Agent testing can depend on rollout and audience settings.
* Conversation context may be lost after human handoff and return.
* PDF or CSV tables may not be interpreted reliably.
* The agent may not reliably send files or images to consumers.
* MCP connectors are not available; use HTTP connectors and tools.
* Billing and commercial behavior may change while the product is in early access.

## Delete the agent when retiring the phone number

Send [DELETE Delete Agent](/api-reference/meta-business-agents/delete-agent) only when the agent should be removed from that WhatsApp Business phone number. A successful request returns HTTP `200` and can include `deleted_agent_id` when the upstream response supplies it.

Deleting the agent is different from disabling rollout. Use `rollout.enabled=false` when you need a reversible pause.


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