Iniciar una conversación de prueba
Inicia por API una conversación simulada con una de tus tareas y recibe la primera respuesta del agente, con las herramientas que usó. No se envía nada por un canal real.
conversation_id que recibes.
Antes de empezar
- Usa una API key secreta. La clave publicable del widget se rechaza con 403
publishable_key_out_of_scope. - Las keys de MCP necesitan
workflows:write. Las keys REST de acceso completo no necesitan nada más. - Siempre es simulado. No se envía nada por WhatsApp, SMS, correo ni ningún otro canal, aunque el lead de prueba tenga teléfono o correo.
- Funciona con tareas pausadas o inactivas, igual que Playground.
- Tus herramientas HTTP se ejecutan de verdad, con el header
X-Nexor-Playground: true. Revisa ese header en tu endpoint si una prueba no debe crear pedidos ni reservas reales. - Los errores devuelven un código estable en
error, comoworkflow_not_found. Asocia el código a tus propios textos. - Si el agente rechaza el turno a propósito, por ejemplo porque el lead se derivó a una persona o la IA está apagada para él, recibes 409
turn_refusedcon la causa enreason, comolead_in_support,human_takeoveroai_not_enabled. Reenviar el mismo mensaje da la misma respuesta. Una falla real devuelveturn_failed.
Qué envías
Qué recibes
Límites
- 30 turnos por minuto por API key. Si te pasas, recibes
rate_limitedy un headerRetry-After. - Un turno que tarda más de 90 segundos devuelve
turn_failedcon motivotimeout. Puede terminar igual; lista tus conversaciones de prueba para leerlo. - Las API keys y tokens dentro de los argumentos de las herramientas aparecen enmascarados.
Autorizaciones
API key for authentication. Keys are prefixed with nxr_live_.
Cuerpo
Task ID (workflow in the API). It must belong to your account.
What the simulated lead writes.
1 - 4000Optional. Simulated channel for the whole conversation; later messages reuse it. Delivery is always simulated. Voice is not available. Any other value returns 400 invalid_input.
whatsapp, webchat, sms, imessage, unsupervised-whatsapp, email, instagram, messenger Optional test lead data, at most 8000 bytes. first_name, last_name, email, and phone (strings) set the lead's contact fields; every other key is saved as lead metadata the agent can read. The phone is never contacted.
Respuesta
The conversation was created and the agent answered.
ID of the test conversation. It is the test lead's ID, so it also works with GET /test-conversations and GET /leads/{id}/turns.
Same value as conversation_id.
Task ID (workflow in the API) the conversation runs on.
Simulated channel the conversation runs on. The agent writes as it would on that channel; nothing is sent.
whatsapp, webchat, sms, imessage, unsupervised-whatsapp, email, instagram, messenger The agent's text for this turn, bubbles joined by a blank line. null when the agent stayed silent on purpose.
Every message the agent sent in this turn, in order, as the lead would receive them.
Tools the agent called in this turn, in order. API keys and tokens in the arguments are masked.
Key of the lead's stage in the task after this turn.
Only when the agent stayed silent on purpose, for example terminal_tool (it reacted with an emoji) or status_paused (the stage pauses the agent).