Widget Customization

For a normal installation, configure the widget in Settings → Widget and use the production embed code unchanged. The only required installation value is the public widget key.

<script
  src="https://cdn.convor.io/widget.js"
  data-key="convor_wpk_..."
  async
></script>

The hosted build owns the production API, iframe, and realtime endpoints. Those addresses are not customer configuration.

Dashboard configurationCopy Anchor Link

The dashboard is the preferred place for settings that should stay consistent across the site. Settings → Widget currently covers appearance, localized visitor-facing copy, launcher position, pre-chat fields, avatars, and branding settings available to your plan. Site domains are managed under Sites, and named proactive messages are managed under Triggers.

Options such as autoOpen, departments, and soundEnabled remain supported browser initialization overrides even though the current Widget settings page does not expose matching controls.

Changes saved in the dashboard are loaded by the existing embed automatically. You do not need to replace the script tag.

Content languages are configured per site under Settings → Localization. They are independent from the Convor-owned widget interface catalogs. See Manage content languages.

Programmatic initializationCopy Anchor Link

widget.js exposes window.Convor. Most sites can wait for the automatically initialized widget with Convor.ready() and never call Convor.init() explicitly.

If your application creates the widget programmatically, key is the only required option. The runtime also accepts these visitor-facing overrides:

offset.x and offset.y are the default offsets for the selected corner. Values are CSS pixels: positive values move the widget farther inward from its anchor edge and negative values move it outward. For example, position: "bottom-right" with offset: {x: 20, y: 64} places the launcher 44 px from the right edge and 88 px from the bottom edge because the standard 24 px launcher margin is retained.

Below the widget's 640 px mobile breakpoint, offset.mobile.x and offset.mobile.y override the corresponding base axis. Each omitted mobile axis inherits its base value. The launcher and preview cloud use the mobile offsets; the opened mobile chat remains full-screen and ignores placement offsets. This keeps the responsive contract small while still letting applications clear mobile bottom navigation or cookie controls.

Use offset instead of targeting internal .convor-* elements with CSS. center is not a valid widget position; positions are always anchored to one of the four corners.

Example:

await Convor.init({
  key: "convor_wpk_...",
  position: "bottom-left",
  offset: {
    x: 20,
    y: 64,
    mobile: {x: 12, y: 80},
  },
  primaryColor: "#2563eb",
  content: {
    greeting: "How can we help?",
  },
});

Do not pass service endpoints to Convor.init(). Production builds use the endpoints shipped with widget.js.

Application data belongs in the browser APICopy Anchor Link

Use the dedicated browser methods for values that describe the current visitor or page instead of encoding them in the script tag.

await Convor.ready();

await Convor.setUser({
  name: currentUser.name,
  email: currentUser.email,
  attributes: {
    plan: currentUser.plan,
  },
});

await Convor.setPage(window.location.href);
await Convor.setLocale(currentLocale);

For a cryptographically verified signed-in identity, follow Convor.identify(identity). The identity secret always stays on your server.

See Widget JavaScript API for methods and events exposed by window.Convor.