Install guides / plain HTML
Install the SupportHQ widget on any HTML site
If you can edit your site's HTML, the install is two script tags before the closing body tag. This is the base method every platform guide on this site builds on, and it works with static site generators (Astro, Hugo, Jekyll, Eleventy), hand-written HTML, and any CMS that lets you edit templates.
This page also covers embedded mode, the data-attribute auto-init, and the small JavaScript API for opening and closing the widget from your own buttons.
Requirements: No platform requirements. Any page that can load a script.
Steps
- 1
Copy your embed code from SupportHQ
In the SupportHQ dashboard open your project, go to Integrations, choose Web chat, and copy the HTML snippet.
- 2
Paste before the closing body tag
Open your HTML template or layout file and paste the snippet just before </body>. In a static site generator, the base layout that wraps every page is the right place.
- 3
Deploy
Publish or deploy the site as usual. The widget loads on every page that uses the layout you edited.
- 4
Optional: customize
Add options to the init call: themeColor, theme ("light", "dark", "auto"), position ("bottom-right" or "bottom-left"), requiredFields (["email"] to ask for an email first), and metadata for context your team sees on handoff. The dashboard embed generator emits these for you.
Where it goes: Immediately before the closing body tag in the layout that wraps every page.
The snippet
Replace YOUR_PROJECT_ID, or copy the ready-made version from Integrations, Web chat in your dashboard.
<script src="https://cdn.supporthq.app/widget/latest/supporthq-widget.js"></script>
<script>
SupportHQWidget.init({
projectId: 'YOUR_PROJECT_ID',
})
</script>Things that go wrong on plain HTML
- Placing the script in the head runs init before the body exists. Keep it at the end of the body, or wrap init in a DOMContentLoaded listener.
- If you use a Content Security Policy, allow script-src cdn.supporthq.app and connect-src api.supporthq.app.
- Calling init twice (for example from two templates) creates two launchers. Call it once per page load.
Verify it works
- Open the published page in a private browser window. The launcher bubble should appear in the bottom-right corner within a second or two of the page loading.
- Click the bubble and ask a question your knowledge base covers. The reply should come from your content. Ask something it does not cover and confirm it says it does not know and offers to bring in a person.
- Open the same page on a phone. The panel should open full-height and the keyboard should not cover the reply.
- Check the SupportHQ inbox. The test conversation should be there with the page URL in its metadata.
FAQ
Is there a way to initialize without a second script tag?
Yes. Add data-project-id="YOUR_PROJECT_ID" to the script tag and the widget initializes itself on load. The dashboard shows the two-tag form because it is easier to add options to.
How do I open the widget from my own link?
After init, call SupportHQWidget.open() from a click handler. close(), show(), hide(), update(options), and destroy() are also available on window.SupportHQWidget.
Where do I find my project ID?
In the SupportHQ dashboard, open your project, go to Integrations, and choose Web chat. The embed code shown there already contains your project ID and any options you set (theme color, position, required fields). Copy it from there instead of typing it.
Will the widget slow my site down?
The script loads from a CDN. Place it at the end of the body, or use the async pattern shown for React and Next.js, and it will not block your page from rendering. Your content paints first.
Can I put the widget inside the page instead of a floating bubble?
Yes. Add a container element and pass mode: "embedded" and, if needed, container: "#your-id" to init. The chat renders inside that element at the width and height you set.