Operate and troubleshoot

Configure handoff and follow-up behavior in Onboard and configure and validate it in 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

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

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 · 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\"}"
    }
  }'

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

Getting Started

Guides

Endpoints

Webhooks

Operate and troubleshoot

Inspect conversation turns

Control a customer thread

Submit and track business events

Inspect connector execution logs

Handle failed requests safely

Plan for early-access limitations

Delete the agent when retiring the phone number

​Inspect conversation turns

​Control a customer thread

​Submit and track business events

​Inspect connector execution logs

​Handle failed requests safely

​Plan for early-access limitations

​Delete the agent when retiring the phone number

Inspect conversation turns

Control a customer thread

Submit and track business events

Inspect connector execution logs

Handle failed requests safely

Plan for early-access limitations

Delete the agent when retiring the phone number