# 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](https://vatio.ai/docs/channels/inbox).