Skip to main content

Embed and Deployment Guide

Use this guide when taking an assistant live on your site.

What you need before embedding​

  1. At least one assistant is created.
  2. Knowledge is uploaded and tested in Try Assistant.
  3. You have your assistant embed values:
  • assistantId
  • token

Required embed structure​

Minimum required embed format:

<div id="chatbot-root"></div>
<script>
  window.ChatbotConfig = { token: "YOUR_TOKEN", assistantId: "YOUR_ASSISTANT_ID" };
  (function (d) {
    var s = d.createElement("script");
    s.src = "https://cdn.solhelps.com/bootstrap.js";
    s.async = true;
    d.head.appendChild(s);
  })(document);
</script>

Required parts:

  • container element with id chatbot-root
  • window.ChatbotConfig with correct token and assistantId
  • loader script from https://cdn.solhelps.com/bootstrap.js

Environment requirements​

Embedding can work in:

  • static HTML sites
  • React/Next.js apps
  • tag managers (for example GTM), if script injection is allowed

If your site has strict script policies, review CSP requirements before rollout.

CSP and security checklist​

If your site enforces Content Security Policy, ensure required Sol Helps origins are allowlisted for script loading and runtime network calls.

At minimum, teams usually need to verify policy coverage for:

  • script-src
  • connect-src
  • img-src
  • frame-src (if your environment uses embedded frames)

Coordinate with your security owner before release if your org blocks third-party script execution by default.

  1. Start with 1-2 high-intent pages (pricing, docs, help).
  2. Validate behavior and capture for 24-48 hours.
  3. Expand to more pages after quality checks pass.

Avoid rolling out everywhere before first validation.

Post-embed validation checklist​

Run in an incognito window:

  1. Widget appears and opens normally.
  2. Assistant responds to a known question.
  3. Conversation appears in Conversations.
  4. Metrics begin appearing in Signal Health.
  5. Repeated issues eventually appear in Friction Insights.

If item 1-2 work but item 3-5 do not, review environment blocking, assistant selection, and filters.

Common deployment issues​

Widget does not render​

Check:

  • chatbot-root exists on page
  • script is loaded successfully (no blocked network request)
  • no JavaScript errors in browser console

Wrong assistant appears​

Check:

  • correct assistantId in window.ChatbotConfig
  • deployment did not cache an old snippet

No data in Conversations after launch​

Check:

  • assistant is actually embedded on pages with traffic
  • date/assistant filters in Conversations are not narrowing results
  • browser/network tooling is not blocking requests

Script blocked in production only​

Most often this is CSP or edge security policy drift between staging and production.

Operational ownership​

Define these owners before broad rollout:

  • embed owner (implements snippet changes)
  • product owner (validates assistant behavior)
  • operations/support owner (monitors Conversations and Insights)

Safe rollback​

If severe issues appear:

  1. remove/disable embed snippet from affected pages
  2. verify widget no longer loads
  3. resolve root cause in staging
  4. redeploy with validation checklist