Operar y solucionar problemas

Configure el comportamiento de transferencia y seguimiento en Onboard and configure y valídelo en 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

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

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

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

Primeros pasos

Guías

Endpoints

Webhooks

Operar y solucionar problemas

Inspeccionar turnos de conversación

Controlar un hilo de cliente

Enviar y realizar un seguimiento de eventos comerciales

Inspeccionar registros de ejecución del conector

Manejar solicitudes fallidas de manera segura

Planificar las limitaciones de acceso anticipado

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

​Inspeccionar turnos de conversación

​Controlar un hilo de cliente

​Enviar y realizar un seguimiento de eventos comerciales

​Inspeccionar registros de ejecución del conector

​Manejar solicitudes fallidas de manera segura

​Planificar las limitaciones de acceso anticipado

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

Inspeccionar turnos de conversación

Controlar un hilo de cliente

Enviar y realizar un seguimiento de eventos comerciales

Inspeccionar registros de ejecución del conector

Manejar solicitudes fallidas de manera segura

Planificar las limitaciones de acceso anticipado

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