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

# Start a test conversation

> Start a simulated conversation with one of your tasks by API and get the agent's first answer, with the tools it called. Nothing is sent on a real channel.

This is Playground by API. You write as the lead, and the agent answers exactly as it does in Playground. Use it to run many scripted test conversations before you put an agent live, from your own scripts or from your own AI assistant with the Nexor MCP.

Each call creates a new test conversation. To keep talking in it, send the next message with the `conversation_id` you get back.

## Before you start

* Use a secret API key. The widget publishable key is rejected with 403 `publishable_key_out_of_scope`.
* MCP keys need `workflows:write`. Full-access REST keys need nothing else.
* It is always simulated. Nothing is sent on WhatsApp, SMS, email, or any other channel, even if the test lead has a phone or an email.
* It works on paused or inactive tasks, like Playground.
* Your HTTP tools run for real, with the `X-Nexor-Playground: true` header. Check that header in your endpoint if a test must not create real orders or bookings.
* Errors return a stable code in `error`, such as `workflow_not_found`. Map the code to your own copy.
* If the agent refuses the turn on purpose, for example because the lead was escalated to a person or the AI is off for it, you get 409 `turn_refused` with the cause in `reason`, such as `lead_in_support`, `human_takeover`, or `ai_not_enabled`. Sending the same message again gets the same answer. A real failure returns `turn_failed` instead.

## What you send

| Field | Detail |
| - | - |
| `workflow_id` | The task (`workflow` in the API) to test. It must belong to your account. |
| `message` | What the simulated lead writes. Up to 4000 characters. |
| `channel` | Optional. The channel to simulate: `whatsapp` (default), `webchat`, `sms`, `imessage`, `unsupervised-whatsapp`, `email`, `instagram`, or `messenger`. The agent writes as it would on that channel. Later messages reuse it. Voice is not available. |
| `metadata` | Optional. `first_name`, `last_name`, `email`, and `phone` set the test lead's contact fields. Every other key is saved as lead data the agent can read. Up to 8000 bytes. |

## What you get back

| Field | Detail |
| - | - |
| `channel` | The simulated channel of the conversation. |
| `conversation_id` | The test conversation. It is the test lead's ID, so it also works to list tests and read the agent's turns. |
| `reply` | The agent's text for this turn. `null` when the agent stayed silent on purpose. |
| `messages` | Every message the agent sent, in order, as the lead would receive them. Text and files. |
| `tool_calls` | Each tool the agent called, with its arguments, whether it worked, and its error when it failed. |
| `status` | The lead's stage in the task after this turn. |
| `no_reply_reason` | Only when the agent stayed silent on purpose, for example `status_paused`. |

## Limits

* 30 turns per minute per API key. Over that you get `rate_limited` and a `Retry-After` header.
* A turn that takes more than 90 seconds returns `turn_failed` with reason `timeout`. It may still finish; list your test conversations to read it.
* API keys and tokens inside tool arguments are masked.


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