WordPress Integration Guide

QuackChat on WordPress

Add the QuackChat widget to your WordPress site in minutes. Works with all themes including Elementor, Divi, and Gutenberg.

Quick Start (TL;DR)

1. Download the QuackChat plugin: quackchat-widget.zip
2. Plugins → Add New → Upload Plugin → choose the zip → Install Now → Activate
3. Settings → QuackChat → paste your Bot ID → Save

Prerequisites

• WordPress admin access
• Bot ID from your QuackChat dashboard (Deploy page → Copy Bot ID)

Step-by-Step Installation

Option A: QuackChat Plugin (Recommended)

The official plugin, no code, no theme edits, survives theme updates.

1. Download the plugin zip: quackchat-widget.zip (also available from your dashboard's Deploy page).
2. In WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Choose quackchat-widget.zip, click Install Now, then Activate.
   • The plugin is distributed directly by QuackChat, so it won't appear in the plugin search. Use Upload Plugin.
4. Go to Settings → QuackChat and paste your Bot ID (you can also paste the whole embed snippet; the ID is picked out automatically).
5. Click Save Changes. The status banner shows Live ✓ and the widget appears site-wide.

Updates

From version 1.2.0, updates work the normal way: WordPress checks with us and shows them on your Plugins screen, so you can update with one click or switch on automatic updates.

If you're on 1.1.0 or earlier, you need to upload the zip by hand once to reach 1.2.0. Those versions have update checking switched off, so there's no way for us to reach them. After that you're done uploading zips.

Plugin settings:

• Bot ID: from your dashboard's Deploy page
• Enable widget: turn off to pause without uninstalling
• Position: bottom right (default) or bottom left
• Hide on cart & checkout (WooCommerce sites only). Recommended off: cart-recovery and free-shipping nudges fire on those pages

Option B: WPCode Snippet (Manual Fallback)

If you can't upload plugins (some managed hosts, or an upload that fails with a wp-content/uploads permission error), use the free WPCode – Insert Headers and Footers plugin instead. Installing from the plugin search doesn't use the uploads folder, so it works on sites where Upload Plugin fails:

1. In WordPress admin, go to Plugins → Add New Plugin, search WPCode Insert Headers and Footers, install and Activate.
2. Go to Code Snippets → Header & Footer, paste the widget snippet into the Footer box, and Save:

<script
  src="https://www.quackchat.app/widget/quackchat-widget.js"
  data-bot-id="YOUR_BOT_ID"
  async
></script>

If the code disappears when you save, your site strips <script> tags. Add it as a JavaScript Snippet instead (no <script> wrapper; WPCode adds it):

js

var s = document.createElement('script');
s.src = 'https://www.quackchat.app/widget/quackchat-widget.js';
s.setAttribute('data-bot-id', 'YOUR_BOT_ID');
document.body.appendChild(s);

Option C: Custom HTML Block (Specific Pages Only)

To add the widget to specific pages only:

1. Edit the page in WordPress
2. Add a Custom HTML block (in Gutenberg) or use a text widget
3. Paste the widget snippet from Option B
4. Publish the page

Note: This method loads the widget only on pages where you add the block. The plugin (Option A) is site-wide.

Page Builder Notes

The plugin (Option A) works with all page builders that render standard WordPress themes (Elementor, Divi, and Gutenberg included) because it injects via the theme footer.

• Elementor / Divi / Gutenberg: just use Option A.
• Fully headless or static-export setups (theme never calls wp_footer()): the plugin can't inject. Use the embed snippet from Option B wherever your setup allows custom scripts.

Verification

Quick test:

1. Visit your WordPress site (logged out or incognito)
2. Look for the chat bubble in the bottom-right corner
3. Click to open and send a test message

Troubleshooting

Two chat bubbles

Cause: The widget was previously installed via a code snippet (WPCode, theme editor) and the plugin is now also active.

Solution: Remove the old snippet. The plugin replaces it.

Widget doesn't appear after saving settings

Cause: Page-cache plugins bake the page HTML, so settings changes (enable/disable, Bot ID) don't show until the cache is purged.

Solution:

• Plugin 1.1.0 and later clears the cache for you when you activate it or change your Bot ID
• Otherwise purge your cache after changing QuackChat settings
• Exclude the widget script from minification/combining
• In WP Rocket: Add quackchat-widget.js to excluded files

I can see the chat, but my customers can't

Cause: Your page cache is serving a copy of the page saved before the widget was added. Caching plugins skip the cache for logged-in users, so you see the chat in your own browser while everyone else gets the old copy. On a phone, logged out, it disappears, which looks like a mobile problem but isn't one.

Check it in one step: open your site normally, then open it again with ?cb=123 on the end of the address. If the chat only shows up on the second one, it's the cache.

Solution:

• Plugin 1.1.0 and later clears this for you when you activate it, when you update it, and when you change your Bot ID or turn the widget on or off. The settings page tells you which caches it cleared. Caching run by your host or a CDN (Cloudflare, Kinsta, WP Engine and similar) is a separate layer we can't reach, so clear that from their dashboard
• Clearing by hand: pick the option that deletes the cache rather than the one that refreshes or revalidates it. A refresh keeps serving the old copy while it rebuilds, so the chat comes back for a few hours and then vanishes again
• In Seraphinite Accelerator: Manager → All pages/all views → Delete cache, plus Delete server's cache if you see it
• Wait for the rebuild to finish before you test
• Check while logged out, then check again the next day

Security plugin blocks the script

Cause: Some security plugins block external scripts.

Solution:

• Whitelist www.quackchat.app and api.quackchat.app
• Check Wordfence, Sucuri, or similar plugin settings

"The uploaded file could not be moved to wp-content/uploads/..."

Cause: The zip arrived fine, but WordPress can't save files on your server. It's a permissions or disk-space problem on the site, not a problem with the plugin. Upload Plugin is the only way of installing that needs that folder, which is why it fails while the rest of the site works. It's common on staging copies of a site, which keep the original's file ownership.

Check it in one step: go to Media → Add New and drop in any photo. It fails the same way. (If the photo uploads fine, this isn't your problem. Look for a security plugin blocking .zip files.)

Solution:

• Ask whoever hosts the site to fix write access to wp-content/uploads, or check the disk isn't full
• Tools → Site Health → Info → Filesystem Permissions tells you directly whether the uploads folder is writable
• To get going without waiting on them, use Option B above. Installing a plugin from the search doesn't use that folder, so it still works

"Installation failed: Could not create directory"

Cause: The web server can't write to wp-content/upgrade/ (permissions or disk space). This is the step straight after the upload above, so it's a different folder with the same cause.

Solution: Ask your host to fix ownership of wp-content/ for the web server user, or upload the extracted quackchat-widget/ folder to wp-content/plugins/ via SFTP.

Testing in WordPress

// In browser console, test if widget loaded:
console.log(typeof QuackChatWidget); // Should output: "object"

// Open widget programmatically:
QuackChatWidget.open();

WooCommerce

If you're using WooCommerce, see the dedicated WooCommerce guide for e-commerce-specific tips. The plugin is WooCommerce-aware out of the box.

Google Tag Manager & analytics

The widget reports booking and cart activity to your own analytics (booking-link clicks, confirmed bookings, product clicks and chat add-to-carts) with no extra setup on the WordPress side. See the Google Tag Manager guide to turn those into GA4 events.

Multisite

For WordPress Multisite installations:

• Per-site (recommended): Network-activate the plugin or activate it per site; each site configures its own Bot ID under Settings → QuackChat.
• Uninstalling removes the settings from every site.

Performance Tips

The widget script is injected with async, so it won't block your page from rendering.

Content-Security-Policy

Only relevant if your site sets a strict CSP. Most WordPress sites don't, and many security plugins add one without telling you.

Allowing the script alone isn't enough. The chat will load and then sit there half-working: no typeface, no avatar, no messages. You need all six of these directives:

script-src 'self' https://www.quackchat.app;
style-src 'self' 'unsafe-inline';
connect-src 'self' https://www.quackchat.app;
img-src 'self' https: data:;
font-src 'self' https://www.quackchat.app;
media-src 'self' https://www.quackchat.app;

Copy that exactly as it is. CSP has no comment syntax. A semicolon ends one directive and the next word starts another, so a note written beside a line is read as a directive name and silently swallows the line below it.

What each one is for:

• script-src: the widget itself
• style-src: the widget styles itself from inside its own container, and blocking inline styles gives you a fully working chat with no styling at all
• connect-src: sending and receiving messages
• img-src: your bot's avatar and any product card images
• font-src: the chat's typeface
• media-src: the notification sound

img-src is deliberately broader than one host. Your bot's avatar may be served from our file storage rather than the main domain, and product card images come from your own store or whatever CDN it uses. Pinning it to a list of hosts works until any one of those changes and then quietly breaks, leaving you a working chat with blank images. If your security policy won't allow https:, enumerate our domain, your store's domain and your CDN's, and re-check it whenever you move image hosting.

Two of these fail quietly rather than with an error you'd notice. A blocked font-src falls back to whatever serif your visitor's device happens to have, so the chat looks subtly wrong on some machines and fine on yours. A blocked media-src just means no sound. If the chat looks off but works, check the console for CSP warnings before assuming it's a theme conflict.