Skip to content
Vroxy docs

Installing the widget

The script tag

Section titled “The script tag”

Copy the snippet from your workspace’s Embed page (there’s a “Copy snippet” button) and paste it into every page you want the widget on. Either the <head> or just above </body> works.

<script async
  src="https://vroxy.ai/widget.js?tenant=YOUR_PUBLIC_KEY"></script>

That’s the whole install — no styling to configure, no framework integration, no server-side changes. The launcher bubble appears in the bottom-right corner within about half a second.

The ?tenant= query parameter is required. It’s the only thing that tells Vroxy which workspace the widget belongs to; the returned script has your public key baked into it. Older snippets also carried a data-tenant attribute on the <script> tag — nothing reads it any more, and it’s harmless if you still have one, but new installs don’t need it.

Where to get your public key

Section titled “Where to get your public key”

Workspace sidebar → Embed. The key is a 24-character string and it is not a secret — it’s visible in the page source of every site you install the widget on. All it identifies is which workspace a conversation belongs to. (The API key and the identity-verification secret on that same page are secrets. Don’t put those in a page.)

The Embed page is also where you read your identity-verification secret, manage the origin allowlist, and regenerate your API key. Note what “Regenerate” does: it revokes every outstanding server-to-server token for the workspace and issues one fresh one, so any integration using an old token breaks until you update it.

Restricting which pages can boot the widget

Section titled “Restricting which pages can boot the widget”

By default any page holding your public key can boot the widget. That’s a reasonable posture for most sites: the widget can’t read your data, and bot usage is capped by rate limits.

To hard-restrict it, fill in the Origin allowlist on the Embed page — one origin per line. When the list is non-empty, Vroxy refuses to open a widget session from any other origin (the widget’s boot request gets a 403).

https://acme.com
https://app.acme.com
http://localhost:3000

Details that bite people:

  • Entries are exact scheme://host[:port] strings. Wildcards are not supported. https://acme.com and https://www.acme.com are two different entries; so are http:// and https://.
  • The default port for the scheme is normalized away, so https://acme.com and https://acme.com:443 are the same entry.
  • An empty list means “allow any origin”.
  • Maximum 32 entries. Blank rows are dropped and duplicates collapsed when you save.
  • Testing locally? Add your dev origin (e.g. http://localhost:8080) while you test, and remove it afterwards.

The Rails gem

Section titled “The Rails gem”

If your site is a Rails app, the gem does the install and the visitor identification for you.

# Gemfile
gem "vroxy"
Terminal window
bundle install
bin/rails generate vroxy:install

Then set your public key:

Terminal window
VROXY_API_KEY=your_public_key

The gem’s Rack middleware appends the loader script to every text/html response, right before </body>, plus a second inline script that calls vroxy("identify", …) with the current user’s email, name, id, and role. Conversations therefore arrive already identified — see Identifying your users.

Configuration lives in config/initializers/vroxy.rb:

Setting What it does
api_key Your public key. Defaults to ENV["VROXY_API_KEY"].
endpoint Base URL of the Vroxy deployment. Defaults to ENV["VROXY_ENDPOINT"], else https://vroxy.ai.
enabled Master kill switch. Defaults to on whenever api_key is present.
auto_inject Middleware injection, on by default. Turn it off and place <%= vroxy_snippet %> yourself.
identify ->(controller) { … } custom identity resolver. Return nil to stay anonymous for that request.
identity_secret Signs the identity claims. Defaults to ENV["VROXY_IDENTITY_SECRET"].
admin_roles Roles that count as admin for tool access. Defaults to %w[admin owner].
csp_nonce ->(controller) { controller.content_security_policy_nonce } if you run a strict CSP.
exclude_paths Strings or Regexps that never get the snippet — health checks, internal dashboards.
report_errors Ships your app’s exceptions to your workspace’s Errors page. On automatically in production when an api_key is set.

Verifying the install

Section titled “Verifying the install”

Load a page that has the snippet and look for the chat bubble in the bottom-right corner. If it isn’t there, open devtools:

  • /widget.js returned 404 with a body of // vroxy: unknown tenant '…' — the ?tenant= value doesn’t match any workspace. Copy the snippet again from the Embed page.
  • /widget/boot returned 403 with Origin not allowed — your origin allowlist is blocking this page. Add the page’s origin, or clear the list.
  • No request for /widget.js at all, and a Content-Security-Policy violation in the console — your site’s CSP is blocking the script. You need script-src to allow the Vroxy host, and connect-src to allow both its https:// and wss:// origins for the live connection.

Removing the widget

Section titled “Removing the widget”

Delete the <script> tag (or set the gem’s enabled to false). Existing conversations stay in your workspace; the visitor localStorage keys left behind on your site are inert.