← Back to blog

How to Add the Embeddable Widget to Your Website

· 6 min read · Heedback Team

Your customers shouldn’t have to hunt for a “Contact Us” page buried three clicks deep. Heedback’s embeddable widget puts support, conversations, and self-service content right where users already are — on your website or app. In this guide, we’ll walk through installation, configuration, and testing so you can go live in under ten minutes.

Prerequisites

Before you begin, make sure you have:

  • A Heedback account with at least one organization set up
  • Access to your website’s HTML, or the ability to modify your frontend framework’s entry point (React, Vue, Next.js, etc.)
  • Your organization’s widget embed code, available under Settings → Widget in the Heedback dashboard

Step 1: Copy the Embed Snippet

Navigate to Settings → Widget in your Heedback dashboard. You’ll find a ready-to-use script tag that looks like this:

<script
  src="https://widget.heedback.com/embed.js"
  data-org-id="your-org-id"
  async
></script>

This snippet loads the widget asynchronously, so it won’t block your page from rendering. Copy it — you’ll paste it into your site in the next step.

Step 2: Add the Widget to Your Site

Plain HTML: Paste the snippet just before the closing </body> tag in your main HTML file. That’s it — the widget will appear on every page that includes this script.

React / Next.js: Add the script to your root layout or use a useEffect hook to inject it dynamically. If you’re using Next.js App Router, place it in app/layout.tsx using the <Script> component with strategy="afterInteractive".

Vue / Nuxt: In Nuxt, add the script to nuxt.config.ts under the app.head.script array. In a standard Vue app, inject it in your index.html or mount it in App.vue’s onMounted lifecycle hook.

Single-page apps: The widget persists across route changes automatically. No special handling is needed for client-side navigation.

Step 3: Configure Appearance

Back in Settings → Widget, you can customize how the widget looks and behaves:

  • Brand color: Set a primary color that matches your brand. The widget button, headers, and accent elements will adopt this color.
  • Position: Choose bottom-right or bottom-left placement. Bottom-right is the convention most users expect, but pick whichever avoids overlapping with other UI elements.
  • Welcome message: Write a short greeting that appears when users open the widget for the first time. Keep it warm and actionable — something like “Hi! How can we help you today?”
  • Logo: Upload your company logo to appear in the widget header for brand consistency.

Changes are saved instantly and reflected on your live site without redeploying.

Step 4: Explore Widget Features

The widget isn’t just a chat box. Depending on your plan and configuration, customers can:

  • Start or continue conversations: Real-time messaging with your support team, with full history preserved across sessions.
  • Browse your knowledge base: Articles from your help center surface directly inside the widget, letting users self-serve without leaving your app.
  • Search for answers: A built-in search bar queries your knowledge base so customers find relevant articles before opening a conversation.
  • Submit feature requests: If you’ve enabled feature boards, users can browse and vote on ideas without leaving your site.
  • View announcements: Changelog entries can appear in the widget, keeping customers informed about new features and fixes.

Step 5: Identify Logged-In Users

By default, widget visitors are anonymous. To associate conversations with known users — so your team sees names, emails, and history — pass user data via the JavaScript API:

<script>
  window.heedbackSettings = {
    user: {
      id: "usr_abc123",
      email: "jane@example.com",
      name: "Jane Doe",
    },
  };
</script>

Place this before the embed script. When a logged-in user opens the widget, their conversations are linked to their profile in Heedback. This eliminates the need for users to identify themselves manually and gives your agents full context from the first message.

Step 6: Test Before Going Live

Before pushing to production, verify the widget works correctly:

  1. Open your site in an incognito window to simulate a first-time visitor. The widget button should appear in the configured position.
  2. Send a test message and confirm it arrives in your Heedback inbox.
  3. Reply from the dashboard and verify the response appears in the widget in real time.
  4. Test on mobile — the widget is responsive and adapts to smaller screens automatically.
  5. Check for z-index conflicts — if the widget appears behind modals or sticky headers, reach out to support for CSS override guidance.

Tips and Best Practices

  • Don’t hide the widget behind a menu. The whole point is instant access. Let it float visibly on every page.
  • Use identified users whenever possible. Anonymous conversations create friction when users return — they lose history and your agents lose context.
  • Keep your knowledge base updated. The widget’s self-service value is only as good as the content behind it. Stale articles erode trust.
  • Monitor widget engagement in your Heedback analytics dashboard. Track how many users open it, how many self-serve via articles, and how many start conversations.
  • Knowledge Base — The articles your widget surfaces come from here. A well-organized help center makes the widget dramatically more useful.
  • AI Auto-Reply — Enable AI-powered responses so customers get instant answers even when your team is offline.
  • Multi-Language Support — Serve the widget in your customers’ preferred language automatically.
  • Notifications — Make sure your team gets alerted the moment a customer reaches out through the widget.