Sessions and channels

On the web

Render the token onto the widget's script tag. Signed-out visitors simply get no token, and the agent answers with its public tools.

<script src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="acme"
        data-token="vatpub_..."
        <%= "data-visitor-token=\"#{visitor_jwt}\"".html_safe if current_user %>></script>

To sign someone in without reloading the page:

window.VatioWidget.identify(newToken);   // null to sign out

Signing in mid-conversation

A visitor asks something, the agent tells them to sign in, they do, and they come back. The conversation survives. Whether they signed in through identify() or by navigating away and reloading the page with a token, the chat they already had is carried over and now has a name on it — so the agent can answer the question that prompted the login without them retyping it.

Before	After	What happens
anonymous	signed in	Same conversation, now identified
user A	user A, newer token	Same conversation, token refreshed
user A	user B	New conversation
signed in	signed out	New conversation

The last two are the shared-laptop case: a conversation that belonged to one sub is never handed to another, so signing in as someone else looks exactly like arriving for the first time. Vatio enforces that server-side — the page cannot opt out of it.

Refreshing is also how a web session stays alive: render a fresh token on each page load and a long-running conversation keeps working past the first token's exp.

Channels with no session

On WhatsApp and Instagram there is no page to render a token onto, so Vatio asks your backend for one. Add mint::

auth:
  public_key: identity.pub
  mint:
    url: $env.API_URL/api/vatio/identity
    headers:
      X-Api-Key: $env.API_KEY

Vatio posts the channel's evidence and expects a token back:

POST /api/vatio/identity
Content-Type: application/json

{ "channel": "whatsapp", "phone_number": "+56912345678" }

{ "token": "<the same kind of JWT you sign for the web>" }

Return any non-2xx for a number you do not recognize — the visitor stays anonymous and the agent keeps its public tools. Set the secrets it needs with vatio secrets set API_KEY ....

Mint runs once per conversation, and again only if the token expires. On WhatsApp that means a long conversation refreshes itself.

Mint is never used on the web, even when you declare it. On the web the token is the evidence: the page had a session and said so in a signature. A web visitor with no valid token is signed out, and stays that way until the page calls identify() with a fresh one.