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

# Operar y solucionar problemas

> Controle los hilos de conversación, procese eventos, inspeccione registros, maneje fallas y retire un Meta Business Agent de manera segura.

Configure el comportamiento de transferencia y seguimiento en [Onboard and configure](/es/documentation/meta-business-agent/onboard-and-configure) y valídelo en [Test and evaluate](/es/documentation/meta-business-agent/test-and-evaluate). Durante la operación, el agente, el flujo de trabajo de soporte humano y la automatización del backend no deben asumir que controlan el mismo hilo al mismo tiempo.

## Inspeccionar turnos de conversación

Utilice los turnos de conversación para investigar la latencia, los errores y la secuencia de llamadas a LLM y herramientas para un usuario de WhatsApp.

**Referencia de la 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` debe contener solo el código de país y dígitos. No incluya un `+` inicial, espacios ni separadores. Los límites de marca de tiempo son milisegundos de época Unix inclusivos. No combine `before` y `after`.

Cada turno requiere `conversation_id`, `turn_id` y `steps`. `message_id` es opcional y la respuesta no contiene `session_id`. Cada paso tiene el tipo `LLM_CALL` o `TOOL_CALL` y puede tener el estado `SUCCESS`, `ERROR` o `TIMEOUT`.

Continúe la paginación mientras `paging.next` esté presente, incluso cuando la matriz `data` actual esté vacía o contenga menos elementos que `limit`.

## Controlar un hilo de cliente

Utilice `pass`, `release` o `take` con el punto de conexión de control de hilos general. Proporcione `to` como un número de teléfono E.164 o ID de WhatsApp. `metadata` es opcional y admite hasta 2000 caracteres.

**Referencia de la 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"
  }'
```

Liberar el control impide que el agente responda en ese hilo. El contexto de la conversación se puede perder cuando el control vuelve más tarde al agente. La superficie REST actual no expone un punto de conexión que informe sobre el propietario actual del hilo, por lo que su integración debe realizar un seguimiento de las transiciones solicitadas y sus resultados.

## Enviar y realizar un seguimiento de eventos comerciales

Envíe un evento solo mientras el agente controle el hilo del cliente.

**Referencia de la 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\"}"
    }
  }'
```

| Campo | Límite | Significado |
| - | - | - |
| `to` | E.164 | Número de teléfono de WhatsApp del consumidor. |
| `event.type` | 256 caracteres | Tipo de evento estable. |
| `event.description` | 1024 caracteres | Significado en lenguaje sencillo del evento. |
| `event.payload` | 4096 caracteres | JSON opaco serializado como una cadena. |

Conserve `agent_event_id` de la respuesta y consulte [GET Get Agent Event Status](/api-reference/meta-business-agents/get-agent-event-status) para conocer el estado de procesamiento, las marcas de tiempo, `error_message` o `skipped_reason`. Un envío exitoso solo confirma que el evento fue aceptado para procesamiento asincrónico; no garantiza una respuesta de cara al cliente. Un evento omitido puede significar que el agente ya no controla el hilo.

## Inspeccionar registros de ejecución del conector

Consulte [GET List Connector Logs](/api-reference/meta-business-agents/list-connector-logs) cuando una llamada a una herramienta falle o se vuelva lenta. La respuesta combina entradas de registro con recuentos, tasa de éxito y estadísticas de latencia.

Las consultas de registro del conector admiten un intervalo de tiempo limitado. El límite ascendente actual es de siete días. Verifique la ubicación de las credenciales, el estado del certificado, los enlaces de solicitud y las definiciones de herramientas antes de volver a intentar una operación fallida.

## Manejar solicitudes fallidas de manera segura

YCloud conserva el estado HTTP ascendente relevante y devuelve un sobre de error seguro en lugar de exponer respuestas o credenciales ascendentes sin procesar.

| Campo | Significado |
| - | - |
| `status` | Código de estado HTTP. |
| `code` | Código de error de YCloud. |
| `message` | Resumen de cara al desarrollador. |
| `target` | Destino de solicitud relacionado, cuando esté disponible. |
| `docUrl` | URL de documentación de YCloud relacionada, cuando esté disponible. |
| `requestId` | Identificador de YCloud utilizado para soporte y correlación de registros. |
| `metaBusinessAgentApiError.title` | Título de error ascendente, cuando sea seguro y esté disponible. |
| `metaBusinessAgentApiError.detail` | Detalle ascendente procesable. |
| `metaBusinessAgentApiError.type` | Categoría de error ascendente o URI. |
| `metaBusinessAgentApiError.status` | Estado ascendente. |
| `metaBusinessAgentApiError.requestId` | Identificador de solicitud ascendente. |

Cuando el servicio ascendente no devuelve un error utilizable, YCloud puede devolver `MBA_UPSTREAM_UNAVAILABLE`.

| Síntoma | Qué comprobar |
| - | - |
| `401` | Verifique la clave de API de YCloud y el acceso del inquilino. No envíe un token de acceso de Meta. |
| `403` | Verifique el acceso al producto y la aceptación de los términos para la empresa propietaria. |
| `404` | Verifique el ID del número de teléfono y el enlace del agente de la API pública activa del inquilino. |
| La prueba no devuelve respuesta | Verifique el lanzamiento, la audiencia, la lista de permitidos, la elegibilidad y `no_response_reason`. |
| El sitio web permanece pendiente | El rastreo es asincrónico; recupere el recurso del sitio web nuevamente más tarde. |
| Falla la llamada al conector | Verifique los registros, las credenciales, el estado del certificado y los enlaces de parámetros. |

Vuelva a intentar las lecturas con un retroceso exponencial limitado para `429`, `500` y `502`. Antes de volver a intentar una solicitud de creación, actualización, eliminación, evento, prueba, ejecución de herramienta, credencial o multiparte, determine si la escritura original ya surtió efecto. Registre tanto los ID de solicitud como una forma de solicitud saneada al escalar una falla repetida.

## Planificar las limitaciones de acceso anticipado

Los siguientes comportamientos son limitaciones, no garantías del contrato REST de YCloud:

* Algunos fallos de elegibilidad aparecen como `500` en lugar de una respuesta de inelegibilidad estable.
* Las pruebas del agente pueden depender de la configuración de implementación y de la audiencia.
* El contexto de la conversación puede perderse después de la transferencia a un humano y el retorno.
* Es posible que las tablas PDF o CSV no se interpreten de manera confiable.
* Es posible que el agente no envíe archivos o imágenes a los consumidores de manera confiable.
* Los conectores MCP no están disponibles; utilice conectores y herramientas HTTP.
* La facturación y el comportamiento comercial pueden cambiar mientras el producto esté en acceso anticipado.

## Eliminar el agente al retirar el número de teléfono

Envíe [DELETE Delete Agent](/api-reference/meta-business-agents/delete-agent) solo cuando el agente deba eliminarse de ese número de teléfono de WhatsApp Business. Una solicitud exitosa devuelve HTTP `200` y puede incluir `deleted_agent_id` cuando la respuesta ascendente lo proporciona.

Eliminar el agente es diferente a deshabilitar la implementación. Utilice `rollout.enabled=false` cuando necesite una pausa reversible.


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