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.
  • Every attribute the element accepts, 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 and a public key (`pk_…`); never put a secret key in client markup.

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

Attributes

tenantstring
Your tenant slug.
thememeadow | marigold | coral | deep
Widget theme. Default meadow; unknown values fall back to meadow. See Notes & caveats for the vocabulary divergence.
channelstring
Channel id to attribute conversations to.
greetingstring
First message shown on open.
api-urlurl
Override the API base URL.
api-keypk_…
Public key for the widget. 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("deep");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 (meadow | marigold | coral | deep).
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: the supported themes are the four v3 names — `meadow` (default), `marigold`, `coral`, and `deep`. An unknown value falls back to `meadow`. Older snippets and the placeholder `light | dark | auto` values are mapped to a legacy vocabulary internally; prefer the v3 names shown above.
  • 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. Auth via X-API-Key.
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?