Helpin
Dark mode
Connect the chat widget

Connect the chat widget

The chat widget loads from your installation, so customers talk to your server directly. This page covers what's specific to self-hosting: public URLs, allowed origins, Content Security Policy, and verified identities.

1. Set the widget URLs

The widget uses two public URLs from .env. helpin install --mode server sets them for you.

PUBLIC_WIDGET_URL=https://app.example.com
PUBLIC_SDK_URL=https://app.example.com/sdk/lib.js

These are server settings. The generated install snippet picks them up automatically, with no rebuild needed. If you use a separate widget hostname, route only /widget/* and /sdk/* to the dashboard port.

2. Allow your website origins

Go to Settings → Chat widget and add every site that embeds the widget, one per line:

https://www.example.com
https://app.example.com
http://localhost:3000

Use scheme, host, and port only: no paths, trailing slashes, or wildcards. Add preview, staging, and local development origins explicitly.

An empty list blocks everyone, including existing sessions. Origin checks apply to every widget request and WebSocket connection.

3. Install the snippet

Copy the snippet from Settings → Chat widget after saving your origins, and paste it before </body> on your site. It points at your installation's URLs and sends no analytics to Helpin.

For framework integrations, events, and the JavaScript API, see the Widget SDK developer guide.

4. Update your Content Security Policy

If your site sends a CSP header, allow your Helpin hosts:

script-src  'self' https://app.example.com;
connect-src 'self' https://app.example.com wss://app.example.com https://files.example.com;
img-src     'self' https://files.example.com data:;

Serve every Helpin endpoint over HTTPS. Browsers block widget requests from an HTTPS site to an HTTP server.

5. Verify from a real site

  1. Open your website from a browser, not the dashboard host.

  2. Send a message, reply from the Helpin inbox, and confirm the reply appears live.

  3. Attach an image in both directions.

  4. Reload the page and confirm the conversation reconnects.

  5. From a site that isn't on your list, confirm the widget is refused with 403.

Identify logged-in users

New Community installations treat identities sent from the browser as unverified claims. They're useful context, but matching an email never grants access to that person's conversations.

When your users are logged in, turn on Require server-signed identities so Helpin can trust who they are:

  1. Integrate identity signing on your backend. The signature is an HMAC-SHA256 over the visitor's identity with a short expiry.

  2. Rotate and copy the signing secret, and store it only in your backend's secret manager, never in the browser.

  3. Turn on Require server-signed identities in Settings → Chat widget.

Anonymous chat keeps working. Identities with missing, expired, or invalid signatures are rejected. Signing code and the exact payload format are in the Widget SDK developer guide.

Troubleshooting

Problem

Check

Widget doesn't appear

Browser console: loader blocked by CSP, mixed content, or a wrong PUBLIC_SDK_URL

Requests return 403

The exact origin, including port, is in the allowed list

Messages only show after a refresh

Your reverse proxy forwards WebSocket Upgrade and Connection headers and doesn't buffer

Attachments fail

PUBLIC_STORAGE_URL is public, uses HTTPS, and is allowed in connect-src and img-src

Was this article helpful?