# Embed Chat Widget Add your AI chatbot to any website with a floating chat bubble or iframe embed. --- Add your Chipp AI chatbot to any website using either a floating chat bubble widget or an embedded iframe. Choose the option that best fits your site's design. ## Embed Options | Option | Best For | |--------|----------| | **Chat Widget** | Floating bubble in corner, doesn't take page space | | **Iframe** | Dedicated chat section embedded in your page | --- ## Option 1: Chat Widget (Floating Bubble) The chat widget adds a floating chat bubble to the corner of your page. When clicked, it opens your chatbot in an overlay. It's lightweight (~5KB gzipped), uses Shadow DOM for CSS isolation, and works on any website. ### Quick Start Add a single ` ``` That's it. The widget auto-detects your app from the subdomain and renders a floating chat bubble in the bottom-right corner. ### Getting the Widget Code **1.** Go to Share Settings Open your app and click **Launch > Share** in the navigation. **2.** Find the Widget Card Look for the **Chat Widget** card on the Share page. **3.** Copy the Code Click the code snippet to copy it to your clipboard: ```html ``` **4.** Add to Your Website Paste the code before the closing `
` tag" section **For Iframe:** 1. Add a **Code** component 2. Paste the iframe embed code ### Kajabi > **Tip:** See the full step-by-step walkthrough at [Embed Chipp into Kajabi](/docs/guides/embed-on-kajabi). Kajabi fully supports both the floating widget and inline iframe embeds. You have two routes -- pick the one that fits your goal. **For Widget (site-wide -- recommended):** This is the easiest route. The widget appears on every page of your Kajabi site (excluding the checkout and upsell pages, which Kajabi locks down). 1. In your Kajabi admin, go to **Settings** > **Site Details** 2. Scroll to the **Header Page Scripts** section 3. Paste the widget script tag 4. Click **Save** The widget will appear as a floating bubble on every public page. **For Widget (per-page):** If you only want the widget on specific pages (e.g. a sales page, a specific landing page), use a Custom Code block instead. 1. Open the page in the Kajabi page builder (**Website > Pages**, **Marketing > Landing Pages**, or **Products > Customize** on the Premier theme) 2. Click **Customize > Add block > Custom Code** 3. Paste the widget script tag 4. Click **Save** and republish the page **For Iframe (per-page):** 1. Open the page in the Kajabi page builder 2. Click **Customize > Add block > Custom Code** 3. Paste the iframe code 4. Click **Save** and republish the page > **Note:** **Momentum-theme Product pages:** Kajabi's Momentum theme blocks `` tag on your website. ### Customizing with Data Attributes You can customize the widget by adding `data-*` attributes to the script tag: ```html ``` #### Attribute Reference | Attribute | Default | Description | |-----------|---------|-------------| | `data-app-id` | *(auto-detected from subdomain)* | App slug, e.g. `my-app`. Required when hosting the script from a different domain | | `data-position` | `bottom-right` | Widget position: `bottom-right`, `bottom-left`, `top-right`, `top-left` | | `data-theme` | `auto` | Color theme: `light`, `dark`, `auto` (follows user's OS preference) | | `data-greeting` | *(none)* | Greeting message shown as a preview bubble above the chat button | | `data-greeting-delay` | `2000` | Delay in milliseconds before the greeting appears (0-30000) | | `data-auto-open` | *(disabled)* | Automatically open the chat after this many milliseconds (e.g. `5000` for 5 seconds). Set `false` to keep the chat closed on this page even when the app's widget settings auto-open it | | `data-color` | *(app brand color)* | Bubble background color as a hex value (e.g. `#2563EB`) | | `data-bubble-size` | `60` | Bubble diameter in pixels (48-80) | | `data-bubble-shape` | `circle` | Bubble shape: `circle` or `rounded` (rounded rectangle) | | `data-icon-url` | *(app logo)* | Custom icon URL for the bubble (falls back to app logo, then a chat icon) | | `data-z-index` | `2147483646` | CSS z-index for the widget container | | `data-hide-on-mobile` | `false` | Set to `true` to hide the widget on mobile viewports | | `data-lang` | *(auto)* | Display language code (e.g. `fr`, `de`, `es`). Shows the app's localized title, description, and conversation starters for that language (configure them under Experience > Identity > Languages) plus matching interface chrome. Set it per page, so the French version of your site can load `data-lang="fr"` while the English version omits it. When unset, the language is resolved from the visitor's saved preference, then their browser language (only when you configured that language), then the app default | #### Config Priority Data attributes take the highest priority. If you set a value via `data-*`, it overrides the server-side configuration. The full priority order is: 1. **Data attributes** on the ` ``` ### React Integration ```jsx import { useEffect } from "react"; function App() { useEffect(() => { // Load the widget script const script = document.createElement("script"); script.src = "https://your-app.on.chipp.ai/w/chat/chipp-widget.js"; script.async = true; document.body.appendChild(script); return () => { // Clean up on unmount if (window.ChippWidget) { window.ChippWidget.destroy(); } script.remove(); }; }, []); return ( ); } ``` ### Next.js Integration ```jsx "use client"; import Script from "next/script"; export default function ChatWidget() { return ( ); } ``` ### Auto-Open After a Delay Open the chat automatically after 5 seconds, useful for onboarding flows: ```html ``` ### Track Conversations in Analytics ```javascript ChippWidget.on("open", () => { // Google Analytics gtag("event", "chat_opened", { event_category: "engagement" }); }); ChippWidget.on("message", (data) => { if (data.role === "user") { gtag("event", "chat_message_sent", { event_category: "engagement" }); } }); ``` ### Conditional Widget Loading Only load the widget for certain users or pages: ```javascript if (window.location.pathname.startsWith("/support")) { const script = document.createElement("script"); script.src = "https://your-app.on.chipp.ai/w/chat/chipp-widget.js"; script.dataset.greeting = "How can we help with your support issue?"; document.body.appendChild(script); } ``` ### Server-Side Auth with React ```jsx import { useEffect } from "react"; function ChatWidget({ user }) { useEffect(() => { if (!user || !window.ChippWidget) return; // Call your backend to get a widget token fetch("/api/chat-token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ email: user.email, name: user.name }), }) .then((res) => res.json()) .then(({ token }) => { window.ChippWidget.setUser({ email: user.email, name: user.name, token, }); }); }, [user]); return null; } ``` --- ## Option 2: Iframe Embed The iframe embeds your chatbot directly into your page layout. Use this when you want the chat to be a fixed part of the page rather than a floating overlay. ### Getting the Iframe Code **1.** Go to Share Settings Open your app and click **Launch > Share** in the navigation. **2.** Find the Iframe Card Look for the **Embed with Iframe** card on the Share page. **3.** Copy the Code Click the code snippet to copy it: ```html ``` The `allow="microphone; clipboard-write; screen-wake-lock"` attribute is required for voice mode to work properly on mobile devices. Without `screen-wake-lock`, the phone screen will lock during a voice call and end the conversation. **4.** Add to Your Website Paste the iframe code into your website's HTML where you want the chat to appear. ### Customizing the Iframe **Adjust dimensions:** ```html ``` **Responsive container:** ```html
``` --- ## Platform-Specific Instructions ### WordPress **For Widget:** 1. Go to **Appearance** > **Theme Editor** (or use a plugin like "Insert Headers and Footers") 2. Add the widget code before `` in your theme's footer **For Iframe:** 1. Edit your page or post 2. Add a **Custom HTML** block 3. Paste the iframe code ### Webflow 1. Go to **Project Settings** > **Custom Code** 2. For widget: Paste in "Footer Code" 3. For iframe: Add an **Embed** element to your page ### Squarespace **For Widget:** 1. Go to **Settings** > **Advanced** > **Code Injection** 2. Paste in the "Footer" section **For Iframe:** 1. Add a **Code Block** to your page 2. Paste the iframe code ### Shopify **For Widget:** 1. Go to **Online Store** > **Themes** > **Edit code** 2. Find `theme.liquid` and paste before `` **For Iframe:** 1. Edit the page where you want the chat 2. Add a **Custom Liquid** section 3. Paste the iframe code ### Wix **For Widget:** 1. Go to **Settings** > **Custom Code** 2. Click **Add Code in the Body - End** 3. Paste the widget script tag **For Iframe:** 1. Add an **HTML iframe** element to your page 2. Set the source URL to your app URL ### Framer **For Widget:** 1. Go to **Site Settings** > **Custom Code** 2. Add the widget script in the "End of `
`, not inside `
` 2. **Check for conflicts**: Other scripts may interfere -- check browser console for errors 3. **Check app status**: Ensure your app is published and active 4. **Check CSP**: Your site's Content Security Policy may block the script or iframe 5. **Check mobile**: If `data-hide-on-mobile="true"` is set, the widget won't appear on mobile ### Widget Appears But Chat Won't Open 1. **Check the console**: Look for network errors or CORS issues 2. **Check the app URL**: Ensure the app is reachable at the URL in the script `src` 3. **Check authentication**: If auth is enabled, use `setUser()` with a token or set up a custom domain ### Iframe Shows "Session Not Found" Error This typically means the browser is blocking cookies in the cross-origin iframe context. Chipp handles this automatically, but some strict privacy settings can still interfere: 1. **Safari ITP**: Safari aggressively blocks third-party cookies. Use a custom domain (subdomain of your site) or server-side auth with `setUser({ token })` 2. **Chrome Incognito**: Third-party cookies may be blocked by default in Incognito mode 3. **Browser extensions**: Privacy extensions (uBlock Origin, Privacy Badger) may block cross-site cookies ### Iframe Not Loading 1. **Check the URL**: Make sure the iframe `src` matches your app's URL exactly 2. **CSP headers**: Your site's Content Security Policy may block iframes 3. **X-Frame-Options**: Some hosting providers set `X-Frame-Options: DENY` by default ### Styling Issues 1. **Z-index conflicts**: Use the `data-z-index` attribute to adjust widget stacking order 2. **Container overflow**: For iframe, make sure parent elements don't have `overflow: hidden` 3. **Mobile display**: Use `data-hide-on-mobile="true"` if the widget conflicts with your mobile layout 4. **Double widget**: If you see two widgets, make sure the script tag is only included once. The widget prevents double-initialization, but old v1 and new v2 scripts can coexist ### User Identity Not Working 1. **Check `setUser` timing**: Call `setUser()` after the widget script has loaded. Listen for the `ready` event if needed: ```javascript ChippWidget.on("ready", () => { ChippWidget.setUser({ email: "user@example.com" }); }); ``` 2. **Check token validity**: Server-side tokens expire. Generate a fresh token on each page load 3. **Check API key scope**: The Builder API key must have **write** scope to call `/consumers/auth`