Guide
External Embed
This page explains how to embed the SRV AI Chatbot widget on a website other than your WHMCS client area — for example, your main marketing site. It is for administrators who want the same assistant available outside WHMCS.
Prerequisites
- Enable external-site embed must be turned on globally in Settings → General (see General Settings).
- You need an existing assistant to embed — embed configuration is set per assistant.
Configuring embed on an assistant
Go to Addons → AI Copilot Suite → Assistants → Edit on the assistant you want to embed. Scroll to the External Embed section (available once the assistant has been saved at least once).
| Friendly name | System name | Type | Default |
|---|---|---|---|
| Embed Enabled | embed_enabled |
toggle | Off |
| Allowed Origins | embed_allowed_origins |
textarea, one full origin URL per line | — (empty = all embed requests blocked) |
| Site Key | — | read-only, auto-generated 32-character hex value | — |
| Embed Code | — | read-only, ready-to-copy <script> tag |
— |
Warning
Allowed Origins is a strict allow-list, enforced by the server: only requests whose origin exactly matches an entry in this list are accepted. If the list is empty, all embed requests for this assistant are blocked — this is a safe default.
An origin is the scheme + host + port of a site, e.g. https://www.example.com (not a full page URL, and not a wildcard).
Getting the embed code
Once this assistant's Embed Enabled toggle is on and at least one origin is listed, click Save. The panel then displays a ready-to-copy snippet similar to:
<script src="https://your-whmcs-domain.example/modules/addons/srv_aichatbot/assets/embed.js" data-site-key="YOUR_SITE_KEY" async></script>
Paste this snippet into the HTML of every page on the external site where the widget should appear (commonly just before the closing </body> tag).
Regenerating the site key
Click Regenerate Key to invalidate the current key and issue a new one.
Caution
Regenerating the key immediately breaks any existing embed code still using the old key — every external site using this assistant's embed must have its <script> tag updated with the new data-site-key.
How it works (for reference)
The embedded script reads its data-site-key, requests that site's configuration (API URL, base theme, active Theme Studio tokens, position, offsets, language, icon, sanitized custom CSS), and then loads the same widget interface used in the client area, scoped to the registered site and its allowed origins. Appearance choices from Appearance apply to embed the same way they apply in the client area.
Troubleshooting
| Problem | Fix |
|---|---|
| Widget does not appear on the external site | Confirm Enable external-site embed is on globally (Settings → General) and Embed Enabled is on for this assistant, and that the embedding site's exact origin is listed in Allowed Origins |
| Widget stops working after a domain or protocol change (http → https) | Update Allowed Origins to match the new exact origin |
| Old embed code stopped working | The site key was likely regenerated — copy the current Embed Code and update the external site |