# SDK reference

`Vatio.chat` starts or resumes a conversation and waits for a subscription
before resolving. The SDK handles reconnects, history resync, and polling
fallback. Messages include `id`, `role`, and `content`. Deduplicate history
and event delivery by `id`.

| Method | Purpose |
|---|---|
| `Vatio.config({ workspace, token })` | Fetch public agent and widget configuration |
| `Vatio.chat(options)` | Start, resume, or reopen a conversation |
| `Vatio.conversations({ workspace, token, ... })` | List this browser visitor's conversations, newest first |
| `Vatio.resumable({ workspace, ... })` | Check for a locally stored, unexpired conversation |
| `Vatio.reset({ workspace, ... })` | Forget the locally stored conversation; does not delete server history |
| `chat.send(text, { files })` | Send a message, optionally with files |
| `chat.history({ limit })` | Fetch messages |
| `chat.on(event, handler)` | Subscribe to `message`, `typing`, `status`, `error`, `feedback`, or `update` |
| `chat.feedback()` | Fetch the feedback moment on offer, or `null` |
| `chat.rate(rating, { comment })` | Answer it: `good`, `neutral`, or `bad` |
| `chat.dismissFeedback()` | Decline it |
| `chat.close()` | Disconnect the client |

## Files and voice notes

Pass `files` — `File` or `Blob` objects, up to four — to attach images (JPEG,
PNG, WebP, GIF, HEIC), PDFs, text files (plain, CSV, Markdown) or audio (M4A,
MP3, OGG, WAV, AAC, FLAC). With files, `text` may be empty:

```js
const input = document.querySelector("input[type=file]");
const { message } = await chat.send("Is this the right part?", { files: [...input.files] });
```

`send` resolves to the stored message. A voice note is transcribed in the
background: the stored message comes back as "Audio", and a few seconds later
an `update` event — `{ id, content, content_is_media_label }` — carries the
transcript for the message with that `id`; merge it in. The agent answers only
once the transcript is in. A PDF holds the reply the same way while it is read,
and what it says stays out of `content`. Messages carry `attachments` —
`{ id, filename, content_type, byte_size, kind, url }`, where `kind` is
`image`, `audio`, `video` or `file`, and `url` is absolute and loads without
the chat credential. When the visitor sent only a file, `content` is a stand-in
such as "Image" and `content_is_media_label` is `true`: draw the file instead.

To record in a browser, ask `MediaRecorder` for `audio/mp4` (or `audio/ogg`)
explicitly. Chrome defaults to WebM, which is not accepted.

## Visitor feedback

Vatio offers a feedback moment at most once per conversation, when a request
looks resolved and the visitor closed the topic — see
[the widget guide](https://vatio.ai/docs/channels/widget#visitor-feedback). The `feedback` event
delivers it, including one offered before the page connected:

```js
chat.on("feedback", (feedback) => {
  // { agentName, messageId, question, rating, submittedAt, dismissed }, or null
  if (feedback && !feedback.rating && !feedback.dismissed) {
    showRating(feedback.question ?? `How did ${feedback.agentName} do?`);
  }
  else hideRating();
});

await chat.rate("neutral", { comment: "Took a while" });
```

`question` is how the agent asks, written for that conversation; it is `null`
when there is none, so keep your own wording as the fallback.

The event fires again with `null` when the visitor writes without answering,
because the moment has passed. `comment` takes up to 2,000 characters and is
meant for `neutral` and `bad`. `rate` rejects with `feedback_unavailable` once
the moment is gone.

## Options

`Vatio.chat` accepts `workspace` and `token`, plus optional `baseUrl`, `fresh`,
`scope`, `visitorToken`, `replyStyle`, and `conversation`. `fresh: true` starts
a new chat. `conversation` reopens an entry returned by `Vatio.conversations`.

Use a distinct `scope` when preview and live UIs share an origin. Pass the
same `scope` and `visitorToken` to `chat`, `conversations`, `resumable`, and
`reset`. Storage is separated by the complete visitor token, so issuing a new
token also changes its local conversation scope. It does not merge contacts
across devices.

## Storage

The SDK stores the current conversation per tab and a visitor reference in
local storage. Chat credentials last 12 hours. Treat visitor references and
chat credentials as private: the reference can retrieve that visitor's
anonymous conversations and fresh chat credentials, so store the reference
where the signed-in user cannot read another's, and never derive it from a
public or predictable user ID. Issue a new reference when the signed-in user
changes.

A conversation the visitor had signed in is listed only when the request also
carries their signed token. `Vatio.conversations` sends the `visitorToken` you
pass it in the `Vatio-Visitor-Token` header (SDK 3.5.1 and later; iOS 0.4.1,
Android 0.2.1). Without it, the list holds only what the visitor said
anonymously, so a reference copied out of a browser does not open a signed-in
customer's history.