#Chats
A chat here is you, the developer holding the token, on channel cli. It is
not a way to impersonate a customer: channel, from, as, session_id,
reply_style, email and phone_number are all refused, and environment is
the only field create and reset accept.
| Method | Path | Body / query |
|---|---|---|
| POST | /chats | { "environment": "preview" } → chat_id |
| GET | /chats/:id | Any chat in the workspace, on any channel: its channel, environment, deployment_id and identity state |
| POST | /chats/:id/reset | { "environment": "preview" } → a new chat_id |
| POST | /chats/:id/messages | { "content": "Hello" } → 202 with user_message_id |
| GET | /chats/:id/messages | after and limit |
environment is required on create and reset, and it is the one field in
this API with no default. Everywhere else an omitted environment falls back to
something harmless; here the fallback would be live, and a request missing one
word would be a real conversation with your published agent — billed, visible in
the inbox, and running your tools against live secrets. Send preview to
talk to a preview deployment, or live when you mean it. A name that is not an
environment is 422, not a guess.
Replies are asynchronous: post a message, then poll GET /chats/:id/messages
with after set to the last id you have seen.
Both read endpoints always return the developer view, because the token already
is the developer view — deleted messages, tool calls with their results,
attachments, channel delivery receipts, and an identity block saying whether
the workspace recognized the visitor and why not. There is no view parameter to
choose; print as much of the payload as your caller needs.
This API only sees the conversations it started. To read what real customers said on the widget, WhatsApp or Instagram, use the inbox.