Skip to main content
POST
Start a test conversation
Esto es Playground por API. Tú escribes como el lead y el agente responde igual que en Playground. Úsalo para correr muchas conversaciones de prueba con guion antes de poner un agente en vivo, desde tus propios scripts o desde tu propio asistente de IA con el MCP de Nexor. Cada llamada crea una conversación de prueba nueva. Para seguir hablando en ella, envía el siguiente mensaje con el 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, como workflow_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_refused con la causa en reason, como lead_in_support, human_takeover o ai_not_enabled. Reenviar el mismo mensaje da la misma respuesta. Una falla real devuelve turn_failed.

Qué envías

Qué recibes

Límites

  • 30 turnos por minuto por API key. Si te pasas, recibes rate_limited y un header Retry-After.
  • Un turno que tarda más de 90 segundos devuelve turn_failed con motivo timeout. 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

X-API-Key
string
header
requerido

API key for authentication. Keys are prefixed with nxr_live_.

Cuerpo

application/json
workflow_id
string<uuid>
requerido

Task ID (workflow in the API). It must belong to your account.

message
string
requerido

What the simulated lead writes.

Required string length: 1 - 4000
channel
enum<string>
predeterminado:whatsapp

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

Opciones disponibles:
whatsapp,
webchat,
sms,
imessage,
unsupervised-whatsapp,
email,
instagram,
messenger
metadata
object

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.

conversation_id
string<uuid>
requerido

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.

lead_id
string<uuid>
requerido

Same value as conversation_id.

workflow_id
string<uuid>
requerido

Task ID (workflow in the API) the conversation runs on.

channel
enum<string>
requerido

Simulated channel the conversation runs on. The agent writes as it would on that channel; nothing is sent.

Opciones disponibles:
whatsapp,
webchat,
sms,
imessage,
unsupervised-whatsapp,
email,
instagram,
messenger
reply
string | null
requerido

The agent's text for this turn, bubbles joined by a blank line. null when the agent stayed silent on purpose.

messages
object[]
requerido

Every message the agent sent in this turn, in order, as the lead would receive them.

tool_calls
object[]
requerido

Tools the agent called in this turn, in order. API keys and tokens in the arguments are masked.

status
string | null
requerido

Key of the lead's stage in the task after this turn.

no_reply_reason
string

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

Última modificación el 9 de octubre de 2026