Inspeccionar turnos de conversación
Usa los turnos de conversación para investigar la latencia, los errores y la secuencia de llamadas al LLM y a herramientas para un usuario de WhatsApp. Referencia de la API: GET Get Conversation Turnsuser_phone_number debe contener solo el código de país y dígitos. No incluyas un + inicial, espacios ni separadores. Los límites de marca de tiempo son milisegundos de época Unix inclusivos. No combines 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úa con la paginación mientras paging.next esté presente, incluso cuando el array data actual esté vacío o contenga menos elementos que limit.
Controlar el hilo de un cliente
Usapass, release o take con el endpoint general de control de hilos. Proporciona to como un número de teléfono E.164 o un ID de WhatsApp. metadata es opcional y admite hasta 2000 caracteres.
Referencia de la API: POST Control Thread
Enviar y rastrear eventos de negocio
Envía un evento solo mientras el agente controle el hilo del cliente. Referencia de la API: POST Submit Agent Event · GET Get Agent Event Status
Cuando está disponible, la respuesta de estado incluye
conversation_id, el mismo identificador opaco devuelto por Conversation Turns. Úsalo para correlacionar registros, no como un ID de evento ni como prueba de entrega del mensaje. El campo puede estar ausente.
Conserva agent_event_id de la respuesta y sondea GET Get Agent Event Status para obtener el estado de procesamiento, las marcas de tiempo, error_message o skipped_reason. Un envío correcto solo confirma que el evento fue aceptado para procesamiento asíncrono; no garantiza una respuesta dirigida al cliente. Un evento omitido puede significar que el agente ya no controla el hilo.
Inspeccionar registros de ejecución de conectores
Consulta GET List Connector Logs cuando una llamada a 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 registros del conector admiten un intervalo de tiempo delimitado. El límite ascendente actual es de siete días. Comprueba la ubicación de las credenciales, el estado del certificado, las vinculaciones de solicitudes y las definiciones de herramientas antes de reintentar una operación que haya fallado.Gestionar solicitudes fallidas de forma segura
YCloud conserva el estado HTTP ascendente correspondiente y devuelve una envoltura de error segura en lugar de exponer credenciales o respuestas ascendentes sin procesar.
Cuando el servicio ascendente no devuelve un error utilizable, YCloud puede devolver
MBA_UPSTREAM_UNAVAILABLE.
Reintenta las lecturas con retroceso exponencial acotado para
429, 500 y 502. Antes de reintentar una solicitud de creación, actualización, eliminación, evento, prueba, ejecución de herramienta, credencial o multiparte, determina si la escritura original ya surtió efecto. Registra ambos ID de solicitud y una estructura de solicitud saneada cuando escales un fallo repetido.
Planifica teniendo en cuenta las limitaciones del acceso anticipado
Los siguientes comportamientos son limitaciones, no garantías del contrato REST de YCloud:- Algunos fallos de elegibilidad aparecen como
500en lugar de una respuesta de no elegibilidad estable. - Las pruebas del agente pueden depender de la configuración del despliegue y de la audiencia.
- El contexto de la conversación puede perderse tras la transferencia a un agente humano y el retorno.
- Es posible que las tablas en PDF o CSV no se interpreten de forma fiable.
- El agente podría no enviar archivos o imágenes a los consumidores de forma fiable.
- Los conectores MCP no están disponibles; utiliza conectores HTTP y herramientas.
- La facturación y el comportamiento comercial pueden cambiar mientras el producto se encuentre en acceso anticipado.
Elimina el agente al retirar el número de teléfono
Envía DELETE Delete Agent solo cuando se deba eliminar el agente de ese número de teléfono de WhatsApp Business. Una solicitud correcta devuelve el código HTTP200 y puede incluir deleted_agent_id cuando la respuesta del servicio ascendente lo proporcione.
Eliminar el agente es diferente a desactivar el despliegue. Utiliza rollout.enabled=false cuando necesites una pausa reversible.
