Appearance
Concepts
Workspace and team
One server runs one workspace: your bots, provider keys, knowledge, tools, conversations and team. People sign in to the admin panel with a role:
| Role | Can |
|---|---|
owner | Everything, including the workspace itself and other owners |
admin | Bots, providers, tools, knowledge, webhooks, API tokens, team (but not owners), settings |
agent | Conversations: read, reply, take over, and leads |
viewer | Read only |
Each role can do everything the roles below it can. Programs use API tokens with scopes instead.
Provider connections
A connection is one API key for one provider (Anthropic, OpenAI, Google Gemini or ElevenLabs), added under Providers in the admin panel. The server checks the key, notes what it can be used for (text, realtime voice, speech to text, text to speech) and loads its models and voices for the dropdowns. Keys are encrypted at rest and never sent back to a browser; the admin panel only shows their last four characters.
Bots refer to connections by id, so you can replace a key in one place, or give different bots different keys. See Providers.
Bots and versions
A bot is one agent: its identity and instructions, its brain and voice, its face and look, and its rules. Each bot has a public id (pk_...) that goes in the embed code. It isn't a secret: anyone can read it in your page. What protects a bot is its list of allowed origins.
You edit a bot's draft. Publishing checks the draft (a missing model, a rejected key and other problems stop it) and freezes a copy as a numbered version. Then:
- live chats on your site switch to the new version (open chat windows reload their settings);
- conversations already under way keep the version they started with (prompt, brain, voice and tools), so a change never confuses a conversation halfway through; how the chat looks, and whether typed replies are read aloud, follow the new version;
- you can copy any old version back into the draft and publish it again.
A bot is a draft until its first publish, then live; you can pause it, which takes it off every site until you set it live again. The admin panel's preview shows the unpublished draft through a signed preview link that lasts six hours. When the draft has changed since its test conversation began, the preview starts a new one.
The full list of settings is in Configuration.
Visitors
A visitor is one browser talking to one bot. The first time someone opens the chat, the server gives the browser a random visitor token, which widget.js keeps in your site's own localStorage (or sessionStorage, or nowhere: see the storage option). Coming back with the token, they are the same visitor.
If your site has accounts, tell the chat who is signed in with identity verification. A verified visitor is tied to your user id, so their conversations follow them between devices.
Conversations
A conversation starts with the visitor's first message (or when they start voice, send the lead form or ask for a person). Text and voice turns go into the same conversation. Each one is in one of four states:
| Status | Meaning |
|---|---|
ai | The agent is answering |
handoff_pending | Someone from your team has been asked to take over |
human | A person from your team is answering; the agent stays quiet |
closed | Ended: by the agent saying goodbye, by your team, or after a quiet spell |
A visitor who comes back within the bot's behavior.persistence.resumeWindowHours (24 hours by default) continues their open conversation, with its history (or, with behavior.persistence.showHistory off, with a clean window while the conversation and the agent's memory carry on). Conversations the agent is handling close after behavior.endAfterIdleMinutes (30 minutes) without messages, once nobody has the chat open. The chat's menu also offers New conversation, which closes the current one.
Your team reads conversations in the admin panel, where they can tag, export and delete them, take one over, and reply. Programs can read them through the REST API or receive them through webhooks.
Long conversations
Models can only read so much at once. When a conversation's history grows past the bot's brain.compactAtTokens (120,000 tokens by default, roughly estimated), the server condenses its older part: the bot's brain writes a factual summary (who the visitor is, what they asked, what was decided and promised, details such as order numbers, and what is still open), and from then on the model sees that summary first, followed by the recent messages. Nothing is deleted: the visitor's window and the transcript keep every message. The summary costs one extra model call, counted in the bot's usage; if it fails, the reply goes ahead without it.
Knowledge, tools and leads
Knowledge sources, HTTP tools, MCP servers and secrets belong to the workspace; each bot picks the ones it uses. Leads (contact details a visitor leaves) belong to the bot and conversation they came from. See Knowledge base, Tools and MCP and Leads and CSAT.