Install guides / WordPress
Install the SupportHQ widget on WordPress
On WordPress the reliable way to add a site-wide script is a header and footer plugin, which survives theme updates. Editing the theme directly also works but is overwritten when the theme updates unless you use a child theme.
The snippet is two script tags. Nothing else is needed: no shortcode, no block, no PHP.
Requirements: Works on any self-hosted WordPress site. On WordPress.com, plugins and custom code require the Business plan or higher.
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
Install a header and footer plugin
In WordPress admin go to Plugins, Add New, and install a plugin that inserts code into the footer (WPCode, "Insert Headers and Footers", or similar). Activate it.
- 3
Paste into the footer slot
Open the plugin's settings and paste the snippet into the Footer (before closing body) box. Save.
- 4
Clear caches
If you use a caching plugin (WP Rocket, W3 Total Cache, LiteSpeed Cache) or a host cache, purge it so the new footer is served.
Where it goes: The Footer box of a header and footer plugin. Alternative: Appearance, Theme File Editor, footer.php, before the closing body tag, in a child theme so a theme update does not remove it.
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 WordPress
- Do not paste the snippet into a post or page with the block editor. WordPress strips script tags from content for most user roles.
- Optimization plugins that "defer" or "delay" JavaScript can run the init call before the CDN script has loaded. Exclude supporthq-widget.js from delay or deferral in the plugin settings, or keep both tags together in the same footer slot.
- Editing footer.php in a parent theme is lost on the next theme update. Use a plugin or a child theme.
- Some security plugins block third-party scripts by default. Allow cdn.supporthq.app.
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
Do I need a SupportHQ WordPress plugin?
No. The widget is a script tag, so any header and footer plugin works. There is nothing to configure on the WordPress side beyond pasting the snippet.
Will it work with WooCommerce?
Yes. The footer snippet loads on every page including shop, cart, and account pages. Checkout pages are included on standard WooCommerce; page builders that replace the footer may need the snippet added in their own settings.
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.