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

#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:

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. The feedback event delivers it, including one offered before the page connected:

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.