Install the widget

The chat widget is a single dependency-free widget.js, served by the Vicero web app at /widget.js. It renders inside a Shadow DOM, so it neither inherits your site's CSS nor leaks its own into your page.

Get the agent's public key

Open the agent → Channels tab.
Set the appearance — colour, position, launcher text, whether it opens by default, whether to show the Vicero footer. Changes autosave.
Copy the embed snippet. The data-agent value is the agent's public key.

The public key is safe to expose in client-side HTML. It grants access to that one published agent's public chat and nothing else.

Add it to your site

Paste this just before </body>:

<script
  src="https://YOUR_WEB_HOST/widget.js"
  data-agent="pk_your_agent_public_key"
  data-api="https://YOUR_API_HOST"
  defer
></script>

Attribute	Required	Meaning
`src`	yes	Where `widget.js` is hosted — your Vicero web host
`data-agent`	yes	The agent's public key, from the Channels tab
`data-api`	recommended	The API base URL. Defaults to the page host on port 8000, which is almost never right in production — set it

Control it from JavaScript

Once loaded, window.Vicero is available:

Vicero.open();                             // open the panel
Vicero.close();                            // close it
Vicero.toggle();                           // toggle
Vicero.sendMessage("Hello from my site");  // send a message as the visitor
Vicero.setUser({ name: "Jane", email: "jane@acme.com" });
Vicero.on("message", (m) => console.log("reply:", m));

Opening it from your own button:

<button onclick="Vicero.toggle()">Chat with us</button>

setUser is worth calling if you already know who the visitor is — it attaches identity to the conversation, so the contact record is not an anonymous session and your operators can see who they are talking to.

Theming

Appearance comes from the agent's Channels configuration rather than from the snippet: accent colour, launcher side, launcher label, open-by-default, and the "Powered by Vicero" footer. Change it in the dashboard and the widget picks it up on next load.

Keeping theming server-side means you can restyle the widget across every site that embeds it without anyone editing HTML.

Human handoff

If the agent has handoff enabled, a visitor can ask to talk to a person. The conversation appears in the dashboard Inbox; when an operator takes over and replies, the reply is pushed to the open widget in real time over a WebSocket. Handing back resumes the agent.

The visitor sees no page reload and no "ticket number" — it stays one conversation.

Cross-origin

The public endpoints are CORS-enabled. In development the API accepts any http://localhost:<port> origin. In production, set CORS_ORIGINS to include every site that embeds the widget — or serve the widget from the same origin as the API and avoid CORS entirely.

Try it locally

apps/web/public/widget-demo.html is a plain page containing nothing but the widget script. Serve the web app, open it, and drop in a real public key.