Implementation Guide

This guide covers techniques for implementing the Chatmode embed using the standard Bubble Code snippet across different platforms and frameworks.

​

Basic Implementation Recap

The standard method involves adding the script tag, copied from your Environment settings, to your website HTML.

1. Navigate to your EMBED Environment settings in Chatmode.
2. Find the Implementation / Share section.
3. Copy the “Bubble Code” snippet.
4. Paste the snippet into your HTML, usually before the closing </body> tag.

<!-- Example Snippet Structure - Copy the exact code from Chatmode UI! -->
<script type="module">
  import Chatmode from "https://cdn.jsdelivr.net/npm/@chatmode/embed/+esm";

  // Store the return value if you need programmatic control
  const chat = Chatmode.initBubble({
    // Required - Copied from UI
    environmentId: "YOUR_ENVIRONMENT_ID",

    // Optional - Copied from UI if set
    // iconKey: "YOUR_ICON_KEY",
    // updatedAt: TIMESTAMP,

    // Optional - Can be added/modified manually
    theme: "automatic",
  });

  // Example: Open chat via custom button
  // document.getElementById('my-help-button')?.addEventListener('click', () => chat.open());
</script>

This script adds the floating chat bubble to your page.

​

Platform-Specific Implementations

Here’s how you might add the copied script snippet in common setups:

​

WordPress

​

Using a Plugin (Recommended)

1. Install and activate a plugin that allows adding code snippets to headers/footers (e.g., “WPCode”, “Header Footer Code Manager”, “Insert Headers and Footers”).
2. Go to the plugin’s settings page.
3. Create a new snippet.
4. Paste the copied Chatmode Bubble Code snippet into the code area.
5. Configure the snippet location to be in the Footer.
6. Ensure the snippet is active and save.

​

Theme File Integration (Advanced)

If using a child theme, you could edit its footer.php file and paste the script snippet directly before the <?php wp_footer(); ?> call or the closing </body> tag.

​

React Applications

Use a useEffect hook in a layout component or the main App component to append the script dynamically only on the client-side. Ensure you handle cleanup.

​

React / Next.js Applications (Recommended)

For modern JavaScript frameworks like React or Next.js, the recommended approach is to dynamically import the @chatmode/embed package within a client-side component. This ensures the embed code is loaded only when needed and integrates well with the framework’s lifecycle and build process.

Steps:

1. Install the package:
   Copy

   npm install @chatmode/embed
   # or
   yarn add @chatmode/embed
   # or
   pnpm add @chatmode/embed
   

2. Create a Client Component: Create a component that will handle loading the embed. Ensure it’s marked as a client component (e.g., using "use client"; in Next.js App Router).
3. Use useEffect for Initialization: Inside the component, use a useEffect hook to dynamically import and initialize the bubble. Also, implement a cleanup function to remove the embed when the component unmounts.

// Example Client Component (e.g., components/ChatEmbedLoader.tsx)
"use client";

import { useEffect } from "react";
import { useTheme } from "next-themes"; // Example using next-themes

import type { BubbleControls } from "@chatmode/embed";

export function ChatEmbedLoader() {
  const { resolvedTheme } = useTheme(); // Use your theme detection logic

  useEffect(() => {
    let chatmodeBubble: BubbleControls | null = null;

    const loadEmbed = async () => {
      try {
        // Dynamically import the embed package
        const { default: Chatmode } = await import("@chatmode/embed");

        // Initialize using your Environment ID from the Chatmode UI
        // Pass the theme based on your application's logic
        chatmodeBubble = Chatmode.initBubble({
          environmentId: "YOUR_ENVIRONMENT_ID_FROM_UI", // <-- Replace this!
          theme: resolvedTheme === 'dark' ? 'dark' : 'light',
          // iconKey and updatedAt might be needed if using a custom icon
          // iconKey: "YOUR_ICON_KEY_FROM_UI",
          // updatedAt: YOUR_TIMESTAMP_FROM_UI,
        });
      } catch (error) {
        console.error("Failed to load Chatmode embed:", error);
        // Optionally, report error to a tracking service
      }
    };

    // Load the embed when the component mounts
    loadEmbed();

    // Cleanup function: Remove the embed when the component unmounts
    return () => {
      if (chatmodeBubble) {
        chatmodeBubble.remove();
        chatmodeBubble = null;
      }
    };
    // Re-run the effect if the theme changes
  }, [resolvedTheme]);

  return null; // This component doesn't render anything itself
}

// Then, import and use <ChatEmbedLoader /> in your root layout or main App component.

​

Advanced Considerations

​

Conditional Loading

To load the chat bubble only under certain conditions, conditionally execute the JavaScript code that appends the script tag. In frameworks like React/Vue/Angular, wrap the script-appending logic within your component’s conditional rendering logic.

​

Performance Optimization

• Dynamic Import (Advanced): Instead of pasting the script content directly, you could dynamically import the @chatmode/embed module only when needed (e.g., after user interaction or page load completion), though this requires a more complex setup.
• Script Location: Placing the script tag just before </body> is generally good practice.

​

Interaction with Parent Page

Direct interaction (calling functions like identify, setContext) is not supported by the standard Chatmode.initBubble method.

However, you can programmatically control the chat modal’s state (open, close, toggle) using the object returned by Chatmode.initBubble. See the Customization Guide for details.

If you need to hide the bubble itself based on page logic, you might need to resort to conditional loading (not adding the script) or CSS overrides (display: none !important;) targeting the bubble elements (not recommended).

​

Implementation Checklist

• Copied Bubble Code snippet from Chatmode Environment settings.
• Snippet pasted into relevant HTML page(s) or loaded via framework component logic.
• Bubble appears correctly on desktop and mobile devices.
• Chat functionality tested by clicking the bubble and interacting.

​

Troubleshooting

• Bubble Not Appearing: Verify the script snippet was copied correctly and completely. Check for JavaScript errors in the browser console. Ensure the Environment ID and Org ID in the snippet are correct.
• Styling Issues: Check for general CSS conflicts on your page. Overriding the bubble’s internal styles directly is not recommended.
• Z-index Problems: If the bubble is hidden behind other elements, try increasing the z-index of a parent container on your page.
• Multiple Bubbles: Ensure the script is only loaded/initialized once per page load, especially in Single Page Applications.

​

Next Steps

• Test thoroughly across different browsers and devices.
• Adjust Environment settings in Chatmode for chat interface configuration (Display Name, Picture, Colors, Initial Message).