Saltar al contenido principal
Configura el comportamiento de traspaso y seguimiento en Incorporación y configuración y valídalo en Probar y evaluar. Durante el funcionamiento, el agente, el flujo 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

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 Turns
user_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

Usa pass, 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
Liberar el control impide que el agente responda en ese hilo. El contexto de la conversación puede perderse cuando el control regresa más tarde al agente. La superficie REST actual no expone un endpoint que informe del propietario actual del hilo, por lo que tu integración debe hacer un seguimiento de las transiciones solicitadas y de sus resultados.

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 500 en 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 HTTP 200 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.