Install the chat widget

Before you start

You need an account, an organization widget in SupportWhale and permission to change your website’s code. An owner or admin can change the widget settings. The website key in the snippet is public; your identity signing key is secret and must never appear in browser code.

Install the widget

1. Sign in and choose the correct organization in the sidebar.
2. Open Widget → Installation and copy your generated script. Keep its actual loader URL, website key and API address together.
3. Paste the script immediately before </body> on your website, then publish the change.
4. Open your site in a private browser window. Send a message, open the SupportWhale inbox and reply. Reload the page to check that history is retained.

Choose allowed domains

Open Widget → Allowed domains. Allowlist is the default. Add each production, staging or development hostname that needs the widget. example.com and www.example.com are different entries. *.example.com allows subdomains, but does not include the apex example.com. A non-default port must match exactly, for example localhost:5173. International domain names are normalized by the server.

Allow all domains lets any website embed this widget. Enable it only when that is intentional. It does not grant access to private conversations or team credentials. Changing an allowlist also affects reconnecting widgets; include your preview and staging origins when needed.

Widget language

The widget follows the visitor’s browser language (English, Dutch or German). Optionally add data-locale="nl" to the installation script to choose a language explicitly; en and de are also supported. After loading, window.SupportWhale.setLocale("de") changes the language without clearing an unfinished message or email address.

Plain HTML

Use the script copied from Installation. This example shows its shape; replace YOUR_WEBSITE_KEY with your own public key.

<script src="https://cdn.supportwhale.com/loader.js"
  data-website-id="YOUR_WEBSITE_KEY"
  data-api="https://api.supportwhale.com/v1" defer></script>

Nuxt

Add the same script once in your app’s useHead configuration, not in every page component. Use your generated values.

useHead({ script: [{
  src: 'https://cdn.supportwhale.com/loader.js',
  'data-website-id': 'YOUR_WEBSITE_KEY',
  'data-api': 'https://api.supportwhale.com/v1',
  defer: true
}] })

React

The simplest option is to put your generated script in the application’s HTML document before </body>. If you do not control that document, add it once from a root component effect. Keep it mounted across client-side navigation; do not add a new copy for every route.

useEffect(() => {
  if (document.getElementById('supportwhale-loader')) return;
  const script = document.createElement('script');
  script.id = 'supportwhale-loader';
  script.src = 'https://cdn.supportwhale.com/loader.js';
  script.dataset.websiteId = 'YOUR_WEBSITE_KEY';
  script.dataset.api = 'https://api.supportwhale.com/v1';
  script.defer = true;
  document.head.appendChild(script);
}, []);

Open chat from your own button

Add this button anywhere on your site, alongside the installed widget script:

<button type="button" data-supportwhale-action="open">Contact support</button>

Use close to close chat or toggle to alternate between open and closed. Buttons added during client-side navigation work automatically. Clicks while the widget bundle loads are queued; the page does not scroll or change its URL. Use a button instead of an empty href="#" link.

From JavaScript, use window.SupportWhale.open(), window.SupportWhale.close() or window.SupportWhale.toggle() after the loader has executed. Keep the script mounted once in your app. On logout or account change, call window.SupportWhale.reset() before setting the next customer's identity.

If the widget does not open

Check that the loader URL is reachable, the key belongs to the selected website and the current hostname/port is allowed. A content-security policy must allow the CDN script and API/WebSocket connections; browser extensions may block chat scripts. Avoid loading the snippet twice. The built-in preview is useful for testing the configuration, but always test the installed customer page as well.

For signed-in customer identities, create short-lived JWTs on your own server and use the identity-provider integration shown in Installation. Never send the signing secret to the browser. Contact support with the affected hostname and the visible error, without passwords or private tokens.