Widget Configuration

The hosted Convor widget combines site-level configuration saved in the dashboard with optional browser initialization overrides. Most installations should save stable settings in the dashboard and keep the production embed unchanged.

Settings → Widget

Open Settings → Widget for the visitor-facing configuration that is currently exposed in the dashboard:

• localized widget title, greeting, and related content;
• primary color, launcher position, and theme;
• bot avatar and launcher icon;
• the pre-chat form, including built-in name, email, and phone fields plus active custom fields;
• Convor branding where your plan allows it.

Saving these settings updates the hosted configuration. You do not need to replace the script tag afterward.

Installation and security

Open Settings → Widget → Installation and security for installation-specific controls.

This area contains:

• Identity verification: enable, rotate, or disable the per-site secret used to verify signed-in visitors;
• Embed Code: copy the production script for the currently selected site.

Every production embed contains a public widget key beginning with convor_wpk_:

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

The public widget key is expected to be visible in browser code. It identifies the site configuration but cannot authorize customer REST API operations.

Site domains

Allowed production hostnames are managed with the site, not on the Widget settings page. Open Sites, select the site, and manage its domains there.

Add every hostname that should be allowed to use the site configuration, including required subdomains. Add local development hostnames only while testing your own application.

If the widget works on one hostname but not another, check the selected site's domain list before changing the embed.

Proactive triggers

Behavior-based proactive messages are managed under Triggers, not Settings → Widget. Triggers can react to supported visitor behavior such as time on page, a visited page, exit intent, first visit, or a proactive-invitation condition set.

See Triggers for the current dashboard workflow.

Browser-only overrides

Some supported widget options are intentionally available through Convor.init() or script data attributes even though the current dashboard does not expose a matching control. Examples include autoOpen, departments, and soundEnabled.

Use those only when the page needs an explicit override. See Widget Customization for the supported initialization options.

Application-specific data

Do not put signed-in customer details or application state in HTML attributes. Use window.Convor for data that depends on the current browser session:

await Convor.ready();

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

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

Production endpoint ownership

The hosted widget.js build owns the production API, iframe, and realtime endpoints. These addresses are not customer widget configuration and should not be copied into the embed or application environment variables.

For browser methods and events, see the Widget JavaScript API.