Embed on a custom website

The custom-website embed is the simplest deployment — one <script> tag and the widget loads on every page that includes it.

In this guide:

• Get the embed snippet
• Install on your site
• Configure inline options
• Restrict to allowed domains
• Verify it works

Step 1: Get the snippet

On your chatbot detail page, click Install. The snippet looks like:

<script src="https://cdn.hilalsoftware.tools/chat_v3.js"></script>
<script>
  window.HilalChat.init({
    organizationId: 'org_abc123',
    botId: 'bot_xyz789',
    theme: 'light'
  });
</script>

Click Copy to copy yours.

Screenshot: The Install tab with copy buttons for the embed snippet.

Step 2: Install on your site

Paste the snippet just before </body> on every page where you want the widget.

If you’re using a tag manager (Google Tag Manager, Segment), create a Custom HTML tag with the snippet and trigger it on All Pages.

Step 3: Configure inline options

The init() config object accepts:

Step 4: Restrict to allowed domains

By default, the widget will load anywhere — you should lock it down to your real domains so no one can embed your bot on a phishing page.

In Install → Allowed domains, add each domain (example.com, www.example.com, app.example.com). Subdomain wildcards work (*.example.com).

The widget refuses to send messages from any other origin and the API rejects calls from non-allowed referrers.

Step 5: Verify

Visit a page where you installed the snippet:

1. Open browser DevTools → Console.
2. Look for any errors. A 404 on chat_v3.js means the script URL is wrong.
3. The chat bubble should appear in the configured corner within ~1 second of page load (the widget lazy-loads).
4. Click the bubble → send a test message → expect a normal reply.

Performance notes

• Lazy loading. The full chat UI only loads when the user clicks the bubble — first page load only fetches a small bootstrap (~25 KiB gzipped).
• Shadow DOM. The widget renders in a shadow root, so its CSS never leaks into your site’s styles.
• Async script. The snippet is non-blocking — it doesn’t slow down your page’s first paint.

Troubleshooting

• Widget never appears. Console says Refused to load? The host page’s CSP blocks scripts. Add cdn.hilalsoftware.tools to your script-src.
• Widget appears on dev but not prod. You added localhost to allowed domains but not your prod domain. Add the prod domain.
• Send fails with “Origin not allowed.” Check Install → Allowed domains and confirm the exact origin (with the right protocol and subdomain).

What’s next