Skip to main content
POST
Test Chat

Authorizations

Authorization
string
header
required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Thinnest-Workspace
string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace. Refused with 404 (Workspace not found.) when the id is unknown, is not one of your customers, or is not an org_… id; 410 when that customer was deleted (restore it with POST /customers/{id}/restore until it is erased); 403 when the key belongs to one customer workspace (it cannot act as another); 400 when your workspace is not a developer workspace. /customers/* and GET /customers/usage are your own workspace's and refuse the header with 400: call them without it.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Path Parameters

id
string
required

The agent's id (ag_…), as List Agents returns it. Another workspace's agent is the same 404 as one that never existed.

Body

application/json
message
string
required

What the customer says. Trimmed; up to 4,000 characters.

Required string length: 1 - 4000
session
string

The session a previous test chat answered with, to continue that conversation. Leave it out to start a new one.

Pattern: ^vr_[0-9a-f]{32}$
mode
enum<string>
default:chat

chat talks to the agent as a website visitor. call runs the turn with the agent's call prompt: its call rules (or the built-in ones), the speaking rules, the model its calls use (the Voice page's, or your own key's) and, on your own Gemini key, the thinking level a call uses, with no cards or buttons. It shows the words a caller will be given, not the audio, and not the call's own tools (transferring, hanging up). Needs calling set up on the agent (409 otherwise).

Available options:
chat,
call

Response

The agent's reply and the tools it used.

session
string
required

Send this back as session to continue the conversation.

Example:

"vr_4f1c09e2b7a84d55a1e0c3b2d9f86a71"

mode
enum<string>
required

The mode the turn ran in.

Available options:
chat,
call
reply
string
required

What the agent said.

tools
object[]
required

Every tool it used, in order.

error
string

Present when the reply failed part-way; reply holds what came before.