Skip to main content
POST
Start a test conversation
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

What you get back

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.

Authorizations

X-API-Key
string
header
required

API key for authentication. Keys are prefixed with nxr_live_.

Body

application/json
workflow_id
string<uuid>
required

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

message
string
required

What the simulated lead writes.

Required string length: 1 - 4000
channel
enum<string>
default: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.

Available options:
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.

Response

The conversation was created and the agent answered.

conversation_id
string<uuid>
required

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>
required

Same value as conversation_id.

workflow_id
string<uuid>
required

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

channel
enum<string>
required

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

Available options:
whatsapp,
webchat,
sms,
imessage,
unsupervised-whatsapp,
email,
instagram,
messenger
reply
string | null
required

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

messages
object[]
required

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

tool_calls
object[]
required

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

status
string | null
required

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

Last modified on October 9, 2026