Platform Install Guides & Troubleshooting

Step-by-step instructions for adding the ZipTier embed widget to popular website platforms, plus a Next.js / React note and a troubleshooting section for common issues. For the widget's attributes and styling options, see Widget Customization.

Where the Script Goes

On every platform, the goal is the same: add the widget's <script> tag just before the closing </body> of the pages where the AI Assistant should appear. Most platforms expose a "footer" or "code injection" setting for exactly this.

<script
  src="https://chat.ziptier.ai/wgt/script/latest.js"
  data-chat-url="https://chat.ziptier.ai/bt/v1?id=1234567890"
></script>

Platform-Specific Instructions

WordPress

1. Go to Appearance > Theme Editor (or use a plugin like "Insert Headers and Footers").
2. Locate your theme's footer.php file.
3. Paste the script tag just before </body>.
4. Save changes.

Shopify

1. Go to Online Store > Themes.
2. Click Actions > Edit Code.
3. Open theme.liquid.
4. Paste the script tag just before </body>.
5. Save changes.

Webflow

1. Go to Project Settings > Custom Code.
2. Paste the script in the Footer Code section.
3. Publish your site.

Squarespace

1. Go to Settings > Advanced > Code Injection.
2. Paste the script in the Footer section.
3. Save changes.

Next.js / React

Plain <script> tags can execute before React finishes hydrating the page, causing a DOM mismatch and an error overlay. On Next.js sites, load the widget with next/script using strategy="afterInteractive":

import Script from 'next/script';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <Script
        src="https://chat.ziptier.ai/wgt/script/latest.js"
        data-chat-url="https://chat.ziptier.ai/bt/v1?id=1234567890"
        strategy="afterInteractive"
      />
    </>
  );
}

Other React frameworks: mount the script in an effect that runs after first paint, or use the framework's equivalent of an "after interactive" load strategy.

Troubleshooting

Standalone Page Issues

• Link not working. Verify the campaign is within its active date range.
• Wrong content displaying. Confirm you're using the correct campaign link.
• Page not loading. Check your internet connection and try refreshing.

Website Embed Issues

• Widget not appearing.
  • Check the data-chat-url matches your campaign link.
  • Verify the campaign is within its active date range.
  • Look for JavaScript errors in the browser console.
  • Disable ad blockers that may interfere with third-party scripts.
• Widget positioned incorrectly.
  • Your site's CSS may override widget positioning.
  • Try switching between bottom-right and bottom-left.
• Widget conflicts with other elements.
  • Other floating elements (cookie banners, chat widgets) may overlap.
  • Check z-index conflicts in your site's CSS.
• Page shows an error after adding the widget (React / Next.js sites).
  • This can happen because a plain <script> tag executes before React finishes hydrating the page, causing a DOM mismatch.
  • Fix it by loading the script with next/script using strategy="afterInteractive" instead of a plain <script> tag. See the Next.js / React section above.

Custom Trigger Issues

• Trigger doesn't open the widget. Custom triggers require the main embed widget to be present on the page. Confirm the widget <script> tag is installed alongside your triggers.
• Auto-styled trigger doesn't render. The ziptier-widget-trigger class must be on the element itself, not on a parent wrapper. Also verify data-button-style is one of the supported values (pill, fab, avatar, textbox).