Customize the widget before you publish

Widget settings are under Settings → Widget. Changes stay in the dashboard until you select Save Changes, so you can safely explore the preview first.

Set the visitor-facing details

Set the widget title, primary color, position, greeting, and light or dark theme. Keep the greeting specific: tell visitors what the team can help with and when they can expect a reply.

Check the live preview

The preview is an actual widget frame, not a static illustration. Open it, check the launcher position, and read the greeting at the same width your visitors will see. Make one small change at a time so you know which setting caused a visual difference.

Verify signed-in customer identity

Open Settings → Widget → Installation and security. Use Verified customer identity only when your application already knows who the signed-in customer is. Select Generate secret, copy the value immediately, and store it only in a server-side secret store. Convor returns the full secret only when it is generated or rotated.

The flow is:

1. The browser waits for Convor.ready() and obtains the current visitorId.
2. It sends that visitorId to an authenticated endpoint in your application.
3. Your server resolves the customer from its own session instead of trusting identity fields supplied by the browser.
4. Your server computes HMAC-SHA256 over the exact JSON property order visitorId, id, email, name, phone. Missing email, name, and phone values are empty strings.
5. The server returns the customer traits and the 64-character hexadecimal userHash. The secret never reaches browser code.
6. The browser calls Convor.identify() with the same id, email, name, and phone values that were signed.

The signature includes the current visitorId, so it cannot be replayed for another visitor session. Rotating the secret makes future requests signed with the previous secret fail verification.

The complete server and browser example is in Convor.identify(identity).

Adjust placement for your application shell

The dashboard position is the right choice for most sites. If a fixed cookie bar, mobile navigation, or another application control needs additional clearance, initialize the widget programmatically with offset:

await Convor.init({
  key: "convor_wpk_...",
  position: "bottom-right",
  offset: {
    x: 20,
    y: 64,
    mobile: {x: 12, y: 80},
  },
});

offset.x and offset.y are signed CSS-pixel additions to the normal margin from the selected corner. Positive values move the launcher, preview cloud, and desktop frame farther into the page; negative values move them toward or beyond the edge. Below 640 px, offset.mobile.x and offset.mobile.y override their corresponding base values, with omitted mobile axes inheriting the base value. The opened mobile chat remains full-screen, so mobile offsets apply to the launcher and preview cloud only.

Do not move the widget by overriding internal .convor-* CSS selectors. They are implementation details; offset is the supported positioning contract. center is not a valid widget position.

Switch language in an SPA

If your application changes language without a full page navigation, call the runtime locale API after the widget has initialized:

await Convor.setLocale("pl-PL");

This refreshes localized site content and the built-in widget interface without recreating the host launcher or frame. The current open/closed state, visibility, position, and site-scoped visitor identity are preserved. See Convor.setLocale(locale) for the complete behavior.

Copy the embed code

On the same Settings → Widget → Installation and security page, copy the snippet from Embed Code and paste it before the closing </body> tag on the pages where chat should appear. The production snippet has this shape:

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

Replace convor_wpk_... with the public widget key shown for the selected site. Keep the widget.js URL and key intact. Do not add API, iframe, or WebSocket addresses manually.

Allow the site hostname

Before testing, open Sites, select the site, and add the hostname that embeds the widget to its allowed domains. Include production subdomains separately when needed. Add localhost only while testing your own local application. A valid embed can stay invisible when its current hostname is not allowed.

Content Security Policy

For a strict host-page CSP, add these permissions to the equivalent directives in your existing policy:

script-src  https://cdn.convor.io;
connect-src https://api.convor.io https://cdn.convor.io;
frame-src   https://cdn.convor.io;
style-src   'unsafe-inline';

The host page itself fetches configuration from https://api.convor.io, loads locale assets and widget.js from https://cdn.convor.io, and frames https://cdn.convor.io. Realtime runs inside that hosted iframe, so your host page does not need wss://ws.convor.io in connect-src for the standard embed.

style-src 'unsafe-inline' is currently required because the launcher injects a style element and inline layout styles into the host page. If your policy defines style-src-elem or style-src-attr, those directives must also permit the corresponding inline styles. If you configure a custom launcher icon, add that image's origin to your existing img-src policy.

Related setup docs

• Installation covers framework-specific placement.
• Embedding the Widget explains the production embed contract and allowed domains.
• Widget JavaScript API covers signed-in customer data, SPA navigation, events, and programmatic control.

Publish checklist

1. Save the settings.
2. Add the snippet to a staging page.
3. Start one conversation as a visitor.
4. Confirm that the operator can reply from Conversations.
5. If verified identity is enabled, sign in with a staging account and confirm that its visitor profile is marked as verified.