Skip to main content

Embed and Deploy the Widget

This is the canonical production installation guide. It covers the standard browser embed. It does not describe a self-hosted widget service.

Prerequisites​

  • A configured assistant and its assistantId and token.
  • Permission to read the assistant's installation details.
  • Control of the target website and its Content Security Policy.
  • The production and staging hostnames added to Allowed domains.
  • A privacy decision for consent and conversation logging.

Treat the token as an embed credential: keep it out of source maps, support screenshots, analytics events, and server logs that do not require it.

Install the standard embed​

Place this once in the host page:

<div id="chatbot-root"></div>
<script>
  window.ChatbotConfig = {
    token: "YOUR_EMBED_TOKEN",
    assistantId: "YOUR_ASSISTANT_ID"
  };
</script>
<script async src="https://cdn.solhelps.com/bootstrap.js"></script>

The bootstrap waits for the DOM, authenticates token and assistantId, caches authenticated settings in browser storage for up to one hour, loads https://cdn.solhelps.com/sol-chat.umd.js, then calls:

window.ChatbotWidget.init("chatbot-root", authenticatedSettings);

If chatbot-root is absent, the runtime creates it. Reinitialising the same target reuses its React root and updates the rendered configuration; it does not intentionally create a second root. Do not include the bootstrap twice.

Allowed domains​

When authenticated settings contain allowed domains, the runtime compares the current hostname with each configured hostname. Exact hosts and their subdomains are accepted. A rejected host logs a bounded warning and does not render the widget.

Configure separate staging and production hostnames. Do not weaken the list to solve a deployment typo; verify the browser hostname and saved settings first.

Placement and single-page applications​

The runtime supports bottom-right, bottom-left, inline, and a custom bottom/right position returned in authenticated settings. An inline widget is always part of the page and cannot be closed with the public close() command.

In an SPA, mount the bootstrap once at the application shell. Use setContext when the route or workflow changes. Runtime navigation records the bounded path and keeps the existing conversation.

Content Security Policy​

Inspect a staging Network panel and allow only the Sol Helps origins actually used for:

  • script-src for bootstrap and the UMD bundle;
  • connect-src for authentication, assistant requests, and eligible logging;
  • img-src for configured widget assets; and
  • frame-src only if your host integration actually uses a frame.

Do not copy a broad allowlist from another integration.

Widget rendering and assistant requests are distinct from conversation logging. Logging requires a non-Free plan, enableChatLogging, and visitor opt-in. Pending eligible messages may be held briefly until the visitor chooses; opting out drops them. See Feedback, Consent, and Evidence.

Production verification​

In a private window:

  1. Confirm bootstrap.js and sol-chat.umd.js return successfully.
  2. Confirm the authentication request succeeds.
  3. Confirm one widget target is mounted.
  4. Confirm the current hostname is accepted.
  5. Open the widget and submit a controlled question.
  6. Confirm the answer completes.
  7. Exercise opt-in and opt-out as required by your policy.
  8. For an eligible opted-in test, confirm the record in Captured Questions.
  9. If using context, confirm the expected snapshot appears.

Common failures and safe rollback​

  • No widget: check script loading, authentication, target ID, CSP, and the allowed hostname.
  • Two widgets: remove the duplicate bootstrap or duplicate target.
  • Old settings: wait for the one-hour cache to expire or verify in a private window after changing credentials.
  • No captured question: verify plan, logging setting, consent, filters, and assistant scope.

To disable a faulty deployment, remove the bootstrap script from the host page or call window.ChatbotWidget.destroy("chatbot-root") for the mounted runtime. Removing the script prevents future page loads; destroy() affects only the current page. Preserve the assistant and evidence while investigating.

Exact public methods and return values are in the Widget Runtime API. See Troubleshooting for symptom-led recovery.