Implementation Guide

​

Basic Implementation Recap

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>

​

Platform-Specific Implementations

​

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)

​

React Applications

​

React / Next.js Applications (Recommended)

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

​

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

​

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).