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.
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: trueheader. Check that header in your endpoint if a test must not create real orders or bookings. - Errors return a stable code in
error, such asworkflow_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_refusedwith the cause inreason, such aslead_in_support,human_takeover, orai_not_enabled. Sending the same message again gets the same answer. A real failure returnsturn_failedinstead.
What you send
What you get back
Limits
- 30 turns per minute per API key. Over that you get
rate_limitedand aRetry-Afterheader. - A turn that takes more than 90 seconds returns
turn_failedwith reasontimeout. It may still finish; list your test conversations to read it. - API keys and tokens inside tool arguments are masked.
Authorizations
API key for authentication. Keys are prefixed with nxr_live_.
Body
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.
Response
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).