Sign in
Open console
Docs/Widget/Widget embed
docs · widget

Widget embed

reference

Drop the widget on any page with a script tag and a custom element.

Embed the VeriCite Widget on any page by loading one script and dropping in a `<vericite-widget>` custom element. This page is the lookup reference for the embed snippet, its attributes, the display modes, and the `window.VeriCiteWidget` JavaScript API.

Permission required — Configuring the per-assistant Widget panel (under assistants/widget) requires the setting:update permission, held by Tenant Administrator. The console shows the panel to everyone, but saving without the grant is rejected. The embed snippet itself runs client-side with a public key and needs no console permission to deploy.

What this covers

  • The verbatim embed snippet — script tag plus the `<vericite-widget>` custom element.
  • The attributes you set on the element, with type and meaning.
  • The three display modes and the default.
  • The five methods on the `window.VeriCiteWidget` runtime API.
  • Known limitations you should plan around before shipping.

Embed snippet

Paste this near the end of your page body. Use your tenant slug, the gateway base URL, and a public key (`pk_…`); never put a secret key in client markup.

index.htmlhtml
<script src="https://widget.vericite.ai/widget.umd.js"></script><vericite-widget  tenant="state-bridge"  theme="light"  api-url="https://api.vericite.ai"  api-key="pk_live_•••"  default-mode="popup"></vericite-widget>

Attributes

tenantstring
Your tenant slug. Required.
themelight | dark | auto
Widget theme. Default light; auto follows the visitor's OS setting. Retired names are coerced — see Notes & caveats.
channelstring
Channel id to route and attribute conversations to. Never shown to visitors.
display-namestring
Label under the header title. Defaults to the assistant name from your widget config, then Knowledge.
greetingstring
First message shown on open.
welcome-subtitlestring
Secondary line under the greeting. Defaults to the value in your widget config.
api-urlurl
Base URL of the api-gateway (no trailing slash). Required.
api-keypk_…
Public key for the widget. Required; always a public pk_ key, never a secret.
default-modepopup | expanded | fullscreen
Initial display mode. See the enum below.
suggested-promptsstring[]
Prompt chips shown on open.

Display modes

popupdefault
Floating launcher that opens a compact panel. Used when default-mode is omitted.
expandedmode
Larger docked panel for content-heavy conversations.
fullscreenmode
Takes the full viewport — best for dedicated help pages.

JavaScript API

Once the script loads, `window.VeriCiteWidget` exposes exactly five methods for controlling the Widget at runtime.

control the widgetjs
VeriCiteWidget.open();VeriCiteWidget.close();VeriCiteWidget.setTheme("dark");VeriCiteWidget.setMode("expanded");VeriCiteWidget.identify({ id: "u_1" }); // event-only stub
open()void
Open the Widget.
close()void
Close the Widget.
setTheme(name)void
Switch theme at runtime (light | dark | auto).
setMode(mode)void
Switch between popup / expanded / fullscreen.
identify(obj)void · stub
Emits an identity event only — see the caveat below.
identify is an event-only stub — `identify` currently emits an event only; it does not persist identity yet. Do not rely on it to associate conversations with a known user.

Notes & caveats

  • Theme vocabulary: `light` (default) | `dark` | `auto` (follows the visitor's OS setting). Legacy theme names (`meadow`/`marigold`/`coral` → `light`, `deep` → `dark`) are still accepted and coerced; any other value falls back to `light`.
  • The per-assistant Widget panel's "Copy embed snippet" button is non-functional — copy the snippet from this page instead.
  • Widget deflection and off-domain redirect settings are collected in the console but are not yet persisted or rendered by the Widget. Configuring them has no runtime effect today.
  • All five JS API methods ship in the runtime even though the admin Widget card omits `setMode` from its prose — you can call `setMode` regardless.
referenceAPI referenceThe shipped HTTP surface — chat, documents, config, webhooks. Stateful chat uses an API key plus a signed visitor credential.
featureWidgetConfigure the embeddable widget’s theme, greeting, and prompts.
featureAPI keysCreate and rotate the pk_ and sk_ keys used by the API and widget.
troubleshootingWidget won’t loadResolve script, key, and allowed-domain errors in the embed.
Was this page helpful?