Skip to content
Vroxy docs

Bot settings

Settings — at /w/<workspace-id>/<slug>/settings — is where you control how the widget looks and how the bot talks. Installation (snippet, public key, origin allowlist) lives on the Embed page instead; the two are deliberately separate.

Viewing needs settings.read; changing anything needs settings.write, which admin and owner hold. Branding changes take effect on the next widget load — a visitor who already has the panel open keeps whatever they booted with until they reload.

Branding

Section titled “Branding”

Header title — the name in the widget’s header. Up to 80 characters. Leave it blank and the widget uses your workspace name.

Brand color — a hex color (#rgb or #rrggbb, with or without the #). It drives the widget’s accent color. Blank falls back to a neutral near-black (#111827).

First-message greeting — the opening bubble a visitor sees before they’ve said anything. Up to 500 characters. Blank falls back to “How can we help?”.

Bot model

Section titled “Bot model”

The bot runs on a model of your choosing, named by its OpenRouter slug. The field is free text with a dropdown of suggestions, so you can pick from the catalog or type any model OpenRouter supports.

The catalog offers:

Slug Notes
anthropic/claude-haiku-4.5 Fast and cheap — the default
anthropic/claude-sonnet-4.6 Balanced
anthropic/claude-opus-4.7 Best quality, pricier
openai/gpt-4o-mini Fast and cheap
openai/gpt-4o
openai/gpt-4.1
openai/gpt-4.1-mini
google/gemini-2.5-flash
google/gemini-2.5-pro
meta-llama/llama-3.3-70b-instruct
mistralai/mistral-large

Leave the field blank and the bot uses anthropic/claude-haiku-4.5.

A note on picking one: the bot’s job is mostly reading your published docs and paraphrasing them, which the small fast models do well. Reach for a larger model when replies are getting the reasoning wrong, not when they’re getting the facts wrong — wrong facts are a knowledge base problem, and a bigger model will state them just as confidently.

If the deployment has no model provider configured at all, the bot doesn’t error at the visitor: it posts a short “one of our operators will reply here shortly” message and your manual reply from the Chats page becomes the real answer.

Bot system prompt

Section titled “Bot system prompt”

The Bot system prompt field replaces the built-in description of who the bot is. Leave it blank and the bot is told it’s the support assistant for your workspace, to be concise, factual and friendly, and to offer a hand-off to a human when it doesn’t know.

Fill it in and your text is used verbatim in that slot instead. Use it for persona, tone, and standing policy — “always answer in Spanish”, “never quote prices, direct pricing questions to sales”, “we’re a B2B product, assume the visitor is a developer”.

What an override does not replace, because these are applied on top of it either way:

  • The conversation protocol — keep replies short, don’t mention tool names or internal machinery, don’t promise follow-ups you can’t deliver, hand off plainly when a person is needed.
  • Instructions for searching and reading your knowledge base, and the list of your published doc titles.
  • Context about the visitor’s verified access level and which of your custom tools are out of their reach.
  • The page the visitor started on and the page they’re on now.
  • The bot’s memory notes about your workspace and about this visitor.

So an override customizes what the bot knows and how it sounds; how it conducts a conversation stays consistent. If you want the bot to stop citing docs or stop offering hand-offs, an override won’t do it — those live in layers you can’t switch off.

Two practical warnings:

  • Don’t put product facts in the system prompt. Facts belong in published docs, which the bot can search, quote and cite. Facts in the prompt are invisible to your team, unversioned, and can’t be corrected by anyone without settings.write.
  • The system prompt is not a security boundary. Tool access is gated on a verified visitor level (see Custom bot tools), not on instructions. “Never tell anyone X” in a prompt is a request, not a control.
Section titled “Glossary and admin deep links”

The glossary is a small JSON array on the Settings page, up to 24 entries:

[
  {
    "term": "product",
    "aliases": ["property", "listing"],
    "admin_url_template": "https://yoursite.com/admin/products/{id}"
  }
]

Each entry has a term (2–40 characters, letters, digits, spaces, hyphens and underscores), an optional list of aliases, and an optional admin_url_template that must be an http(s) URL.

What it actually does today:

  • Admin deep links. An entry whose term is user and which has an admin_url_template puts an “open in your admin ↗” link on each visitor’s page and on the header of each chat transcript. The {id} placeholder is filled with the visitor’s external_id — the id your own identify call supplied — and URL-encoded. That’s the fastest path from “this person is complaining” to “here’s their record in my system”.
  • Server-to-server access. GET and PUT /api/v1/glossary read and write the list with a workspace API token (writing needs tenant:write). PUT merges by term by default — an incoming term updates the matching entry and unknown terms are appended, so a repeated sync doesn’t clobber entries you added by hand. Pass replace: true to swap the whole list.
  • Syncing from Rails. The Ruby gem adds bin/rails vroxy:sync_glossary, which mines your activerecord.models translations for nouns whose display label differs from the model name and pushes them here.

An entry with no admin_url_template produces no link. If the visitor has no external_id, there’s nothing to substitute and no link is shown.

One thing the glossary does not do today, despite what it sounds like: the aliases list is stored but is not fed to the widget’s bot, so it won’t teach the bot that “listing” means “product”. To make the bot understand a synonym, put the synonym in a published doc.

Visitor tracking

Section titled “Visitor tracking”

Controls when a visitor first appears in your Visitors list.

  • Only when they interact (on_interaction) — the default. Nothing is recorded until the visitor opens the chat panel, sends a message, or your site identifies them. Someone who loads a page and never touches the widget leaves no row.
  • On every page load (all_pages) — every page load that boots the widget records the visitor and refreshes their last-seen time.

Either way, a returning visitor with an existing token is recognized on boot and keeps their transcript — the setting only decides whether a new row gets created for someone who hasn’t done anything yet.

Pick on_interaction unless you specifically want traffic-level presence data. all_pages writes a row for every anonymous browser that ever loads a page with the widget on it, which is a lot of rows that never turn into a conversation.

Chat auto-close

Section titled “Chat auto-close”

Also on this page: open chats with no new messages for a set period are closed automatically. The choices are never, 8 hours, 24 hours, 3 days (the default), or 1 week. A visitor can always start a new conversation; a closed one stays closed and can’t be replied to.