> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnexor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

| Campo | Detalle |
| - | - |
| `workflow_id` | La tarea (`workflow` en la API) que quieres probar. Debe ser de tu cuenta. |
| `message` | Lo que escribe el lead simulado. Hasta 4000 caracteres. |
| `channel` | Opcional. El canal que quieres simular: `whatsapp` (por defecto), `webchat`, `sms`, `imessage`, `unsupervised-whatsapp`, `email`, `instagram` o `messenger`. El agente escribe como lo haría en ese canal. Los mensajes siguientes lo reutilizan. Voz no está disponible. |
| `metadata` | Opcional. `first_name`, `last_name`, `email` y `phone` definen los datos de contacto del lead de prueba. Cualquier otra clave se guarda como dato del lead que el agente puede leer. Hasta 8000 bytes. |

## Qué recibes

| Campo | Detalle |
| - | - |
| `channel` | El canal simulado de la conversación. |
| `conversation_id` | La conversación de prueba. Es el ID del lead de prueba, así que también sirve para listar pruebas y leer los turnos del agente. |
| `reply` | El texto del agente en este turno. `null` cuando el agente no respondió a propósito. |
| `messages` | Cada mensaje que envió el agente, en orden, tal como lo recibiría el lead. Textos y archivos. |
| `tool_calls` | Cada herramienta que usó el agente, con sus argumentos, si funcionó y su error cuando falló. |
| `status` | La etapa del lead en la tarea después de este turno. |
| `no_reply_reason` | Solo cuando el agente no respondió a propósito, por ejemplo `status_paused`. |

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


## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.getnexor.ai/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.