AI Help Center

``` **Option 2: Page Template** Create a custom page template in your theme: ```php theme={null}

``` ### Webflow 1. Create a new page (e.g., "AI Help") 2. Add an Embed element anywhere on the page 3. Paste the following code: ```html theme={null}

``` 4. Set the page body to have no padding/margin for full-screen experience ### Framer 1. Create a new page 2. Add a Code component from the components panel 3. Set it to "Custom Code" and paste: ```html theme={null}

``` 4. Set the page layout to fill the screen for best results *** ## Styling & Layout ### Container Styling The AI Page fills its parent container. For best results: ```css theme={null} #bubblav-ai-page { width: 100%; height: 100vh; /* Full viewport height */ margin: 0; padding: 0; overflow: hidden; /* Prevent scrollbars */ } ``` ### Theme Options Choose between two built-in themes: **Light Theme:** ```html theme={null} data-theme="light" ``` **Dark Theme:** ```html theme={null} data-theme="dark" ``` The theme controls the color scheme of the entire interface including the chat sidebar, message bubbles, and input area. *** ## Advanced Configuration ### Custom Titles Change the header text: ```html theme={null} data-title="How can I help you today?" ``` ### Custom Placeholder Change the input placeholder: ```html theme={null} data-placeholder="Type your question here..." ``` *** ## How It Works 1. **Script loads**: The ai-page.js loader fetches the latest version 2. **Widget initializes**: React component mounts in the container 3. **User sends message**: Chat streams responses in real-time 4. **Sources displayed**: AI responses include citations from your knowledge base 5. **Conversation history**: Chat persists during the session *** ## Best Practices The AI Page is designed for full-page experiences. Use it on dedicated routes like `/help`, `/support`, or `/ai-chat`. Choose light or dark theme based on your website's design for seamless integration. Customize the title and placeholder to match the purpose of your page (e.g., "Product Support" vs "Sales Assistant"). Ensure your API endpoint is accessible and properly configured before going live. The AI Page uses your plan's message limits. Monitor usage in your dashboard. *** ## Troubleshooting * Verify the container div with `id="bubblav-ai-page"` exists * Check browser console for JavaScript errors * Ensure your API key is correct * Confirm the script URL is loading (check Network tab) * Verify `data-api-url` points to a valid endpoint * Check CORS settings on your API * Ensure your API key is valid and not expired * Review browser console for specific error messages * Ensure parent container has defined height * Check for CSS conflicts from your site's stylesheets * Verify `overflow: hidden` on the container * Test in different browsers * The widget uses lazy loading for optimal performance * Initial load may take 1-2 seconds * Subsequent loads are faster due to browser caching * Check your network connection *** ## Comparison: AI Page vs Widget | Feature | AI Page | Widget | | --------------- | -------------------- | ----------------- | | Layout | Full-page immersion | Floating bubble | | Best for | Dedicated help pages | Site-wide support | | Screen usage | 100% viewport | Minimal footprint | | User experience | Focused conversation | Quick assistance | | Installation | Per page | Site-wide | Use both! Install the widget sitewide for quick help, and add the AI Page to your dedicated support page for in-depth conversations. *** ## Next Steps Add content for the AI to reference Customize your chatbot appearance # Best Practices Source: https://docs.bubblav.com/user-guide/best-practices Guide to getting the most out of BubblaV for your customers To ensure your BubblaV chatbot provides the best possible support to your customers, follow these best practices for content management, testing, and continuous improvement. ## 1. Effective Content Crawling The foundation of a smart chatbot is a comprehensive knowledge base. * **Start with a thorough crawl**: When setting up, ensure you crawl your main documentation, help center, and landing pages. * **Verify status**: Check the **Knowledge** tab to ensure all pages are "Indexed". ## 2. Testing in the Design Page Before deploying or after making changes, always use the testing function on the **Design** page. 1. Navigate to your website dashboard and click **Design**. 2. The chat preview on the right side simulates the real user experience. 3. **Ask specific questions**: Ask about pricing, specific features, return policies, or edge cases. 4. **Verify citations**: Check that the bot is citing the correct pages from your site. ## 3. Resolving Content Gaps When you spot an incorrect or suboptimal answer during testing: * Go to the **Knowledge** section -> **Content Gaps**. * BubblaV automatically flags questions that the AI struggled with. * **Add a Q\&A Entry**: You can convert an unanswered question into a precise, hand-crafted Q\&A pair. * This is perfect for "sensitive" questions or brand-specific phrasing that might not be clear in the raw web text. ## 4. Adding Manual Q\&A Sometimes your website doesn't explicitly state the answer to a common question (e.g., "Do you offer a non-profit discount?") or the info is scattered. * Go to **Knowledge** > **Q\&A**. * Add a **Q\&A Entry** (e.g., Question: "Do you offer discounts?", Answer: "Yes, we offer..."). * This fills gaps without needing to create new public web pages. ## 5. Monitoring Content Gaps Your chatbot improves over time if you listen to what users are asking. * **Check Top Unanswered Questions**: Periodically review usage reports to see what questions the bot couldn't answer. * **Identify Gaps**: If users ask about a feature you haven't documented, that's a content gap. * **Action**: * Add a new section to your website and re-crawl. * Or add a manual Q\&A entry in the **Q\&A** tab to address it immediately. By following this loop—**Crawl**, **Test**, **Q\&A**, and **Monitor**—you will build a powerful automated support agent that your customers love. # Billing & Plans Source: https://docs.bubblav.com/user-guide/billing Manage your subscription, billing details, and usage BubblaV offers flexible pricing plans to scale with your business needs. You can manage your subscription, view invoices, and track usage directly from the dashboard. ## Subscription Plans We offer plans to suit different needs: Perfect for testing and personal projects. * **Price**: \$0/month * 1 Website * 50 pages (web + files + text) * 100 messages/month * 100 MCP API calls/month * 7 days retention * Built-in integrations * Human handoff (chatbot → human) * Email to visitors For growing businesses needing advanced features. **Start with a 14-day free trial.** * **Price**: \$49/month (\$39/month annually, save \$120/year) * Everything in Free * 5 Websites * 5,000 pages (web + files + text) per website * 5,000 messages/month * 5,000 MCP API calls/month * 1 year retention * Advanced data sources and reports * Live Chat Dashboard (real-time takeover) * Human handoff scenarios (AI intent-based routing) * Integrations (Zendesk, HubSpot, Attio) and Custom tools * Custom branding (remove "Powered by") * 3 team member seats * Weekly data sync ## Managing Your Subscription To access billing settings: 1. Click your **user avatar** in the top-right corner of the dashboard 2. Select **Subscription** from the menu You can also go directly to [bubblav.com/dashboard/subscription](https://www.bubblav.com/dashboard/subscription). ### Upgrading Your Plan 1. Navigate to the **Subscription** page (via user avatar menu or direct link). 2. Scroll down to the **Available Plans** section. 3. Click **Upgrade** on your desired plan. 4. Follow the checkout prompts to complete the purchase. ### Free Trial The Pro plan includes a 14-day free trial for new customers. You get full access to all Pro features during the trial period. * **Eligibility**: Available to new customers who haven't had a paid subscription before * **Card Required**: Your payment card is required at signup but won't be charged until the trial ends * **Trial Duration**: 14 days from signup * **Automatic Conversion**: After the trial, your subscription automatically converts to a paid Pro plan * **Reminder**: We'll send you a reminder email 2 days before your trial ends * **Cancel Anytime**: If you cancel during the trial, you won't be charged at all To start a free trial, click **Start 14-Day Free Trial** on the Pro plan card in the Subscription page. ### Message Usage & Limits Your plan includes a monthly allowance of AI responses (messages). * **Reset Schedule**: * **Paid Plans**: Usage resets on your monthly billing date (e.g., if you subscribed on the 14th, it resets on the 14th of each month). * **Free Plan**: Usage resets on the 1st of every calendar month. * **Tracking Usage**: The Subscription page shows a real-time progress bar of your message consumption. * **Overages**: If you run out of messages, your chatbot will stop replying until the next cycle or until you purchase an add-on. * **Add-on Packs**: You can buy "Extra Message Packs" (1,000 messages for \$5) that never expire and are used after your monthly allowance is exhausted. ### MCP API Call Quotas MCP API calls are tracked separately from your AI message usage. * **Free**: 100 MCP API calls/month * **Pro**: 5,000 MCP API calls/month * **Reset Schedule**: MCP API usage resets on a rolling 30-day window from your first MCP call in the current cycle. * **Tracking Usage**: You can check current MCP API usage from your website settings in the dashboard. * **When Limit Is Reached**: MCP requests return a rate limit error until the quota resets. ### Data Sync Frequency BubblaV automatically syncs your data to keep your chatbot up-to-date. The frequency depends on your plan: * **Free**: Every 30 days * **Pro**: Every 7 days This ensures your chatbot always has the latest information from your website and connected sources. ## Plan Features ### Free Plan Features The Free plan includes essential features for testing: * Basic AI chatbot functionality * Built-in integrations (no external tools) * Core analytics dashboard * Message & conversation trends * Export report data ### Pro Plan Features The Pro plan unlocks advanced capabilities: The AI automatically detects when it can't help and escalates to a human agent. It collects visitor information, creates a live support session, and generates external support tickets (Zendesk, HubSpot, etc.) for seamless follow-up. Take over conversations in real-time with the Live Chat Dashboard. Monitor active conversations, see what visitors are typing, and jump in instantly when needed. Provides full control to handle complex queries personally. Access detailed analytics including: * Most active times * Conversation flow visualization * Visitor and conversation geography * Top unanswered questions * Bad feedback conversations * Most visited links * Leads captured Connect with external tools: * Zendesk (tickets and knowledge base) * HubSpot (CRM and tickets) * Attio (CRM) * Custom tools * MCP Servers (Model Context Protocol) - Connect to any external API or service Remove the "Powered by BubblaV" branding and fully customize the widget appearance to match your brand. ## Billing Providers We support billing through different providers depending on how you signed up: ### Polar For users who sign up directly on BubblaV (non-Shopify merchants). * **14-day free trial** available on Pro plan for new customers * Invoices emailed automatically * Choose monthly or yearly billing (save 20% with annual) ### Shopify For users who installed BubblaV via the Shopify App Store. * Charges appear on Shopify bill * Upgrades/downgrades via Shopify billing * **Note**: Shopify billing only supports monthly billing cycles * Usage tracking in BubblaV dashboard ## Cancellation You can cancel your subscription at any time by downgrading to the Free plan: 1. Click your **user avatar** in the top-right corner and select **Subscription**, or go to [bubblav.com/dashboard/subscription](https://www.bubblav.com/dashboard/subscription) 2. Click **Downgrade to Free** on your current plan 3. Confirm the downgrade when prompted 4. Your plan will remain active until the end of the current billing period **During Free Trial**: If you cancel during your 14-day free trial, you won't be charged at all and your account will revert to the Free plan immediately. # Forms Source: https://docs.bubblav.com/user-guide/forms Collect structured data from visitors through AI-powered forms Forms let your AI chatbot collect structured data from visitors—like feedback, contact details, or survey responses—directly inside the chat. Instead of redirecting visitors to external pages, the chatbot presents a form when it detects the right intent. ## How It Works 1. You **create a form** with the fields you need 2. You give the AI **instructions** on when to show it 3. When a visitor asks something relevant, the AI **presents the form** in the chat 4. The visitor **fills it out and submits**—you get the data instantly The AI decides when to show a form based on your instructions. Write clear, specific instructions so the AI triggers the form at the right moment. *** ## Creating a Form Go to **Dashboard** → select your website → **Forms** in the sidebar Click the **Create Form** button to open the form builder. * **Name** (required): A clear name like "Product Review Form" or "Contact Request" * **Description**: Brief text shown to visitors above the form * **AI Instructions**: Tell the chatbot *when* to show this form (e.g., "Show when a visitor wants to leave a product review or feedback") Click **Add Field** and configure each field's type, label, placeholder, and whether it's required. See [Field Types](#field-types) below for all options. The live preview on the right shows how your form will look to visitors. Click **Create Form** when you're done. Write specific AI instructions. "Show when visitor asks about pricing or quotes" works better than "Show when needed." *** ## Field Types Forms support 8 field types to cover most data collection needs: | Type | Description | Use For | | ---------------------- | --------------------------------- | ------------------------- | | **Text** | Single-line text input | Names, short answers | | **Email** | Email input with validation | Email addresses | | **Number** | Numeric input | Quantities, ages | | **Long Text** | Multi-line text area | Feedback, descriptions | | **Dropdown** | Select one from a list | Categories, departments | | **Radio Buttons** | Choose one option | Yes/No, ratings, choices | | **Checkbox** | Single toggle (checked/unchecked) | Agreements, confirmations | | **Rating (1-5 Stars)** | Star rating selector | Satisfaction scores | ### Field Configuration Each field has: * **Label** (required): The question or prompt shown to visitors * **Type**: The input type from the list above * **Placeholder**: Hint text inside the field (not available for Checkbox and Rating) * **Required**: Whether the visitor must fill in this field before submitting For **Dropdown** and **Radio Buttons**, you also configure a list of options that the visitor can choose from. ### Reordering Fields Use the up/down arrows on each field to change the order. Fields appear to visitors in the order you set. *** ## AI Instructions AI Instructions tell your chatbot when to display a form. This is the most important part of form configuration—if the instructions are unclear, the AI won't know when to act. ### Writing Good Instructions * "Show when a visitor wants to leave a product review or feedback about their purchase" * "Show when a visitor asks for a quote, pricing information, or wants to discuss custom plans" * "Show when a visitor expresses interest in becoming a partner or reseller" * "Show when a visitor wants to schedule a demo or consultation call" * "Show when needed" (too vague) * "Show form" (no context) * "When customer" (incomplete) You can create multiple forms per website, each with different AI instructions. The AI will pick the right one based on the visitor's message. *** ## Enabling and Disabling Forms Forms are **enabled by default** when created. You can toggle a form on or off from the Forms list page without deleting it. * **On**: The AI can see and show this form to visitors * **Off**: The form is hidden from the AI—visitors won't see it *** ## Viewing Submissions Every form submission is stored and accessible from your dashboard. ### View Submissions for a Form Each form in the Forms list has a **submissions count** badge. Click the form's menu to view its submissions. Each submission shows: * All field values with their labels * Formatted values (e.g., "4/5 stars" for ratings) * Submission date and time * Visitor ID and conversation ID ### Email Notifications By default, you receive an email notification when a visitor submits a form. The email includes: * Form name * Website name * All submitted field values * A link to view the submission in your dashboard *** ## Sample Use Cases ### Product Reviews Collect customer feedback with ratings and detailed reviews. **Name**: Product Review
**AI Instructions**: "Show when a visitor wants to leave a review, feedback, or rate a product" 1. Text — "Product Name" (required)
2. Rating — "Overall Rating" (required)
3. Long Text — "Your Review" (required)
4. Text — "Reviewer Name" *** ### Quote Requests Capture lead information when visitors ask about pricing. **Name**: Request a Quote
**AI Instructions**: "Show when a visitor asks about pricing, quotes, custom plans, or wants to discuss business terms" 1. Text — "Full Name" (required)
2. Email — "Email Address" (required)
3. Text — "Company Name"
4. Dropdown — "Interest" (required): Sales, Support, Partnership, Other
5. Long Text — "Tell us about your needs" (required) *** ### Customer Support Tickets Collect issue details before escalating to your support team. **Name**: Support Ticket
**AI Instructions**: "Show when a visitor has a technical problem, wants to report a bug, or needs help that requires follow-up" 1. Text — "Full Name" (required)
2. Email — "Email Address" (required)
3. Dropdown — "Issue Type" (required): Billing, Technical, Account, Other
4. Text — "Order/Reference Number"
5. Long Text — "Describe the issue" (required) *** ### Event Registration Sign visitors up for webinars or events. **Name**: Event Registration
**AI Instructions**: "Show when a visitor wants to register for an event, webinar, workshop, or demo" 1. Text — "Full Name" (required)
2. Email — "Email Address" (required)
3. Text — "Company"
4. Number — "Number of Attendees"
5. Dropdown — "Session" (required): Morning, Afternoon, Evening *** ### Newsletter Signup Collect email subscriptions directly in chat. **Name**: Newsletter Signup
**AI Instructions**: "Show when a visitor wants to subscribe to the newsletter, get updates, or stay informed" 1. Text — "First Name" (required)
2. Email — "Email Address" (required)
3. Checkbox — "I agree to receive marketing emails" (required) *** ## Editing and Deleting Forms ### Edit a Form Click the pencil icon on any form to modify its name, description, AI instructions, or fields. Changes take effect immediately. ### Delete a Form Click the trash icon and confirm. **Deleting a form permanently removes all its submissions**. This action cannot be undone. Deleting a form also deletes all submissions for that form. Consider exporting important data before deleting. *** ## How Visitors Experience Forms When a visitor interacts with your chatbot and the AI decides a form is relevant: 1. The AI sends a brief message (e.g., "I'd love to get your feedback! Please fill out this quick form:") 2. The form appears inline in the chat with all configured fields 3. The visitor fills in the fields and clicks **Submit** 4. Required fields are validated before submission 5. A success message confirms the submission 6. The conversation continues normally Visitors never leave the chat—the entire experience happens inside the widget. *** ## Best Practices 3-5 fields is ideal. Long forms reduce completion rates. Describe exactly when to show the form. Vague instructions lead to missed triggers. Only mark fields as required if you truly need the data. Optional fields increase completion rates. Use the preview in the form builder and test via the chatbot to verify the experience. *** ## Troubleshooting * Check the form is **enabled** (toggle is On) * Review your **AI Instructions**—make them more specific * Try phrasing your test message differently to match the instructions * Ensure the form has at least one field * Check if multiple forms have overlapping AI instructions * Make each form's instructions distinct and specific to its purpose * Check the **Submissions** page in your dashboard * Verify the form is enabled * Check your email notifications settings *** ## Next Steps Connect your chatbot to external APIs Escalate to live agents Optimize your chatbot setup # Getting Started Source: https://docs.bubblav.com/user-guide/getting-started Start your journey with BubblaV in minutes Welcome to BubblaV! This guide will help you create your account, set up your first chatbot, and get it live on your website in under 10 minutes. ## What You'll Need Before starting, have these ready: * An email address (or Google account) * Your website URL * A few minutes of your time *** ## Step 1: Create an Account Go to [bubblav.com/login](https://www.bubblav.com/login) Pick your preferred option: * **Email**: Enter email and create a password * **Google**: One-click sign up with your Google account If using email, check your inbox and click the verification link You'll be redirected to your dashboard automatically Using Google is fastest—no email verification needed. *** ## Step 2: Choose Your Plan BubblaV offers plans for every business size: | Feature | Free | Pro (\$49/mo) | | -------------------------- | ------ | ---------------------------- | | **Messages/month** | 100 | 5,000 | | **Pages crawled** | 50 | 5,000 | | **Websites** | 1 | 5 | | **Team members** | 1 | 3 | | **Human handoff** | Yes | Yes | | **Email to visitors** | Yes | Yes | | **Live Support** | - | Yes | | **Custom Tools** | Yes | Yes | | **Remove branding** | - | Yes | | **Conversation retention** | 7 days | 1 year | | **Annual billing** | - | \$39/month (save \$120/year) | Start with the **Free** plan to test everything. The **Pro** plan includes a **14-day free trial**—full access during the trial, cancel anytime at no cost. Annual billing saves 20% on all paid plans. ### Upgrading Later 1. Click your **user avatar** in the top-right corner 2. Select **Subscription** from the menu 3. Click **Upgrade Plan** 4. Select your desired plan 5. Enter payment details 6. Your new limits apply immediately *** ## Step 3: Create Your First Website From the dashboard, click **+ New Website** The full URL of your site (e.g., `https://example.com`) Your website is created and ready to configure. We'll automatically fetch your favicon and site name if available. ### What Happens Next After creating your website: 1. **Automatic crawl begins**: BubblaV scans your website to learn about your business 2. **Knowledge base populates**: Content from your pages is indexed 3. **Widget is generated**: A unique embed code is created for you Crawling typically takes 2-5 minutes depending on your website size. You can continue setup while it runs. *** ## Step 4: Setup Wizard The setup wizard guides you through essential configuration: ### Crawl Status Monitor your website crawl: * **In Progress**: Pages are being scanned * **Completed**: All pages indexed successfully * **Errors**: Some pages couldn't be accessed ### Design Preview Quick customization in the **Design** tab: * Choose your **brand colors** * Select a **position** (bottom-right or bottom-left) * Customize **bot identity** (Name, Avatar, Welcome Message) * Preview how it looks in real-time ### Installation Code Get your embed code: ```html theme={null} ``` *** ## Step 5: Test Your Chatbot Before going live, test your chatbot: Click **Design** in the sidebar to open the widget configuration and live preview. Try questions your customers might ask: * "What are your shipping options?" * "How do I contact support?" * "What products do you sell?" Verify the answers are accurate and helpful If answers are wrong, add content to your knowledge base *** ## Quick Start Checklist Track your progress through setup: Sign up and verify your email Create your first website in the dashboard Wait for your website content to be indexed Customize colors and appearance to match your brand Verify responses are accurate in preview mode Add the widget code to your website Confirm the widget appears on your live site *** ## Common First Steps After basic setup, consider these enhancements: ### Improve AI Knowledge Add PDFs, documents with detailed info Add specific answers for common questions ### Customize Experience Match your brand colors and style Set AI tone, language, notifications ### Connect Integrations Connect for order lookups Enable appointment booking See all integrations *** ## Troubleshooting Setup * Check your spam/junk folder * Ensure you entered the correct email * Request a new verification email * Try signing up with Google instead * Large websites take longer (100+ pages) * Check if your site blocks bots (robots.txt) * Try adding pages manually if crawl fails * Refresh the page * Clear browser cache * Check browser console for errors * Ensure JavaScript is enabled * Review what content was crawled * Add missing information via Q\&A entries * Check "Content Gaps" for common unanswered questions *** ## Getting Help Need assistance? Here's how to get help: * **Documentation**: You're already here! Browse the guides. * **Email Support**: Contact [support@bubblav.com](mailto:support@bubblav.com) * **Live Chat**: Chat with our bot on [bubblav.com](https://www.bubblav.com) Pro and Turbo plans include priority support with faster response times. *** ## Next Steps Ready to continue? Here's what to do next: Add the chatbot to your website Add more knowledge for better answers # Human Handoff Scenarios Source: https://docs.bubblav.com/user-guide/human-handoff Configure questions that should always be handled by your team # Human Handoff Scenarios Configure specific questions or intents that should always be handled by human agents. When a visitor's message matches a configured scenario, the bot will automatically collect their information and connect them with your team. ## Feature Overview Human Handoff Scenarios use AI intent matching to intelligently detect when a visitor needs human assistance. Instead of relying on exact keyword matches, you can describe scenarios in natural language and the AI will understand when to trigger a handoff. ## Plan Availability This feature is available on **Pro** plans. ## Setting Up Handoff Scenarios 1. Navigate to **Behavior** > **Human Handoff** in your dashboard 2. Click **Add Scenario** 3. Describe when to handoff in natural language 4. Optionally provide a custom response message 5. Click **Add Scenario** ## Example Scenarios ### Sales Inquiries * "When someone asks about enterprise pricing" * "Custom integration or development requests" * "Partner or reseller inquiries" ### Support Issues * "Technical support requests" * "Billing or account issues" * "Feature requests or custom development" ## How It Works When a visitor sends a message: 1. **Intent Matching**: AI analyzes the message against your configured scenarios 2. **Match Detection**: If a scenario matches, handoff is triggered 3. **Info Collection**: Bot asks for visitor's email and name 4. **Live Support Created**: A live support session is created 5. **Team Notified**: You receive an email notification ## Best Practices ### Be Specific * Good: "When someone asks about enterprise pricing plans" * Poor: "pricing questions" ### Use Natural Language * Good: "Partner or reseller partnership inquiries" * Poor: "partner" ### Review Content Gaps Check the **Knowledge** > **Insights** > **Content Gaps** tab to see what questions visitors ask that the AI struggles with. These may be good candidates for handoff scenarios. # Installation Source: https://docs.bubblav.com/user-guide/installation Add the chatbot widget to your website Install BubblaV on any website in minutes. Choose your platform for step-by-step instructions. Installation Overview

## Using AI Builders (Lovable, v0, Bolt, Cursor) Building with an AI-powered tool? Copy the prompt below and paste it directly into your AI builder to integrate BubblaV automatically. This works with Lovable, v0, Bolt, Cursor, Windsurf, and any other AI coding assistant. ```text expandable theme={null} Add the BubblaV AI chatbot widget to this project. **Option 1: NPM Package (Recommended for React, Vue, Angular)** Install: React: npm install @bubblav/ai-chatbot-react Vue: npm install @bubblav/ai-chatbot-vue Angular: npm install @bubblav/ai-chatbot-angular Import and add to your root component or layout: React — import { BubblaVWidget } from '@bubblav/ai-chatbot-react'; Vue — import { BubblaVWidget } from '@bubblav/ai-chatbot-vue'; Angular (standalone) — import { BubblaVWidgetComponent } from '@bubblav/ai-chatbot-angular'; Add BubblaVWidgetComponent to the component's imports array, then: IMPORTANT — For Vite-based projects (Lovable, Bolt, v0, plain Vite), add this to vite.config.ts to prevent duplicate-React conflicts: resolve: { dedupe: ['react', 'react-dom'] } **Option 2: Script Tag (fallback — works with any framework)** Add this before in your main HTML or layout file: For Next.js (app/layout.tsx or pages/_app.tsx), use next/script instead: import Script from 'next/script'; ``` Your website ID is unique to your account. Never share it publicly, as it identifies your chatbot. *** ## Using NPM Packages For React, Vue, and Angular applications, you can use our official NPM packages for a better developer experience with type safety and framework integration. ### React Package Install the package: ```bash theme={null} npm install @bubblav/ai-chatbot-react # or yarn add @bubblav/ai-chatbot-react # or pnpm add @bubblav/ai-chatbot-react ``` Basic usage: ```jsx theme={null} import { BubblaVWidget } from '@bubblav/ai-chatbot-react'; function App() { return ( ); } ``` With customization: ```jsx theme={null} import { BubblaVWidget } from '@bubblav/ai-chatbot-react'; function App() { return ( ); } ``` The React package is **strict-mode safe** and prevents double initialization. It also provides hooks for programmatic access: ```jsx theme={null} import { useBubblaVWidget } from '@bubblav/ai-chatbot-react'; function SendMessageButton() { const widget = useBubblaVWidget(); const handleClick = () => { widget?.sendMessage('Hello, I need help!'); }; return ; } ``` The React package handles SSR automatically and only loads the widget script in the browser. ### Vue Package Install the package: ```bash theme={null} npm install @bubblav/ai-chatbot-vue # or yarn add @bubblav/ai-chatbot-vue # or pnpm add @bubblav/ai-chatbot-vue ``` Basic usage: ```vue theme={null} ``` With customization: ```vue theme={null} ``` Using composables: ```vue theme={null} ``` The Vue package is SSR-safe and works with Vue 3 Composition API. ### Angular Package Install the package: ```bash theme={null} npm install @bubblav/ai-chatbot-angular # or yarn add @bubblav/ai-chatbot-angular # or pnpm add @bubblav/ai-chatbot-angular ``` Basic usage (standalone component): ```ts theme={null} import { Component } from '@angular/core'; import { BubblaVWidgetComponent } from '@bubblav/ai-chatbot-angular'; @Component({ selector: 'app-root', standalone: true, imports: [BubblaVWidgetComponent], template: ` ` }) export class AppComponent {} ``` With customization: ```html theme={null} ``` Using the service for programmatic access: ```ts theme={null} import { Component, inject } from '@angular/core'; import { BubblaVWidgetService } from '@bubblav/ai-chatbot-angular'; @Component({ selector: 'app-support', template: ` ` }) export class SupportComponent { private bubblav = inject(BubblaVWidgetService); openChat() { this.bubblav.open(); } } ``` The Angular package supports Angular 14+ with standalone components and is SSR-safe. *** ## Platform Instructions Choose your website platform: ### WordPress Installation **Option 1: Using BubblaV WordPress Plugin (Recommended)** Install our official WordPress plugin for the easiest installation: Log in to your WordPress admin and go to **Plugins** → **Add New** Search for "BubblaV Chat" in the WordPress plugin repository Click **Install Now** and then **Activate** Go to **BubblaV Chat** settings and enter your website ID The widget is automatically installed on your WordPress site **Option 2: Manual Installation** Alternatively, use a generic plugin: Go to **Plugins** → **Add New**, search for "Insert Headers and Footers", and install it Click **Activate** after installation Go to **Settings** → **Insert Headers and Footers** Paste your BubblaV embed code in the **Scripts in Footer** section Click **Save** to apply changes ### WooCommerce Installation **Option 1: Using BubblaV WordPress Plugin (Recommended)** Install our official WordPress plugin for seamless WooCommerce integration: Log in to your WordPress admin and go to **Plugins** → **Add New** Search for "BubblaV Chat" in the WordPress plugin repository Click **Install Now** and then **Activate** Go to **BubblaV Chat** settings and enter your website ID The widget is automatically installed on your WooCommerce store The widget will work seamlessly with your WooCommerce store and can be configured to track orders and search products when you connect the WooCommerce integration. **Option 2: Manual Installation** Alternatively, use a generic plugin: Go to **Plugins** → **Add New**, search for "Insert Headers and Footers", and install it Click **Activate** after installation Go to **Settings** → **Insert Headers and Footers** Paste your BubblaV embed code in the **Scripts in Footer** section Click **Save** to apply changes ### BigCommerce Installation **Option 1: Using BubblaV BigCommerce App (Recommended)** Install our official BigCommerce app for automatic installation: Log in to your BigCommerce admin panel and go to **Apps** → **BigCommerce Marketplace** Search for "BubblaV" in the marketplace Click **Install** and follow the setup wizard Connect your BubblaV account during setup The widget is automatically installed on your store **Option 2: Manual Installation (Legacy)** Use BigCommerce's Script Manager to add the widget: Log in to your BigCommerce admin panel Go to **Storefront** → **Script Manager** Click **Create a Script** Set these options: * **Name**: BubblaV Widget * **Location**: Footer * **Pages**: All Pages * **Script category**: Script * **Script content**: Paste your embed code Click **Save** to apply changes ### Shopify Installation **Option 1: Using BubblaV Shopify App (Recommended)** 1. Install the BubblaV app from the Shopify App Store 2. Connect your BubblaV account during setup 3. The widget will be automatically installed on your store 4. Configure the widget appearance from your Shopify admin or this dashboard **Option 2: Manual Installation (Legacy)** Go to **Online Store** → **Themes** Click the **...** menu on your active theme, then **Edit code** In the Layout section, click on `theme.liquid` Scroll to find the closing `` tag Paste your embed code just before `` Click **Save** in the top right If you're using a Shopify 2.0 theme, you can also add the code via **Online Store** → **Themes** → **Customize** → **Theme settings** → **Custom code**. ### Haravan Installation Haravan uses Liquid templating similar to Shopify. Add the widget through the theme code editor. Go to your Haravan admin at `your-store.myharavan.com`, then navigate to **Website** → **Giao diện** (Theme) Click on your active theme, then select **Chỉnh sửa code** (Edit code) In the **Layouts** folder on the left sidebar, click on `theme.liquid` Scroll to the bottom of the file to find the closing `` tag (usually around line 142) Paste your BubblaV embed code just before ``: ```html theme={null} ``` Click **Save** to apply changes Haravan's theme structure is very similar to Shopify. The `theme.liquid` file in the Layouts folder is the main template that wraps all pages, making it the ideal location for the widget script. If you prefer, you can also add the script to the `footer-scripts.liquid` snippet (found in the **Snippets** folder) if your theme uses it. However, `theme.liquid` is recommended as it ensures the widget loads on all pages. ### Wix Installation In your Wix dashboard, go to **Settings** Click **Custom Code** (under Advanced) Click **+ Add Custom Code** Paste your BubblaV embed code Set these options: * **Name**: BubblaV Chat * **Add to**: All pages * **Place code in**: Body - end Click **Apply** Custom code requires Wix Premium. Free Wix sites cannot add custom scripts. ### Squarespace Installation Go to **Settings** → **Advanced** → **Code Injection** Scroll to the **Footer** section Paste your BubblaV embed code Click **Save** Code Injection requires a Squarespace Business plan or higher. ### Webflow Installation **Option 1: Using the BubblaV Webflow App (Recommended)** In Webflow, go to Apps and search for "BubblaV", or open the app page directly Click Install to add the app to your project Click Login & Select Website to sign in and choose your website Publish your site and the chatbot appears automatically The app handles OAuth login, website selection, and widget injection automatically — no code required. No need to copy-paste embed codes! **Option 2: Manual Installation (Site-wide)** Click the gear icon in the left panel Go to the **Custom Code** tab Paste your embed code in the **Footer Code** section Save changes and publish your site **Option 3: Specific Pages Only (Manual)** 1. Open the page in the Designer 2. Go to **Page Settings** (gear icon) 3. Scroll to **Custom Code** → **Before `` tag** 4. Paste your embed code 5. Save and publish ### Framer Installation **Option 1: Using BubblaV Framer Plugin (Recommended)** In Framer, go to Plugins → Store and search for "BubblaV" Click Install to add the plugin to your project Click Login & Select Website to sign in and choose your website Adjust widget appearance in the plugin panel (optional) Publish your site and the chatbot appears automatically The plugin automatically creates the component in your code and adds it to your canvas with pre-configured settings. No need to copy-paste codes! **Option 2: Manual Installation** Open your Framer project and go to Site Settings Click on the General tab Scroll down to the End of \ tag section Paste your BubblaV embed code Click Save and then Publish your site ### Google Tag Manager Installation Google Tag Manager (GTM) is one of the most popular ways to add the BubblaV widget without editing your website code. It works on virtually any website and is our recommended method when your platform doesn't have a dedicated app. Log in to [Google Tag Manager](https://tagmanager.google.com) and select your container (or create a new one) Go to **Tags** in the left sidebar, then click **New** Click on **Tag Configuration**, then choose **Custom HTML** as the tag type Paste your BubblaV embed code in the HTML field: ```html theme={null} ``` Click on **Triggering** and select **All Pages** so the widget loads on every page Name the tag **"BubblaV Chat Widget"** and click **Save** Click **Submit** in the top-right corner, then click **Publish** to make the tag live on your site After publishing, it may take a few minutes for changes to propagate. Open your site in an incognito window to verify the widget appears. Make sure the GTM container snippet is installed on your website. If you haven't set up GTM yet, follow Google's [installation guide](https://developers.google.com/tag-platform/tag-manager/web) first. For the full step-by-step guide with troubleshooting, see [Google Tag Manager](/user-guide/integrations/google-tag-manager). ### Joomla Installation **Option 1: Using a Plugin (Recommended)** Install a "Custom HTML" or "Insert HTML" extension from the Joomla Extensions Directory Go to **Extensions** → **Plugins** and configure the plugin Paste your BubblaV embed code in the footer section Save and apply changes **Option 2: Editing Template Files** 1. Go to **Extensions** → **Templates** → **Templates** 2. Select your active template 3. Open `index.php` or `footer.php` 4. Paste the embed code before `` 5. Save & Close ### Drupal Installation **Option 1: Using a Module (Recommended)** Install the "Add to Head" or similar module Go to **Configuration** → **Add to Head** Add your BubblaV embed code to the footer section Save configuration **Option 2: Editing Theme** 1. Go to **Appearance** → **Themes** 2. Edit your active theme 3. Open `html.html.twig` or your template file 4. Paste the embed code before `` *** ## Developer Platforms For custom or developer-built websites: ### Static HTML Add the script tag before the closing `` tag: ```html theme={null} My Website ``` ### React / Create React App Add to your `public/index.html`: ```html theme={null} ``` Or use a component approach: ```jsx theme={null} // components/BubblaVWidget.jsx import { useEffect } from 'react'; export default function BubblaVWidget() { useEffect(() => { const script = document.createElement('script'); script.src = 'https://www.bubblav.com/widget.js'; script.async = true; script.dataset.websiteId = 'YOUR_WEBSITE_ID'; document.body.appendChild(script); return () => { document.body.removeChild(script); }; }, []); return null; } ``` Then add to your App: ```jsx theme={null} import BubblaVWidget from './components/BubblaVWidget'; function App() { return ( <> {/* Your app content */} ); } ``` ### Next.js **Option 1: Using next/script (Recommended)** ```jsx theme={null} // app/layout.tsx or pages/_app.tsx import Script from 'next/script'; export default function RootLayout({ children }) { return ( {children} ``` Or create a component: ```vue theme={null} ``` ### Angular **Option 1: Edit src/index.html (Recommended)** ```html theme={null} ``` **Option 2: Using Component** ```typescript theme={null} // src/app/bubblav-widget/bubblav-widget.component.ts import { Component, OnInit, OnDestroy } from '@angular/core'; @Component({ selector: 'app-bubblav-widget', template: '' }) export class BubblaVWidgetComponent implements OnInit, OnDestroy { private scriptElement: HTMLScriptElement | null = null; ngOnInit() { this.scriptElement = document.createElement('script'); this.scriptElement.src = 'https://www.bubblav.com/widget.js'; this.scriptElement.async = true; this.scriptElement.setAttribute('data-site-id', 'YOUR_WEBSITE_ID'); document.body.appendChild(this.scriptElement); } ngOnDestroy() { if (this.scriptElement) { document.body.removeChild(this.scriptElement); } } } ``` ### Svelte **Option 1: Edit src/app.html (SvelteKit)** ```html theme={null} ``` **Option 2: Create a Component** ```svelte theme={null} ``` ### Astro **Option 1: Using Inline Script (Recommended)** Add the script directly to your main layout file (e.g., `src/layouts/Layout.astro`): ```astro theme={null} --- // Layout.astro --- Your Site ``` **Option 2: Using Client-Side Script** For more control over when the script loads: ```astro theme={null} --- // In your layout or page --- ``` Use `is:inline` to ensure the script runs on the client side without Astro's bundling. *** ## Advanced Options ### Script Attributes Customize widget behavior with data attributes: | Attribute | Values | Description | | -------------- | ------- | --------------------------------- | | `data-site-id` | Your ID | Required. Identifies your chatbot | ### Excluding Pages To hide the widget on specific pages, use the **Exclude URLs** setting in your Widget Design settings: 1. Go to **Design** in the sidebar 2. Expand the **Advanced Settings** section 3. Enter the URLs where you want to hide the widget (one per line) 4. You can use specific paths like `https://example.com/checkout` or `https://example.com/admin` The widget will automatically be hidden on those pages without requiring any code changes. *** ## Verify Installation After adding the code, verify it's working: Clear your browser cache or open an incognito window Go to your website in a new tab The chat bubble should appear in the corner (usually bottom-right) Click the bubble and send a test message like "Hello" You should receive a response from your AI assistant If the widget doesn't appear immediately, wait 1-2 minutes for caching to clear, then try again. *** ## Troubleshooting **Check these common issues:** * Code is placed before ``, not in `` * Website ID is correct (copy from dashboard) * Your domain matches the one in your BubblaV settings * JavaScript is enabled in your browser * No browser extensions blocking scripts **Debug steps:** 1. Open browser DevTools (F12) 2. Check Console for errors 3. Check Network tab for widget.js loading * Check your message limits (may be exceeded) * Verify crawl completed successfully * Ensure knowledge base has content * Check browser console for API errors * Adjust z-index in Widget Design settings * Check for CSS conflicts with `.bubblav-widget` class * Try different position (left vs right) * The `async` attribute ensures non-blocking load * Widget loads after main content (intentional) * Check if your site has slow third-party scripts * Verify mobile isn't disabled in settings * Check responsive CSS isn't hiding it * Test on actual mobile device, not just DevTools * Ensure your domain matches BubblaV settings * Check for Content Security Policy restrictions * Verify HTTPS is used on your site *** ## Content Security Policy (CSP) If your site uses CSP headers, add these directives: ``` script-src 'self' https://www.bubblav.com; frame-src 'self' https://www.bubblav.com; ``` *** ## Multiple Websites If you have multiple websites: 1. Each website needs its own embed code 2. Use the unique `data-site-id` for each site 3. Install the appropriate code on each website Using the wrong website ID will cause the widget to load with incorrect knowledge and settings. *** ## Next Steps Customize colors and appearance Verify everything works correctly # Acuity Scheduling Source: https://docs.bubblav.com/user-guide/integrations/acuity Connect Acuity Scheduling to book, reschedule, and cancel appointments through your chatbot Connect your Acuity Scheduling account so visitors can book, reschedule, and cancel appointments through your chatbot — with an inline calendar right inside the conversation. Every booking is captured as a lead in BubblaV. BubblaV connects to Acuity with secure OAuth — no API keys for you to manage. ## Why Connect Acuity Scheduling? * **Book in chat**: Visitors pick a time from an inline Acuity calendar without leaving the conversation * **Capture leads**: Every booking is saved as a lead with attendee details * **Real-time availability**: Show open slots straight from your Acuity calendar * **Cancel & reschedule**: Visitors manage their own upcoming appointments from the chat * **24/7 scheduling**: Take bookings outside business hours ## Prerequisites * An active Acuity Scheduling account * At least one appointment type set up in Acuity * Your BubblaV admin has registered an Acuity OAuth client (one-time, see below) ## Connect to Acuity Scheduling Go to **Dashboard** → select your website → **Integrations** → find **Acuity Scheduling** Click the **Connect** button next to Acuity Scheduling You'll be redirected to Acuity. Log in (if needed) and click **Authorize** to grant BubblaV access using secure OAuth 2.0. You'll be redirected back automatically and the integration will show as **Connected** with your Acuity account details. ## Available Tools Once connected, the chatbot can use these Acuity tools: | Tool | What it does | | ------------------------------- | ---------------------------------------------------------------------------------- | | `acuity_book_appointment` | Show your Acuity appointment types with an inline calendar so the visitor can book | | `acuity_find_appointments` | Look up a visitor's upcoming Acuity appointments | | `acuity_cancel_appointment` | Show appointments with Cancel buttons so the visitor can cancel | | `acuity_reschedule_appointment` | Show appointments with Reschedule buttons so the visitor can pick a new time | Try queries like: * "I'd like to book a consultation" * "Show my upcoming appointments" * "I need to cancel my meeting" * "Can I reschedule my appointment?" ## How the Inline Calendar Works When a visitor asks to book, the bot calls `acuity_book_appointment`, which lists your public Acuity appointment types. The visitor picks one and an **inline Acuity calendar** renders inside the chat so they can choose a date and time and confirm — all without leaving your website. Their name and email are pre-filled when available. Acuity does not send a "booking complete" signal back to the widget. After booking inside the calendar, the visitor taps **I've scheduled my appointment** to confirm, and the bot records the lead. The Acuity confirmation page is also visible inside the calendar. ## Reconnecting If your connection is ever revoked or you need to switch accounts, click **Reconnect** on the Acuity Scheduling integration card. You'll go through the OAuth flow again to get fresh credentials. ## Troubleshooting * Make sure you clicked **Authorize** (not Deny) on Acuity's authorization page. * Try disconnecting and reconnecting via the integration card. * Ensure you're logged into the correct Acuity account. * Create at least one appointment type in Acuity and make sure it isn't private. * Acuity tokens are long-lived until revoked. If calls fail with an authorization error, click **Reconnect** on the integration card. # Attio Source: https://docs.bubblav.com/user-guide/integrations/attio Sync chat contacts and transcripts to your next-gen CRM Seamlessly integrate BubblaV with Attio to keep your CRM data in perfect sync with your customer conversations. > **Note**: The Attio integration requires a **Pro+ plan** or higher.

## Features * **Automatic Contact Sync**: Automatically creates or updates "Person" records in Attio when a visitor provides their email. * **Lead Capture**: Leads from newsletter signups and contact forms are instantly synced to Attio with UTM parameters and source tracking. * **Transcript Logging**: Chat transcripts are automatically saved as "Notes" on the Person record when conversations are resolved. * **Copilot CRM Tools**: AI Copilot can search contacts, fetch profiles, and sync data to Attio in real-time during conversations. * **Agent Workspace Actions**: Human agents can manually search contacts, fetch profiles, and sync visitor information from the dashboard. * **Visitor Insights**: View Attio profile links and details directly within the BubblaV dashboard when chatting with a visitor. * **Configurable Sync**: Toggle contact syncing and transcript logging independently based on your workflow needs. ## Setup Guide There are two ways to connect BubblaV to your Attio workspace: ### Option 1: From BubblaV Dashboard Navigate to the **Integrations** tab in your BubblaV dashboard. Find the **Attio** card and click the **Connect** button. You will be redirected to the BubblaV app in the Attio Marketplace. In the Attio Marketplace, click **Install** or **Connect**. Follow the prompts to authorize the connection. ### Option 2: From Attio Marketplace Search for **BubblaV** in the [Attio Marketplace](https://attio.com/apps/bubbla-v). Click **Install**. You will be redirected to BubblaV to log in (if you aren't already) and select which website you want to connect. Once back in Attio, click **Allow** to grant BubblaV permission to read and write records. ## Configuration Once connected, you can configure the integration from the dashboard: * **Sync contacts**: Automatically capture and update people in Attio from chat sessions. * If the email exists in Attio, we update the Person. * If it's new, we create a Person. * **Log chat transcripts**: Attach full conversation history as Notes to contact records when conversations are resolved. * **Reconnect**: If you connected via the legacy flow, click "Reconnect" to enable full API authorization for all features. ## Copilot Tools When Attio is connected, AI Copilot gains access to powerful CRM tools that agents can invoke during conversations: ### `attio_search_contact` Search for contacts in Attio by name or email address. Returns a list of matching contacts with their names, emails, and profile URLs. ### `attio_fetch_contact` Fetch detailed information about a specific contact from Attio. Provide either an email address or a record ID to retrieve the full profile including: * Name and email * Job title * Company name and domain * Phone number * Custom attributes * Direct link to Attio profile ### `attio_sync_contact` Manually sync a visitor's contact information to Attio. Creates a new Person or updates an existing one with the provided email and name. These tools are available to human agents through the Copilot interface, allowing real-time CRM data access without leaving the conversation. ## Agent Workspace Tools Human agents also have direct access to Attio tools from the dashboard sidebar. These tools work independently of the AI and can be used to: * Search for existing contacts by email * Fetch detailed contact profiles * Manually sync visitor information to Attio ## How it Works ### Lead Capture When a visitor fills out a newsletter signup form or contact form on your website, BubblaV automatically captures the lead and syncs it to Attio: * **Person Record**: Creates or updates a Person record with email and name * **UTM Parameters**: Captures source tracking data (utm\_source, utm\_medium, utm\_campaign, utm\_term, utm\_content) * **Additional Info**: Includes company, job title, phone, and website if provided This happens automatically in the background as soon as the form is submitted. ### Contact Syncing When a user starts a chat and provides an email (either via the pre-chat form or during conversation), BubblaV searches your Attio workspace for a Person with that email. * **Match Found**: We link the chat session to that Person. * **No Match**: We create a new Person record with the `email_addresses` and `name` attributes. This can happen automatically (if "Sync contacts" is enabled) or manually via Copilot tools. ### Chat Transcripts When a conversation is resolved, the full transcript is posted as a **Note** to the Person record in Attio (if "Log chat transcripts" is enabled). The transcript includes: * Timestamp for each message * Sender identification (Visitor, Bot, or Agent name) * Full message content This allows your team to see the full context of the interaction directly in the CRM.

### Visitor Insights When a support agent views a visitor in the BubblaV dashboard, we look up that email in Attio. If a match is found, we display: * A link to their Attio profile * Key contact details like name and company * Option to sync the contact if not already in Attio

### Real-Time CRM Access Agents can use Copilot tools or workspace actions to: * Search for contacts without leaving the chat * Fetch complete profile information on demand * Sync new or updated contact information instantly # BigCommerce Source: https://docs.bubblav.com/user-guide/integrations/bigcommerce Connect your BigCommerce store for order tracking and product search Transform your chatbot into a powerful e-commerce assistant for your BigCommerce store. Customers can track orders, search products, and get instant answers about your store. ## Why Connect BigCommerce? Customers check order status using order numbers Interactive product discovery with filters and pricing Support agents see order history and customer value in real-time Reduce support workload with accurate, instant info ## Visitor Insights for Support Agents The BigCommerce integration enriches the **Visitor Insight** panel in your BubblaV dashboard, providing support agents with critical customer context during live chats: * **Order History**: A detailed list of current and past orders with fulfillment and payment status * **Order Tracking**: Real-time tracking information including carrier, tracking numbers, and delivery status * **Product Details**: View exactly which products were ordered, including images and itemized prices * **Admin Access**: Direct links to view orders in your BigCommerce admin for quick management * **Refunds & Returns**: View refunded amounts and the status of any active return requests ## Prerequisites * Active BigCommerce store * Store URL (e.g., `https://yourstore.com` or `yourstore.mybigcommerce.com`) * BigCommerce API credentials (Access Token and Store Hash) * Administrator access to your BigCommerce dashboard ## Setup Steps Go to **Dashboard** → **Integrations** and find the BigCommerce card Click **Connect BigCommerce** to open the connection form Your Store Hash is part of your BigCommerce store URL:

If your store URL is [https://store-abc123.mybigcommerce.com](https://store-abc123.mybigcommerce.com), your store hash is store-abc123
You can also find it in your BigCommerce admin under Advanced Settings → API Accounts

Create API credentials in your BigCommerce admin:

Go to Advanced Settings → API Accounts
Click Create API Account
Enter a name (e.g., "BubblaV Integration")
Set the OAuth Scopes to include:
- Products: Read Only
- Orders: Read Only
- Customers: Read Only
Click Save
Copy the Access Token (shown only once)

Enter your Store URL, Store Hash, and Access Token in the connection form Click Connect. The BigCommerce card should now show **Connected** ## Available Tools After Connection | Tool | What It Does | Example Query | | ----------------------------- | ------------------------- | ----------------------------------------------------------- | | `bigcommerce_track_order` | Track orders by number/ID | "Track order #1001" | | `bigcommerce_search_products` | Search product catalog | "Show running shoes under \$50" | | `bigcommerce_get_product` | Get product details | "Tell me about this product" | | `bigcommerce_customer_orders` | Customer order history | "My orders for [john@example.com](mailto:john@example.com)" | ## Test Your Integration Try these queries on your website: * "Track order #1001" (use a real order number) * "Show me your products" * "What running shoes do you have?" * "Check my order status" ## Troubleshooting

Verify that the Access Token is correct and not expired
Ensure the API account has the correct OAuth scopes
Check that you copied the entire Access Token

Verify your Store URL and Store Hash are correct
Check that your store is accessible
Ensure your API account is active

Your Store Hash is the subdomain part of your BigCommerce URL
For [https://store-abc123.mybigcommerce.com](https://store-abc123.mybigcommerce.com), the hash is store-abc123
If using a custom domain, find the hash in Advanced Settings → API Accounts

Wait a few minutes for activation
Verify your store has orders and products
Check that the API account still has valid permissions

**Security**: We use OAuth 2.0 authentication with HTTPS. Your credentials are encrypted and stored securely. We only request read permissions to access your store data. **Important**: Save your Access Token securely when you create it. BigCommerce only shows it once and you'll need to regenerate it if lost. # Cal.com Source: https://docs.bubblav.com/user-guide/integrations/calcom Connect Cal.com to book meetings through your chatbot and capture bookings as leads Connect your Cal.com account so visitors can book meetings through your chatbot, and every booking can be captured as a lead in BubblaV. BubblaV connects to Cal.com with secure OAuth — no API keys for you to manage. Connection, in-chat booking, finding upcoming bookings, and automatic booking-to-lead capture are live today. Visitors can also reschedule or cancel from the chat — the bot lists their upcoming Cal.com meetings with **Reschedule** and **Cancel** buttons that open Cal.com's manage page. ## Why Connect Cal.com? * **Book in chat**: Visitors book meetings without leaving the conversation * **Capture leads**: Every booking is saved as a lead with attendee details * **Real-time availability**: Show open slots straight from your Cal.com calendar * **24/7 scheduling**: Take bookings outside business hours * **Cal.com or Cal.eu**: Works with both the global (Cal.com) and European (Cal.eu) instances — choose your region when connecting ## Prerequisites * An active Cal.com account on **Cal.com** (`app.cal.com`) or **Cal.eu** (`app.cal.eu`) * At least one event type set up in Cal.com ## Connect to Cal.com Go to **Dashboard** → select your website → **Integrations** → find **Cal.com** Click the **Connect** button next to Cal.com Select the instance your Cal.com account is on: **Global (Cal.com)** for `app.cal.com` accounts, or **Europe (Cal.eu)** for `app.cal.eu` accounts. Each connection remembers the region you pick. You'll be redirected to Cal.com. Log in (if needed) and click **Allow** to grant BubblaV access. BubblaV uses PKCE OAuth, so there's no client secret to handle. You'll be redirected back automatically and the integration will show as **Connected** with your Cal.com account details. ## What This Enables Once connected, BubblaV is authorized to access your Cal.com account with these scopes: | Scope | What it allows | | ----------------- | ------------------------------------------------------------- | | `BOOKING_READ` | View your bookings (capture as leads, show "my appointments") | | `BOOKING_WRITE` | Create, cancel, and reschedule bookings | | `EVENT_TYPE_READ` | List your event types (show available meetings to book) | | `PROFILE_READ` | Verify the connected account | Ask the bot things like "I'd like to schedule a consultation" (it shows your bookable meeting types), "show my upcoming meetings" (it lists your bookings), or "I need to reschedule" / "cancel my appointment" (it shows Reschedule/Cancel buttons that open Cal.com's manage page so the visitor can pick a new time or cancel). ## Reconnecting If your connection expires or you need to switch accounts, click **Reconnect** on the Cal.com integration card. You'll go through the OAuth flow again to get fresh credentials. Reconnect reuses the region you originally chose — to switch regions, disconnect and connect again, picking the other region. ## Troubleshooting * Pick the region that matches your Cal.com account when connecting: **Global** for `app.cal.com` accounts, **Europe** for `app.cal.eu` accounts. * If bookings aren't working after connecting, disconnect and connect again, selecting the correct region. * Make sure you clicked **Allow** (not Deny) on Cal.com's authorization page. * Try disconnecting and reconnecting via the integration card. * Ensure you're logged into the correct Cal.com account. * This usually means a temporary mismatch in the connection URL. Try connecting again; if it persists, contact support. * While BubblaV's Cal.com OAuth client is pending Cal.com admin review, only the client owner can authorize. Other users can connect once it's approved. * Access tokens refresh automatically in the background. * If you see a connection error, click **Reconnect** on the integration card. # Calendly Source: https://docs.bubblav.com/user-guide/integrations/calendly Enable 24/7 appointment scheduling Enable 24/7 appointment scheduling. Your chatbot helps visitors book meetings, check availability, and manage appointments — all without leaving the chat. ## Why Connect Calendly? * **Instant Booking**: Visitors get booking links without leaving chat * **Real-time Availability**: Show open time slots immediately * **24/7 Scheduling**: Book appointments outside business hours * **Reduced Friction**: Streamlined booking improves conversion ## Prerequisites * An active Calendly account (Free or paid) * At least one event type set up in Calendly ## Connect to Calendly Go to **Dashboard** → select your website → **Integrations** → find **Calendly** Click the **Connect** button next to Calendly You'll be redirected to Calendly's authorization page. Log in if needed, then click **Allow** to grant BubblaV access You'll be redirected back automatically. You'll see your Calendly account name and the number of event types found

## Available Tools After Connection | Tool | What It Does | Example Query | | ------------------------------- | ------------------------------------------------------------- | ------------------------------------- | | `calendly_book_appointment` | Shows booking links for all event types | "I want to schedule a consultation" | | `calendly_find_events_by_email` | Lists upcoming appointments for an email | "Show my scheduled meetings" | | `calendly_cancel_event` | Cancels an appointment (visitor clicks Cancel button) | "I need to cancel my meeting" | | `calendly_reschedule_event` | Reschedules an appointment (visitor clicks Reschedule button) | "Can I move my meeting to next week?" | ## Test Your Integration Try these queries: * "I'd like to schedule a meeting" * "When are you available this week?" * "Can I book a consultation?" * "I need to cancel my appointment" ## Reconnecting If your Calendly connection expires or you need to switch accounts, click **Reconnect** on the Calendly integration card. You'll go through the OAuth flow again to get fresh credentials. ## Troubleshooting * Make sure you clicked **Allow** (not Deny) on Calendly's authorization page * Try disconnecting and reconnecting via the integration card * Ensure you're logged into the correct Calendly account * Create at least one event type in Calendly * Ensure event types are set to **On** (active) in your Calendly settings * Verify event types are published in Calendly * Check your calendar is connected to Calendly * OAuth tokens refresh automatically in the background * If you see a connection error, click **Reconnect** on the integration card # Custom Tools Source: https://docs.bubblav.com/user-guide/integrations/custom-tools Connect your chatbot to any API or backend system Custom tools extend your chatbot's capabilities by connecting it to your own APIs. Unlike built-in integrations, custom tools give you complete flexibility to integrate with any system—your CRM, inventory, pricing engine, or any external service. ## What Are Custom Tools? A custom tool is a function that your chatbot can call to perform actions or retrieve data. You define: 1. **What** it does (description for the AI) 2. **What parameters** it needs (argument schema) 3. **Where** to send requests (your API endpoint) 4. **How** to authenticate (API key, Bearer token, or HMAC) When a customer asks something relevant, the AI automatically calls your tool and uses the response. ## Common Use Cases Check order status from your backend Real-time product availability Retrieve customer info from CRM Custom pricing based on quantity/customer type *** ## Step-by-Step Guide: Building a Weather Tool In this guide, we'll build a **Weather Checker** tool that allows your chatbot to answer questions about the weather in any city. We'll use the free [OpenWeatherMap API](https://openweathermap.org/api). ### Prerequisites 1. Sign up at [OpenWeatherMap](https://openweathermap.org/api) to get a free API key. Go to **Dashboard** → **Integrations** → **Custom Tools** → **Create Tool** Custom Tools Overview

Fill in the following fields: **Tool Name**: `get_weather` * Must be unique, lowercase, and use underscores. **Display Name**: `Weather Checker` * A human-readable name for your internal dashboard. **Description for AI**: "Get current weather information for a location. Use when customer asks about weather, temperature, or conditions in a specific city or location." * *Tip:* Be specific about *when* the AI should use this tool. Step 1: Configure Tool Details

The argument schema tells the AI what variables it needs to extract from the user's message (like the city name). Paste this JSON schema: ```json theme={null} { "q": { "type": "string", "description": "City name or location to search (e.g., 'New York', 'London', 'Tokyo')", "required": true }, "appid": { "type": "string", "description": "OpenWeatherMap API key", "required": false, "default": "YOUR_OPENWEATHER_API_KEY" } } ``` *Replace `YOUR_OPENWEATHER_API_KEY` with the key you got from step 1.* Step 2: Define Arguments

Now map the schema arguments to the API endpoint's parameters. 1. **City Parameter:** * Name: `q` * Method: `Query` (URL parameter) * Source: `q` (from schema) 2. **API Key:** * Name: `appid` * Method: `Query` * Source: `appid` (from schema) 3. **Units (Static Value):** * You can literally type `metric` as a default value if your schema allows it, or just handle it in the URL if the API supports it. For this example, we'll stick to the two dynamic parameters above. Step 2: Add Parameters

Enter the OpenWeatherMap API URL: `https://api.openweathermap.org/data/2.5/weather` * **HTTP Method**: GET Step 3: Configure Endpoint

Since we are passing the API key as a query parameter (`appid`), choose **None** for the Authentication Method in this specific case. *For your own secure APIs, checking [Authentication Methods](#authentication-methods) below is recommended.* 1. Click **Create Tool**. 2. Click the **Test** button on your new tool. 3. Enter `London` for the `q` parameter. 4. Click **Run Test**. You should see a successful response with temperature and weather data! *** ## Product Cards Display When your tool returns product or item data—such as a product search, catalog lookup, or inventory check—you can enable **Product Cards** to display results as a rich visual UI instead of plain text. ### How It Works When enabled, BubblaV automatically extracts product information from your API response (whether it returns JSON, HTML, or any other format) and renders each item as an interactive card with image, name, price, and a link to the product page. No manual field mapping is required. Customers can: * Browse results as cards directly in the chat * Tap a card to see a full product detail view with image gallery * Click **View Product** to open the product page ### Enabling Product Cards 1. Open your custom tool (create new or edit existing). 2. Navigate to the **Test & Configure** step. 3. Toggle **Show as Product Cards** on. 4. Click **Create Tool** or **Update Tool**. The toggle is in the **Response Display** section at the bottom of the Test & Configure step. ### What Gets Extracted The AI reads your API response and extracts the following fields wherever it finds them: | Field | Description | | ------------- | ------------------------------------------------------------ | | `name` | Product title | | `image` | Product image URL (relative URLs are resolved automatically) | | `price` | Price as a string (e.g. `"89,000₫"` or `"$24.99"`) | | `url` | Link to the product page | | `description` | Short description or excerpt | Relative image and product URLs (e.g. `/products/my-product`) are automatically resolved to full URLs using your tool's endpoint domain—no extra configuration needed. ### AI Response Behaviour When product cards are enabled, the chatbot briefly acknowledges the search results in one sentence rather than repeating the products as a text list. The visual cards serve as the primary response. *** When you secure your custom tool, you share a secret key between BubblaV and your API. 1. **In Dashboard**: You enter or auto-generate a **Secret Key** (e.g., `my-secret-token-123`). 2. **In Your Backend**: You adhere to the environment variable `BUBBLAV_SECRET_KEY` with that *exact same value*. 3. **The Check**: When BubblaV calls your API, your backend checks if the incoming request was signed/authorized with that same key. ### None (No Authentication) Simplest setup—no auth headers sent. Only use for internal testing or truly public APIs. Anyone with your URL can call your endpoint. ### Bearer Token BubblaV sends your secret in the `Authorization` header: ```http theme={null} POST /api/your-endpoint Authorization: Bearer your-secret-key-here Content-Type: application/json ``` In the examples below, `process.env.BUBBLAV_SECRET_KEY` represents the secret key you configured in the BubblaV Dashboard for this tool. You must add this key to your backend's environment variables. **Validate in your API:** ```javascript theme={null} app.post('/api/order-status', (req, res) => { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('Bearer ')) { return res.status(401).json({ success: false, error: 'Missing authorization' }); } const token = authHeader.split(' ')[1]; if (token !== process.env.BUBBLAV_SECRET_KEY) { return res.status(401).json({ success: false, error: 'Invalid token' }); } // Process request... }); ``` ```python theme={null} from flask import Flask, request, jsonify import os app = Flask(__name__) @app.route('/api/order-status', methods=['POST']) def order_status(): auth_header = request.headers.get('Authorization') # Check for Bearer token if not auth_header or not auth_header.startswith('Bearer '): return jsonify({ 'success': False, 'error': 'Missing authorization' }), 401 token = auth_header.split(' ')[1] # Verify against your environment variable if token != os.environ.get('BUBBLAV_SECRET_KEY'): return jsonify({ 'success': False, 'error': 'Invalid token' }), 401 # Process request... return jsonify({ 'success': True, 'data': { 'status': 'shipped' } }) ``` ### HMAC Signature (Recommended) Most secure option using cryptographic signatures. Prevents replay attacks and ensures request authenticity. **Headers sent:** ```http theme={null} POST /api/your-endpoint Content-Type: application/json X-BubblaV-Signature: sha256=abc123def456... X-BubblaV-Timestamp: 1703123456789 ``` In these examples, `process.env.SECRET` refers to the **HMAC Secret Key** you generated in the dashboard. Ensure this environment variable matches the key in your tool configuration. **Validate in your API:** ```javascript theme={null} const crypto = require('crypto'); function verifySignature(body, signature, secret, timestamp) { const payload = `${timestamp}.${JSON.stringify(body)}`; const expected = crypto .createHmac('sha256', secret) .update(payload, 'utf8') .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex') ); } app.post('/api/secure-endpoint', (req, res) => { const signature = req.headers['x-bubblav-signature']?.replace('sha256=', ''); const timestamp = req.headers['x-bubblav-timestamp']; // Check timestamp (5 min tolerance) const now = Math.floor(Date.now() / 1000); if (now - parseInt(timestamp) / 1000 > 300) { return res.status(401).json({ success: false, error: 'Request expired' }); } if (!verifySignature(req.body, signature, process.env.SECRET, timestamp)) { return res.status(401).json({ success: false, error: 'Invalid signature' }); } // Process authenticated request... }); ``` ```python theme={null} import hmac import hashlib import time import json import os from flask import Flask, request, jsonify app = Flask(__name__) def verify_signature(body, signature, secret, timestamp): # Create the payload string exactly as BubblaV does: timestamp + . + json_body # Note: separators=(',', ':') ensures standard JSON formatting without whitespace payload = f"{timestamp}.{json.dumps(body, separators=(',', ':'))}" expected = hmac.new( secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected) @app.route('/api/secure-endpoint', methods=['POST']) def secure_endpoint(): # Get headers signature = request.headers.get('X-BubblaV-Signature', '').replace('sha256=', '') timestamp = request.headers.get('X-BubblaV-Timestamp') if not timestamp or not signature: return jsonify({'success': False, 'error': 'Missing signature headers'}), 401 # Check timestamp (5 min tolerance) to prevent replay attacks if time.time() - int(timestamp) / 1000 > 300: return jsonify({'success': False, 'error': 'Request expired'}), 401 # Verify signature if not verify_signature(request.json, signature, os.environ['SECRET'], timestamp): return jsonify({'success': False, 'error': 'Invalid signature'}), 401 # Process authenticated request... return jsonify({'success': True, 'message': 'Verified!'}) ``` ### Testing HMAC Signatures Validating signatures can be tricky. Use our built-in debug tools to help: **Dashboard Debug Info**: In the **Testing** step of the Custom Tool Wizard, look for the **Request Details (Debug Info)** section. It shows you the exact **Payload String** we used to generate the signature. You can use this to debug your own verification code. *** ### Key Requirements & Security When generating or providing your own keys, follow these security best practices: **General Requirements:** * **Length:** Minimum 32 characters (longer is better) * **Complexity:** Use a mix of letters (upper/lowercase), numbers, and symbols * **Entropy:** Avoid common words, repeated characters (e.g., "aaaaa"), or sequential patterns (e.g., "123456") **Specific Guidelines:** * **Bearer Tokens:** Must be URL-safe (no spaces or special characters). * *Example:* `A4B8C12D16F20G24H28I32J36K40L44M48` * **HMAC Secrets:** Recommended minimum 64 characters for cryptographic security. * *Example:* `abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx...` **Security Note:** These keys are used to authenticate API requests. Store them securely and never share them publicly. If a key is compromised, regenerate it immediately. **Using Existing Keys:** If you choose to use an existing API token or secret key, ensure it is properly configured on your endpoint to accept requests from BubblaV. *** ## Request & Response Format ### Request from BubblaV Your endpoint receives POST requests with this JSON body: ```json theme={null} { "tool_name": "get_order_status", "arguments": { "order_number": "ORD-12345", "include_items": true }, "timestamp": 1703123456789, "user_id": "uuid-of-website-owner" } ``` ### Response to BubblaV Return JSON in this format: ```json theme={null} { "success": true, "data": { "order_number": "ORD-12345", "status": "shipped", "tracking": "1Z999AA123456789", "estimated_delivery": "2024-01-15", "items": [ { "name": "Blue T-Shirt", "quantity": 2 } ] }, "message": "Order ORD-12345 has shipped and will arrive by January 15th." } ``` ```json theme={null} { "success": false, "error": "Order not found: ORD-99999", "data": null } ``` The `message` field is what the AI will use to respond to the customer. Make it friendly and informative! *** *** ## Example: Discourse Forum Search Here's how to connect to a Discourse forum to search for topics. ### 1. Tool Configuration | Field | Value | | ------------ | ----------------------------------------------------------------------------------------------------------------- | | Tool Name | `forum_search` | | Display Name | Community Forum Search | | Description | Search the community forum for topics. Use when answering technical questions or looking for community solutions. | | Endpoint URL | `https://community.yourdomain.com/search.json` | | Auth Method | None (Public API) | ### 2. Argument Schema ```json theme={null} { "q": { "type": "string", "description": "The search query to find relevant topics", "required": true } } ``` ### 3. Parameters * **q**: Add as a query parameter (Method: `query`) ### 4. Advanced: Two-Step Workflow For better results, often you want to search first, then fetch the full topic details. 1. **Create `forum_search` tool**: Returns a list of topics. 2. **Create `forum_topic_detail` tool**: * URL: `https://community.yourdomain.com/t/{topic_id}.json?print=true` * Params: `topic_id` (Path parameter) **AI Instructions**: "First use `forum_search` to find relevant topics. Then use `forum_topic_detail` with the best matching topic ID to get the full answer." *** ### In Dashboard 1. Go to **Integrations** → **Custom Tools** 2. Find your tool and click **Test** 3. Enter sample arguments 4. Click **Run Test** 5. Verify the response looks correct ### Live Testing 1. Open your website with the chatbot 2. Ask questions that should trigger your tool: * "What's the weather in New York?" * "How's the weather in London?" * "Check weather for Tokyo" *** ## Troubleshooting * Make your Description for AI more specific * Include trigger words customers use * Verify tool is marked as Active * Verify secret key is correct * Check endpoint receives expected headers * For HMAC, verify timestamp and signature calculation * Ensure endpoint responds within 10 seconds * Optimize database queries * Check network connectivity * Return valid JSON with `success`, `data`, `message` fields * Check for syntax errors in JSON * Test endpoint with curl or Postman first *** ## Best Practices Each tool should do one thing well Help AI understand when to use each tool Aim for sub-second response times Return user-friendly message text *** ## Next Steps Hand off conversations to live agents Enable real-time web search See all available integrations # Discord Source: https://docs.bubblav.com/user-guide/integrations/discord Connect your Discord server to add AI chatbot capabilities to your community Transform your Discord server with an intelligent AI chatbot that can answer questions, provide support, and engage with your community members automatically using slash commands and the "Ask BubblaV" context menu action. ## Why Connect Discord? Use `/ask` command for quick questions anywhere in your server AI responds to community questions anytime, day or night Choose specific channels where the bot should be active Ask the AI to analyze any message via the "Apps" context menu Automatically reply to new forum posts with helpful answers Answers based on your website's content and documentation ## What Can the Discord Bot Do? ### Answer Questions Instantly Your community members can ask questions about your product, service, or content directly in Discord: **Using Slash Commands:** ``` /ask How do I reset my password? /ask What are your business hours? /ask Tell me about your premium features ``` **Using Context Menu Actions:** 1. Right-click any message in Discord 2. Navigate to **Apps** 3. Click **Ask BubblaV** ### Provide 24/7 Support * Responds instantly to common questions * No waiting for human moderators * Reduces support workload * Consistent, accurate answers ### Search Your Knowledge Base The bot uses your website's content to provide accurate answers: * Documentation pages * FAQ sections * Product information * Help articles * Custom knowledge content ### Create Organized Conversations * **Thread Support**: Create threads for responses to keep channels clean * **Forum Auto-Reply**: Automatically respond to new forum posts * **Channel-Specific**: Limit bot to specific channels (support, help, FAQ) * **Role Restrictions**: Only allow certain roles to use the bot ## Prerequisites * Discord server where you have **Administrator permissions** * Ability to invite bots to your server * Active BubblaV account with a website * Website with knowledge base content ## Setup Steps Go to **Dashboard** → **Your Website** → **Integrations** and find the Discord card Click **Connect Discord** to open the bot invitation flow You'll be redirected to Discord to authorize the bot: 1. Select the server where you want to add the bot 2. Review the requested permissions: * Read Messages * Send Messages * Embed Links * Read Message History * Create Public Threads * Add Reactions * Use Slash Commands 3. Click **Authorize** 4. Complete the captcha verification Return to the BubblaV dashboard. The Discord integration should now show **Connected** with your server name Click **Configure** on the Discord integration to customize: * Which channels the bot should respond in * Forum mode settings * Thread creation preferences * Role-based access control Go to your Discord server and test: ``` /ask Hello, are you working? ``` The bot should respond with an AI-generated answer based on your website's content. ## Using Slash Commands ### `/ask` Command The primary way to interact with the bot. Simply type `/ask` followed by your question. **Syntax:** ``` /ask [your question here] ``` **Examples:** ``` /ask How do I create an account? /ask What payment methods do you accept? /ask Where can I find the API documentation? /ask Tell me about your pricing plans ``` **Response Format:** * The bot responds with a Discord embed * Includes AI-generated answer from your knowledge base * Shows source citations (links to your website pages) * Truncated responses include a link to view the full answer **Command Availability:** * Works in all text channels (unless you restrict it) * Available in threads * Works in forum channels * Instant autocomplete as you type ## Configuration Options Explained ### Channel Selection By default, the bot will respond in all text channels. You can limit this to specific channels: 1. Go to **Dashboard** → **Integrations** → **Discord** → **Configure** 2. View the list of all channels in your server 3. Check only the channels where you want the bot active 4. Click **Save Settings** **Best Practices:** * Start with dedicated support/help channels * Avoid enabling in social/general chat channels * Perfect for: `#support`, `#help`, `#faq`, `#questions` **Empty Selection:** If no channels are selected, the bot responds in **all channels** (not recommended for busy servers). ### "Ask BubblaV" Context Menu Action A powerful way to have the AI analyze an existing message. This is perfect for answering questions that members have already posted without using a slash command. **How to Use:** 1. Find a message containing a question or topic you want addressed. 2. Right-click the message (or long-press on mobile). 3. Select **Apps** → **Ask BubblaV**. 4. The AI will read the message content and provide a response in the channel. **Benefits:** * **Accuracy**: The AI gets the exact text of the question. * **Context**: Works perfectly in busy channels where slash commands might feel disconnected. * **Reliability**: Unlike @mentions which can be ignored by bots in certain privacy modes, Context Actions are direct interactions that always reach the bot. **Availability:** * Works on any message in enabled channels. * Available to all users with the "Use Application Commands" permission. ### Forum Auto-Reply Mode Enable this to automatically respond to new forum posts: **How It Works:** 1. User creates a new post in a forum channel 2. Bot analyzes the post title and content 3. Bot responds with relevant information from your knowledge base 4. Response appears as the first reply in the thread **Best For:** * Support forums * Help channels * FAQ forums * Community Q\&A sections **Configuration:** 1. Enable "Forum Auto-Reply Mode" in Discord settings 2. Ensure forum channels are selected in channel list 3. Bot will auto-reply to new posts only (not replies) ### Enable Threads When enabled, bot responses are posted as threads: **Benefits:** * Keeps main channels cleaner * Creates organized discussions * Users can follow up in thread * Easier to track conversation history **How It Works:** 1. User asks question with `/ask` or "Ask BubblaV" context action 2. Bot creates a new thread 3. Response is posted in the thread 4. Users can continue conversation in thread **Best For:** * Busy servers * Channels with high message volume * Servers that value organization ### Role-Based Access Control Restrict bot usage to specific roles: **Configuration:** 1. Go to Discord integration settings 2. Select allowed roles (e.g., "Members", "Verified", "Premium") 3. Save settings **Use Cases:** * Limit to verified members only * Premium feature for paying subscribers * Prevent abuse from new members * Create VIP support tiers **Empty Selection:** If no roles are selected, **all users** can use the bot. ## Response Examples ### Simple Question **User:** ``` /ask What are your business hours? ``` **Bot Response:** ``` ╔════════════════════════════════════════╗ ║ BubblaV AI Assistant ║ ╠════════════════════════════════════════╣ ║ We're open Monday through Friday ║ ║ from 9 AM to 6 PM EST. ║ ║ ║ ║ For urgent matters outside business ║ ║ hours, you can email support@... ║ ║ ║ ║ Sources: ║ ║ • Contact Us Page ║ ╚════════════════════════════════════════╝ ``` ### Product Question **User:** ``` /ask Tell me about the Pro plan features ``` **Bot Response:** Provides detailed information about Pro plan features, pricing, and benefits with links to pricing page. ### Technical Question **User:** ``` /ask How do I integrate the API? ``` **Bot Response:** Provides code examples, API documentation links, and step-by-step integration guide based on your docs. ## Test Your Integration After setup, test the bot in your Discord server: ### Basic Test 1. Go to one of the enabled channels 2. Type: `/ask Are you working?` 3. The bot should respond within 2-3 seconds ### Knowledge Test 1. Ask a question that's answered on your website 2. Example: `/ask What is [your product]?` 3. Bot should provide answer with source citations ### Channel Test 1. Try using bot in disabled channel 2. Bot should not respond (or show "not enabled" message) 3. Verify bot works in enabled channels only ### Context Menu Test 1. Right-click any message in an enabled channel. 2. Select **Apps** → **Ask BubblaV**. 3. The bot should respond to that specific message content within seconds. ## Best Practices **Start Small**: Begin with "Require Mention" enabled and limit to 1-2 channels. Expand after testing. **Monitor Usage**: Check the Discord integration analytics in your BubblaV dashboard to see how often the bot is used. **Update Knowledge Base**: Regularly update your website content to improve bot responses. The bot is only as good as your knowledge base. **Set Expectations**: Add a channel topic or pinned message explaining that responses are AI-generated and may not always be perfect. ## Troubleshooting **Solutions:** * Wait 5-10 minutes after installation (commands need to propagate) * Ensure bot has "Use Application Commands" permission * Try leaving and rejoining the channel * Reinstall the bot and reauthorize permissions * Check Discord Developer Mode is enabled (User Settings → Advanced) **Check:** * Verify bot is online in server member list * Ensure channel is enabled in BubblaV dashboard * Check if you have required role (if role restrictions enabled) * Verify your website has knowledge base content * Try asking a different question **Test Connection:** 1. Go to BubblaV Dashboard → Integrations → Discord 2. Click "Test Connection" 3. Check for error messages **Solutions:** * Verify the bot has been invited to your server with correct permissions. * Ensure you are right-clicking an actual **Message** (the menu won't appear on users or empty space). * Check that you have "Use Application Commands" permission in the channel. * If recently installed, wait a few minutes for Discord to synchronize commands. * Try restarting your Discord client (Ctrl+R or Cmd+R) to force a refresh. **Solutions:** * Limit bot to specific channels (not #general or #chat) using the **Channel Selection** in dashboard. * Remove bot from busy social channels. * Consider enabling thread creation to keep responses out of the main channel. * Use role restrictions to limit who can use the AI commands. **Solutions:** * Ensure bot has been invited to the server * Check bot has "View Channels" permission * Try disconnecting and reconnecting the integration * Verify you're configuring the correct Discord server * Refresh the page and try again **Solutions:** * Verify forum channels are enabled in channel selection * Ensure "Forum Auto-Reply Mode" is enabled * Check bot has permissions in forum channels: * Read Messages * Send Messages in Threads * Create Public Threads * Verify forum posts are public (not restricted) * Test with a new forum post (bot doesn't reply to existing posts) **Solutions:** * Review your website's knowledge base content * Add more detailed documentation to your site * Use BubblaV's Q\&A feature to add specific answers * Check that your website crawler is up to date * Report issues to BubblaV support for AI improvements **Solutions:** * Check BubblaV status page for outages * Verify Discord integration is still connected in dashboard * Try disconnecting and reconnecting integration * Reinstall bot with fresh authorization * Contact support if issue persists **Solutions:** * Ensure you have Administrator permission in Discord server * Try using a different browser or incognito mode * Check if server has reached bot limit (100 bots max) * Verify server is not restricted by Discord * Ask server owner to invite the bot instead ## Plan Limits Discord bot messages count toward your BubblaV plan's message quota: | Plan | Monthly Messages | Discord Usage | | -------- | ---------------- | ------------------ | | **Free** | 100 | Shared with widget | | **Pro** | 5,000 | Shared with widget | **Note:** Each `/ask` command or Context Menu response counts as 1 message toward your quota. **Upgrade:** If you exceed your limit, upgrade your plan in Dashboard → Billing. ## FAQ **Yes**, but each Discord server requires its own website integration in BubblaV. One Discord server can only connect to one website, but you can create multiple websites in BubblaV if you manage multiple communities. Currently, the bot uses the default BubblaV branding. Custom bot names and avatars are planned for a future update. All bots across different servers share the same BubblaV identity. Yes, Discord conversations are stored in your BubblaV dashboard for analytics and training purposes. This helps improve response quality over time. You can view Discord interactions in Reports → Conversations. Currently, the bot only works in server channels and forums using slash commands and the context menu. Standard @mentions and direct message support are planned for a future update. The bot requires these permissions: * **Send Messages**: To post responses * **Embed Links**: To format responses nicely * **Use Slash Commands / Application Commands**: Required for /ask and context menu actions * **Create Public Threads**: For threaded conversations (optional) * **Add Reactions**: For interactive features (optional) These are requested automatically during installation. The bot typically responds within 2-5 seconds. Since we use Discord's Interaction API, the bot provides an instant "Thinking..." indicator so users know their request is being processed immediately. Currently, `/ask` is the only slash command available. Additional commands (like `/help`, `/status`, `/feedback`) are planned for future releases. Contact support to request specific commands. If the bot can't find relevant information in your knowledge base, it will: 1. Respond honestly: "I don't have information about that" 2. Suggest contacting human support 3. Optionally offer to escalate to your team (if Escalate to Human integration is enabled) The bot never makes up information or guesses. Server moderators cannot see analytics directly in Discord. However, if you grant them access to your BubblaV dashboard (via Team feature), they can view: * Message count and usage * Popular questions * Response quality metrics * User satisfaction ratings The bot responds in the same language as your knowledge base content. If your website has multi-language content, the bot can provide answers in those languages. Automatic translation is not currently supported. ## Security & Privacy **Data Security**: We only request read and send message permissions. Your Discord server data remains secure and private. **Privacy Compliance**: Discord conversations are processed according to our [Privacy Policy](https://bubblav.com/privacy). We do not share conversation data with third parties. **Server Ownership**: Only server administrators can invite bots. If you're not an admin, contact your server owner to add the bot. **Rate Limits**: Discord enforces rate limits on bot activity. If the bot stops responding temporarily, it may be rate-limited. This resets automatically within minutes. ## Need Help? Read our full documentation Contact our support team Join our Discord server Report an issue ## What's Next? After setting up Discord, consider: Escalate complex questions to your support team Add custom actions for Discord users Track Discord bot interactions Improve bot responses with better content # Escalate to Human Source: https://docs.bubblav.com/user-guide/integrations/escalate-to-human Enable the built-in tool to let visitors reach out to your support team. # Escalate to Human Integration The **Escalate to Human** integration allows your chatbot to collect visitor contact information (email) and create a support request or initiate a live chat session. ## Features * **Built-in Tool**: Automatically understood by the chatbot. * **Support Handoff**: Connects visitors with your support team when they request help. * **Context Aware**: Uses existing visitor information if available. * **Customizable**: Can be enabled or disabled per website. ## Setup 1. Go to your **BubblaV Dashboard** > **Integrations**. 2. Find the **Escalate to Human** integration card. 3. Click **Connect** (if not already connected). 4. Toggle the switch to **Active**. ## How it works When a visitor asks to speak to support or says "I need help", the chatbot will: 1. Check if the **Escalate to Human** integration is enabled. 2. Ask the visitor for their email address (if not already known). 3. Confirm they want to be connected to a support specialist. 4. Execute the contact form tool, which can trigger notifications or create a live chat session in your configured support system (e.g., Zendesk, HubSpot, or BubblaV Live Chat). ## Requirements * **Plan**: Available on all plans (Free, Pro, Pro+). # Framer Source: https://docs.bubblav.com/user-guide/integrations/framer Add BubblaV to your Framer website with our official plugin or the Ask AI Button component Add BubblaV AI chatbot to your Framer website in seconds. No coding required. ## Why Use the Framer Plugin? Framer Plugin Demo

Install the plugin, sign in, and select your website. The widget is automatically added to your canvas. Customize widget appearance directly in Framer's property panel—position, theme, bot name. Secure authentication with your BubblaV account. No need to copy-paste Website IDs. *** ## Installation ### Option 1: Using the Framer Plugin (Recommended) The easiest way to add BubblaV to your Framer site. The plugin is available on the Framer Marketplace: Install the BubblaV plugin directly from the Framer Marketplace In Framer, go to Plugins → Store and search for "BubblaV", or open the plugin page directly Click Install to add the plugin to your project Click Login & Select Website to sign in to your BubblaV account and choose your website Adjust the widget appearance in the plugin panel—position, theme, bot name Publish your Framer site and the chatbot will appear automatically ### Option 2: Manual Installation If you prefer manual setup: Open your Framer project and go to Site Settings Click on the General tab Scroll down to the End of \ tag section Paste your BubblaV embed code from the dashboard Click Save and then Publish your site The plugin method is recommended because it automatically creates the component in your code and adds it to your canvas with pre-configured settings. *** ## OAuth Login Flow The plugin uses a secure OAuth flow for authentication: 1. Click **"Login & Select Website"** button in the plugin 2. Browser opens to BubblaV login page 3. Complete login (or sign up if new) 4. Plugin automatically detects successful login 5. Select your website from the dropdown 6. Widget is configured and added to your site *** ## Plugin Features ### Property Controls (Sidebar) * **Site ID** - Your website ID (auto-filled when using OAuth) * **Bot Name** - Custom display name for your chatbot * **Position** - Choose widget placement: bottom-right, bottom-left, or bottom-center * **Theme** - Light or dark mode to match your site ### Visual Preview The plugin shows a live preview on your canvas: * BubblaV branding for easy identification * Status indicator (Ready/Missing Site ID) * Position preview shows where the widget will appear ### When Published The widget script is automatically injected and renders as a floating chat button on your published site. *** ## Available Tools After Connection When you connect your Framer website to BubblaV, the chatbot gains access to your crawled website content and knowledge base. | Feature | Description | | ------------------ | ------------------------------------------------ | | **Website Search** | Chatbot searches your entire Framer site content | | **Knowledge Base** | Add FAQs, documents, and custom content | | **Live Support** | Handoff to human agents when needed | | **Analytics** | Track conversations and visitor insights | *** ## Troubleshooting * Verify you've published your site (not just preview) * Check your Website ID is correct * Wait 1-2 minutes for caching to clear * Try clearing your browser cache * Make sure popups are allowed in your browser * Check that you're not using an ad blocker * Try refreshing the page and clicking Login again * Make sure you have created a website in your BubblaV dashboard * Check that you're logged in to the correct account * Try logging out and back in * Check your message limits (may be exceeded) * Verify crawl completed successfully in dashboard * Ensure knowledge base has content *** ## Next Steps Customize colors, position, and behavior Add your content for better responses # Google Analytics 4 Source: https://docs.bubblav.com/user-guide/integrations/google-analytics Integrate BubblaV events with Google Analytics 4 (GA4) and Google Tag Manager (GTM). BubblaV enables you to track user interactions with your AI chatbot and search widget directly in your Google Analytics 4 (GA4) dashboard. This integration allows you to see: * How many users open the chat or search widget. * What users are searching for (Search Queries). * How many messages are sent to the AI. * Which pages users are on when they interact. ## Prerequisites Before getting started, ensure you have: 1. A Google Analytics 4 property created. 2. The Google Analytics tracking script (`gtag.js`) OR Google Tag Manager snippet installed on the same page as your BubblaV widget. ## Installation The BubblaV integration is **zero-configuration** on the code side, but requires activation in your dashboard. ### 1. Enable in Dashboard To start tracking events, you must enable the integration for your website: 1. Go to your **Project Dashboard**. 2. Navigate to the **Integrations** tab. 3. Locate **Google Analytics 4** and click **Connect**. 4. Confirm the activation. ### 2. Automatic Detection Once enabled, the widget automatically detects if `window.gtag` (GA4) or `window.dataLayer` (GTM) is present on your website and begins dispatching events immediately. You do not need to add any extra code to the BubblaV widget snippet. ### How it works 1. BubblaV loads on your page. 2. It checks for the existence of the Global Site Tag (`gtag`) or GTM Data Layer. 3. When a user interacts (e.g., opens chat), BubblaV pushes an event to the detected analytics instance. ## Configuration While events are sent automatically, you may want to configure **Custom Definitions** in GA4 to see granular data like "Search Query" in your reports. ### Step 1: Check Real-time Data To verify the integration is working: 1. Open your website and interact with the widget (open it, send a message). 2. Go to **Google Analytics > Reports > Realtime**. 3. Look for events named `bubblav_chat_opened` or `bubblav_search_query` in the Event Count card. ### Step 2: Create Custom Dimensions (Optional) To report on specific event parameters (like `query` or `conversation_id`), create custom dimensions: 1. Go to **Admin > Data display > Custom definitions**. 2. Click **Create custom dimension**. 3. Add the following dimensions: | Dimension Name | Scope | Event Parameter | Description | | :-------------- | :---- | :---------------- | :------------------------------------ | | Search Query | Event | `query` | The text users typed into the search. | | Widget Type | Event | `widget_type` | 'chat' or 'search'. | | Search Source | Event | `source` | 'input' or 'suggestion'. | | Conversation ID | Event | `conversation_id` | Unique ID of the chat session. | ## Google Tag Manager (GTM) Setup If you use Google Tag Manager, BubblaV pushes events to the `dataLayer`. You need to create triggers to capture them. 1. **Create a Trigger:** * **Trigger Type:** Custom Event * **Event Name:** `bubblav_.*` (Use regex matching) OR specific names like `bubblav_search_query`. 2. **Create Variables:** * **Variable Type:** Data Layer Variable * **Data Layer Variable Name:** `query` (or other properties listed below). 3. **Create a Tag:** * Go to **Tags** and click **New**. * Click **Tag Configuration** and select **Google Analytics: GA4 Event**. * **Measurement ID:** Enter your GA4 Measurement ID (e.g., `G-XXXXXXXXXX`) or select your Google Tag variable. * **Event Name:** Enter `{{Event}}`. This dynamically passes the event name (e.g., `bubblav_search_query`) from the Data Layer to GA4. * **Event Parameters:** Expand this section to send additional data: * *Parameter Name:* `search_term` (or match your GA4 Custom Dimension). * *Value:* Click the `+` icon and select the **Data Layer Variable** you created in Step 2 (e.g., `{{dlv - query}}`). * **Triggering:** Click to select a trigger and choose the **Custom Event** trigger you created in Step 1. * **Save** the tag and **Submit/Publish** your GTM container changes. ## Event Reference ### Chat Events | Event Name | Description | Trigger | Properties | | :--------------------------- | :----------------- | :--------------------------------------------------------------- | :---------------------------------------- | | `bubblav_chat_opened` | Chat Opened | User clicks the implementation bubble or calls `BubblaV.open()`. | `widget_type: 'chat'` | | `bubblav_chat_closed` | Chat Closed | User minimizes the chat window. | `widget_type: 'chat'` | | `bubblav_widget_expanded` | Widget Expanded | User expands the widget for a better view. | `widget_type: 'chat'` | | `bubblav_widget_collapsed` | Widget Collapsed | User collapses the widget back to normal view. | `widget_type: 'chat'` | | `bubblav_message_sent` | Message Sent | User sends a message to the AI. | `conversation_id`, `message_id`, `text` | | `bubblav_message_received` | Message Received | User receives a response from the AI. | `conversation_id`, `message_id`, `text` | | `bubblav_conversation_rated` | Conversation Rated | User rates the overall conversation. | `conversation_id`, `rating` | | `bubblav_message_rated` | Message Rated | User rates a specific message (up/down). | `conversation_id`, `message_id`, `rating` | ### Search Events | Event Name | Description | Trigger | Properties | | :---------------------- | :------------ | :----------------------------------------------------------- | :-------------------------------------------------------- | | `bubblav_search_opened` | Search Opened | User clicks the search icon or calls `BubblaV.openSearch()`. | `mode` (e.g., 'modal', 'inline'), `widget_type: 'search'` | | `bubblav_search_closed` | Search Closed | User closes the search modal. | `mode`, `widget_type: 'search'` | | `bubblav_search_query` | Search Query | User submits a search or clicks a suggestion. | `query`, `source` | ## Troubleshooting ### Events not showing up? * **Check Ad Blockers:** Ensure your ad blocker isn't blocking Google Analytics. * **Wait:** GA4 standard reports can take 24-48 hours to update. Use the **Realtime** report for testing. * **Debug Mode:** Install the "Google Analytics Debugger" Chrome extension to see events in the developer console. ### Using a different analytics provider? If you use Mixpanel, Amplitude, or others, you can manually listen to BubblaV SDK events and forward them: ```javascript theme={null} window.BubblaV.on('search:query', (data) => { mixpanel.track('Site Search', { query: data.query }); }); ``` # Google Drive Source: https://docs.bubblav.com/user-guide/integrations/google-docs Use Google Docs, Sheets, and Slides from Google Drive as knowledge sources for your AI chatbot Transform your Google Drive into an intelligent knowledge base. Connect documents, spreadsheets, and presentations to provide instant answers from content you already maintain. ## Why Connect Google Drive? Sync Docs, Sheets, and Slides in one integration Changed files are automatically re-synced each cycle AI understands context and meaning, not just keywords OAuth 2.0 with read-only scopes — your files are never modified ## Prerequisites * A Google account with Docs, Sheets, or Slides files you want to use as knowledge * A BubblaV website with an active subscription ## Setup Steps Go to **Dashboard** → **Integrations** → **Google Drive** Click **Connect Google Drive** and authorize via Google Click **Add Files** to browse your Google Drive and select files to sync *** ## Supported File Types | Type | Google MIME Type | Export Format | | ------------- | ------------------------------------------ | --------------------- | | Google Docs | `application/vnd.google-apps.document` | Plain text | | Google Sheets | `application/vnd.google-apps.spreadsheet` | CSV | | Google Slides | `application/vnd.google-apps.presentation` | Text (via Slides API) | ## Content Syncing Google Drive content is synced automatically according to your plan's crawl frequency: * **Free**: No automatic syncing * **Pro**: Weekly ## Sync Status Each file shows one of four statuses: | Status | Meaning | | --------- | ------------------------------------- | | `Pending` | Added but not yet synced | | `Syncing` | Currently being processed | | `Synced` | Successfully synced to knowledge base | | `Failed` | Error during sync — hover for details | ## Permissions Required BubblaV requests the following read-only Google OAuth scopes: * `drive.readonly` — List and read files from Google Drive * `documents.readonly` — Read Google Docs content ## Troubleshooting Only Google Drive files (Docs, Sheets, and Slides) are shown. Other file types (PDFs, images, etc.) are not supported. Make sure you're viewing the correct Google account. Refresh the page. It takes a few minutes to sync. Only the first sheet of a spreadsheet is synced. For large sheets, only the first exported CSV is processed. Consider splitting data across multiple sheets or files. # Google Tag Manager Source: https://docs.bubblav.com/user-guide/integrations/google-tag-manager Install the BubblaV chatbot widget with Google Tag Manager (GTM) — no code editing required, works on any website. Add the BubblaV AI chatbot to **any website** using Google Tag Manager (GTM). GTM is one of the most popular ways to manage scripts on a site, and it lets you add the widget without touching your website's source code — ideal for a normal or custom website that doesn't have a dedicated marketplace app. ## Why Use Google Tag Manager? Add the widget through the GTM interface. You never edit your website's HTML, theme files, or server templates directly. GTM runs on virtually any website — custom builds, static sites, and platforms without an official app. It's a great default choice. Manage the widget alongside all your other tags (analytics, ads, tracking) from one place. Enable, pause, or remove it anytime. Looking for a no-code app install instead? If your site is on **Wix**, **Webflow**, or **Framer**, use our official marketplace app. GTM is the recommended method for any other or custom website. *** ## Prerequisites Before you start, make sure you have: 1. A **Google Tag Manager container** installed on your website. If you haven't set up GTM yet, follow Google's [Web installation guide](https://developers.google.com/tag-platform/tag-manager/web) first. 2. Your **BubblaV embed code**, available in your dashboard under **Installation**. It looks like this: ```html theme={null} ``` *** ## Installation ### Step 1: Open Google Tag Manager Log in to [Google Tag Manager](https://tagmanager.google.com) and select your container (or create a new one for your website). ### Step 2: Create a New Tag Go to **Tags** in the left sidebar, then click **New**. ### Step 3: Configure the Tag Click on **Tag Configuration**, then choose **Custom HTML** as the tag type. ### Step 4: Paste the Widget Code Paste your BubblaV embed code into the HTML field: ```html theme={null} ``` Replace `YOUR_WEBSITE_ID` with the site ID from your BubblaV dashboard. ### Step 5: Set the Trigger Click on **Triggering** and select **All Pages** so the widget loads on every page of your site. ### Step 6: Name and Save Name the tag **"BubblaV Chat Widget"** and click **Save**. ### Step 7: Publish Click **Submit** in the top-right corner, then click **Publish** to make the tag live on your site. After publishing, it may take a few minutes for changes to propagate. Open your site in an incognito window to verify the widget appears. *** ## Troubleshooting * Make sure you clicked **Submit** → **Publish** in GTM (saving a tag is not enough) * Confirm the trigger is set to **All Pages** (or includes the page you're checking) * Open your site in an incognito window and wait 1–2 minutes for cache to clear * Verify the `data-site-id` in your tag matches the website ID in your BubblaV dashboard * Use **Preview** mode in GTM to confirm the "BubblaV Chat Widget" tag fires on page load * Check your browser console for errors related to `widget.js` * Make sure an ad blocker or script blocker isn't blocking `bubblav.com` * Confirm your website has available message quota in the dashboard GTM is free. Create an account at [tagmanager.google.com](https://tagmanager.google.com), set up a container for your website, and add the two GTM container snippets to your site's `` and `` as Google instructs. Then follow the installation steps above. *** ## Next Steps Customize colors, position, and behavior Add your content for better AI responses # Haravan Source: https://docs.bubblav.com/user-guide/integrations/haravan Add your AI chatbot to Haravan stores with one-click installation—no coding required Connect your Haravan store to BubblaV and instantly deploy an AI-powered chatbot that provides 24/7 customer support—all without touching a single line of code. ## Why Connect Haravan? No coding required. Simply authorize and the chatbot is automatically added to your store. Go from zero to live chatbot in under 2 minutes Chatbot updates automatically whenever you change your settings in the dashboard Provide instant answers to your customers around the clock ## Prerequisites * Active Haravan store * Store owner or admin permissions ## Setup Steps Installing BubblaV on your Haravan store is quick and simple with OAuth authorization. Go to your BubblaV dashboard and navigate to **Integrations** → **Haravan**. Click **Connect Store**. You'll be redirected to the Haravan authorization page. Review the permissions requested and click **Yes** to approve the installation. Haravan OAuth Authorization Dialog

This dialog confirms that BubblaV will be granted permission to add the chatbot to your store. After clicking **Yes**, you'll be redirected back to your BubblaV dashboard. The Haravan card should now show **Connected**, and your chatbot is live on your store. **No Code Changes Needed**: The integration automatically injects the chatbot script into your Haravan store. You don't need to edit any theme files or add code manually. *** ## Test Your Integration Visit your Haravan store and open the chatbot widget. Try asking a question based on your knowledge base settings: * "What are your business hours?" * "How do I contact support?" * "What's your return policy?" ## Troubleshooting * Ensure you have store admin permissions * Clear browser cache and try again * Verify your store URL is correct * Wait a few minutes for the script injection to complete * Clear your browser cache and reload the store page * Check that the connection status shows **Connected** in your dashboard * Wait a few minutes for the script injection to complete * Clear your browser cache and reload the store page * Check that the connection status shows **Connected** in your dashboard **Security**: We only request the minimum permissions needed to add the chatbot to your store. Your store data remains secure. # HubSpot Source: https://docs.bubblav.com/user-guide/integrations/hubspot Sync conversations and contacts to your CRM Sync your chatbot conversations, contacts and leads directly to HubSpot CRM. ## Why Connect HubSpot? * **Lead Capture**: Automatically create contacts as soon as email is collected. * **Conversation Logging**: Save chat transcripts to the contact's timeline. * **Visitor Insights**: Support agents see CRM properties and contact history in real-time. * **Page View Tracking**: See which pages visitors viewed before chatting. ## Visitor Insights for Support Agents The HubSpot integration enriches the **Visitor Insight** panel in your BubblaV dashboard, giving support and sales agents critical context from your CRM: HubSpot Visitor Insight

* **Contact Properties**: View HubSpot contact properties like Lifecycle Stage, Lead Status, and Owner directly in the chat. * **Activity Timeline**: See recent events such as emails, notes, and meetings to understand the customer's history. * **Page View Tracking**: Review a history of the specific pages and URLs the visitor has viewed on your site. * **Deal Status**: Monitor any active or closed deals associated with the contact to prioritize high-value interactions. Based on these insights, agents can provide a more personalized and professional support experience with the full CRM context at their fingertips. ## Setup Steps Go to **Dashboard** → **Integrations** → **HubSpot** Click **Connect HubSpot**. You will be redirected to HubSpot's OAuth page. Choose the HubSpot account you want to link and grant permissions. Once redirected back, you'll see your HubSpot Portal ID and connection status. *** ## Configuration After Connection After successfully connecting HubSpot, you can configure how contacts are synced, which workflows are triggered, and how conversations are logged. ### Lead & Contact Sync Configure how new contacts are created and managed in HubSpot: **Sync Lead** * Automatically create a contact in HubSpot as soon as the visitor provides their email address in the chat. * **Default**: Enabled * **Location**: In HubSpot integration settings → **Sync Lead** **Lifecycle Stage for New Contacts** * The HubSpot lifecycle stage applied when a visitor first shares their email * **Default**: `lead` * **Examples**: `lead`, `subscriber`, `opportunity`, `customer` * **Location**: In HubSpot integration settings → **Contact sync defaults** **Lifecycle Stage After Escalation** * The lifecycle stage applied when a live-support escalation is created * **Default**: `opportunity` * **Purpose**: Helps sales teams pick up escalated conversations immediately * **Location**: In HubSpot integration settings → **Contact sync defaults** **Default HubSpot Owner** * Optional HubSpot owner ID to assign new contacts * **Default**: Unassigned (leave blank) * **How to find**: Use the HubSpot Owners API (`GET https://api.hubapi.com/crm/v3/owners`) to look up owner IDs * **Location**: In HubSpot integration settings → **Contact sync defaults** ### Workflow Triggers Automatically enroll contacts into HubSpot workflows when specific intents or tags are detected in chat transcripts. **To configure workflow triggers:** 1. Go to **Dashboard** → **Integrations** → **HubSpot** 2. Navigate to the **Workflow Triggers** section 3. Add rules with: * **Match Type**: Choose `tag` (conversation tag) or `intent` (detected intent) * **Value**: The tag or intent value to match (e.g., `sales-qualified`, `support-request`) * **Workflow ID**: The internal HubSpot workflow ID to trigger 4. Click **Add rule** for each workflow you want to configure 5. Click **Save HubSpot settings** **Example:** * **Match Type**: `tag` * **Value**: `sales-qualified` * **Workflow ID**: `12345678` * **Result**: When a conversation is tagged with `sales-qualified`, the contact is automatically enrolled in workflow `12345678` ### Timeline Logging Control whether chat transcripts are logged as notes in HubSpot. **Log Transcripts as HubSpot Notes** * **Default**: Enabled * **What it does**: Attaches the latest conversation snippet to the contact record in HubSpot * **Additional**: Notes are also associated with HubSpot tickets when available * **Location**: In HubSpot integration settings → **Timeline logging** Timeline logging keeps your sales and support teams informed about customer interactions, ensuring seamless handoffs between chatbot and human agents. ### Save Configuration After configuring all settings: 1. Review your Contact Sync, Workflow Triggers, and Timeline Logging settings 2. Click **Save HubSpot settings** to apply the configuration 3. Test by having a conversation that should trigger your configured workflows *** ## Features * **New Contact Creation**: When a visitor provides their email in chat, a contact is created in HubSpot. * **Timeline Events**: Chat sessions are logged as custom timeline events. * **Property Sync**: Basic info (Name, Email) is synced automatically. # Instagram Source: https://docs.bubblav.com/user-guide/integrations/instagram Connect your Instagram Business account to add AI chatbot capabilities to your customer support Transform your Instagram Direct Messages with an intelligent AI chatbot that can answer questions, provide support, and engage with your customers automatically 24/7. ## Why Connect Instagram? Customers get immediate answers based on your website's knowledge base AI responds day and night, even when your team is offline Support agents can jump into any conversation from the dashboard All Instagram DM conversations are logged and searchable AI supports 100+ languages for international customers Answers based on your website's content and documentation ## What Can the Instagram Bot Do? ### Answer Customer Questions Instantly Your customers can ask questions about your products, services, or content directly through Instagram Direct Messages: **Example Questions:** ``` What are your business hours? How do I track my order? Tell me about your return policy What payment methods do you accept? ``` ### Provide 24/7 Support * Responds instantly to common questions * No waiting for business hours * Reduces support ticket volume * Consistent, accurate answers ### Search Your Knowledge Base The bot uses your website's content to provide accurate answers: * Product information * Help articles * FAQ sections * Pricing details * Shipping information ### Human Agent Handoff & Unified Inbox Instagram messages appear in your **Live Support** unified inbox alongside website widget and other platform conversations. Each conversation shows an Instagram badge so you always know the source platform. When replying to Instagram conversations from the dashboard, be aware of Meta's 24-hour messaging window. Messages sent more than 24 hours after the customer's last message will be blocked with a clear error message. **How agent replies work:** 1. Go to **Live Support** in your dashboard 2. Find the Instagram conversation (look for the Instagram badge) 3. Click to open and type your reply 4. Your message is sent directly to the customer's Instagram DM 5. The AI remains paused while you're active in the conversation The AI resumes automatically when you leave the conversation. ## Prerequisites * Instagram Business account or Creator account * Active BubblaV account with a website * Website with knowledge base content (crawled pages) ## Setup Steps Go to **Dashboard** → **Your Website** → **Integrations** and find the Instagram card Click **Connect Instagram** to open the Facebook authorization flow 1. Select which account to connect 2. Click **Select** to confirm Return to the BubblaV dashboard. The Instagram integration should now show **Connected** with your username and account ID Send a test DM to your Instagram account to verify the AI responds correctly ## Managing Your Integration ### View Connected Accounts From the Instagram configuration page, you can see all connected accounts: * Instagram username and profile picture * Display name and account type * Connection status (Active) ### Disconnect an Account To remove an Instagram account: 1. Go to **Dashboard** → **Your Website** → **Integrations** 2. Click **Instagram** → **Configure** 3. Find the account you want to remove 4. Click the disconnect button 5. Confirm the disconnection in the dialog Disconnecting an account will stop the AI from responding to DMs for that account. ## How Messages Are Processed 1. **Customer sends DM** → Message arrives at your Instagram account 2. **Webhook triggers** → BubblaV receives the message 3. **AI analyzes question** → Your website's knowledge base is searched 4. **Response generated** → AI formulates an answer with sources 5. **Sent to Instagram** → Customer receives the response in their DM 6. **Conversation logged** → Message stored in your dashboard ## FAQ Yes, the Instagram Messaging API only works with Instagram Business accounts. Personal accounts cannot receive messages via webhooks. Converting to a Business account is free and can be done in Instagram Settings. The AI uses your website's content to generate responses. To improve answer quality, ensure your website has comprehensive, up-to-date information. You can also add custom content through the Knowledge section. If the AI is unsure or the customer needs complex help, they can be escalated to a human agent. You'll see all conversations in the Live Support dashboard and can jump in anytime. ## Next Steps * Set up your [Live Support](/user-guide/live-support) to monitor conversations * Improve your [Knowledge Base](/user-guide/knowledge) content for better answers * Explore other [Integrations](/user-guide/integrations/overview) to connect more platforms # Klarna Source: https://docs.bubblav.com/user-guide/integrations/klarna Let your chatbot answer customer payment questions Enable your AI chatbot to answer Klarna payment questions, check order status, and help customers track refunds through natural conversation. ## Why Connect Klarna? * **Instant Payment Answers**: Customers get payment status, order info, and refund details immediately * **BNPL Support**: Handle Pay Later, Pay in 3/4, and Financing questions automatically * **Reduced Support Tickets**: Deflect 70%+ of common payment questions automatically * **Secure by Default**: Read-only access with email verification for each lookup ## Prerequisites Before connecting, you'll need: * A Klarna merchant account with API access * Admin access to create API credentials in Klarna Merchant Portal ## Setup Steps ### Step 1: Get Your Klarna API Credentials Go to [Klarna Merchant Portal](https://portal.klarna.com) and log in For testing, use the [Klarna Playground Portal](https://portal.playground.klarna.com) instead. Go to **Settings** → **API Credentials** → **Generate new Klarna API credentials** Download the credentials file when prompted. This file contains: * **API Username**: Your API username from Klarna * **API Password**: The API password (only shown once) Store this file securely—the password is only shown once and cannot be retrieved later. Note which region your Klarna account is in: * **EU** (Europe) * **NA** (North America) * **OC** (Oceania/Australia) ### Step 2: Connect to BubblaV Go to **Dashboard** → **Integrations** → **Klarna** Paste the **API Username** from your credentials file Paste the **API Password** from your credentials file Choose your Klarna API region (EU, NA, or OC) If using credentials from [Klarna Playground Portal](https://portal.playground.klarna.com), enable the **Test Mode** checkbox to use sandbox API Click **Connect** to validate credentials and enable payment tools *** ## Available Tools Once connected, these tools become available to your chatbot: | Tool | Description | | ---------------------------- | ------------------------------------------------------------- | | **Get Order Status** | Order status, total amount, and creation date | | **Get Payment Status** | Whether the payment is UNPAID, PAID, or CLOSED | | **Get Refund Status** | Refund amounts and processing details | | **Get Payment Info** | Payment method type and installment schedule | | **Get Order History** | List of customer's Klarna orders | | **Get Payment Methods** | Available Klarna payment options | | **Get Installment Schedule** | Detailed breakdown of Pay in 3/4 installments with due dates | | **Get Upcoming Payments** | List of pending payments with "days until due" context | | **Get Capture Details** | Shows what's been charged vs. pending (for partial shipments) | *** ## How It Works 1. **Customer asks a payment question** (e.g., "Is my Klarna payment complete?") 2. **Customer provides order reference** and email for verification 3. **AI verifies customer** by matching email to the order's billing address 4. **Data is retrieved** securely from Klarna's API 5. **Formatted response** is provided with payment status and details Customer verification uses email matching. The chatbot only provides payment information when the provided email matches the billing email on the Klarna order. Unlike some integrations, Klarna's API requires a Klarna Order ID (UUID format) for lookups. If using Shopify with the Klarna OSM app, this is extracted automatically. Otherwise, customers need to provide it from their Klarna app or email. *** ## Shopify Integration For the best experience with Shopify stores, we recommend installing the **Klarna On-site Messaging (OSM) app** with Extended Access enabled. When Extended Access is enabled, the Klarna Order ID is automatically added to Shopify order notes, allowing our chatbot to seamlessly look up Klarna payment information without requiring customers to manually provide their Order ID. ### Enable Extended Access Install the [Klarna On-site Messaging app](https://apps.shopify.com/klarna-on-site-messaging) from the Shopify App Store In the OSM app settings, ensure **Extended Access** is enabled. This is on by default. * Klarna Order ID is automatically added to Shopify order notes * A "Klarna" tag is added to orders placed through Klarna * Product images and URLs are synced to the Klarna app for customers If the Klarna Order ID is not available (e.g., OSM not installed or Extended Access disabled), the chatbot will ask the customer to provide their Klarna Order ID (UUID format) from their Klarna app or confirmation email. *** ## Security * **Read-only access**: No changes to orders or payments—information only * **Email verification**: Customers must be verified before accessing payment data * **Encrypted credentials**: API keys are encrypted at rest * **GDPR compliant**: We follow EU data protection requirements * **Regional API support**: Data stays within your configured region *** ## FAQs You need read access to the Order Management API. This provides access to order details, payment status, captures, and refunds without allowing any modifications. Customers provide their order reference number and email. The chatbot verifies that the email matches the billing address on the Klarna order before showing any payment information. No. Due to Klarna API limitations, a Klarna Order ID is required for lookups. With Shopify + Klarna OSM, this is extracted automatically. Otherwise, the chatbot guides customers to find it in their Klarna app or confirmation email. We support all Klarna regions: EU (Europe), NA (North America), and OC (Oceania/Australia). Select the correct region when configuring the integration. Yes. We use Klarna's official API with encrypted credentials. Your API key is never exposed, and we comply with GDPR and industry security standards. Yes! Enable **Test Mode** when connecting to use Klarna Playground API for testing. Use credentials from [portal.playground.klarna.com](https://portal.playground.klarna.com) to test the integration before going live. *** ## Troubleshooting ### "Invalid credentials" Error * Verify the API Username is correct * Check that the API Password is correct * Ensure you selected the correct region (EU, NA, or OC) * Verify credentials haven't been revoked in Klarna Merchant Portal ### "Order not found" Response * Verify the order reference number is correct * The order must exist in your Klarna merchant account * For very recent orders, wait a few minutes for API sync ### "Email verification failed" * The email provided must exactly match the order's billing email * Check for typos or different email addresses * Email matching is case-insensitive ### Tools Not Appearing * Verify the integration status is "Connected" * Check that tools are enabled in **Configure** → **Tools** * Refresh your integrations page *** ## Example Conversations Here are examples of how customers can interact with your chatbot: **Checking payment status:** > Customer: "Is my Klarna payment complete?" > Bot: "Let me check that for you. What's your order reference number?" > Customer: "ORD-12345" > Bot: "I found your order. ✅ Your payment is complete. Total paid: SEK 1,200.00 via Pay in 3." **Checking refund status:** > Customer: "Has my refund been processed?" > Bot: "I can check that for you. What's your order number and the email address on the order?" > Customer: "Order ABC123, email is [anna@example.com](mailto:anna@example.com)" > Bot: "Yes, your refund of SEK 299.00 was processed on December 15, 2024." **Understanding payment options:** > Customer: "What Klarna payment options do you offer?" > Bot: "We offer these Klarna options: > • Pay Later: Pay the full amount within 30 days > • Pay in 3: Split into 3 interest-free payments > • Financing: Flexible monthly payments" **Checking installment schedule:** > Customer: "When are my Klarna payments due?" > Bot: "Here's your installment schedule for order ORD-12345: > ✅ #1: SEK 400.00 - Due: Dec 1 (Paid) > ⏳ #2: SEK 400.00 - Due: Jan 1 > ⏳ #3: SEK 400.00 - Due: Feb 1" **Checking upcoming payments:** > Customer: "When is my next Klarna payment?" > Bot: "Your next payment is SEK 400.00 due on January 1 (in 10 days). You have one more payment of SEK 400.00 due February 1." **Understanding partial charges:** > Customer: "Why was I only charged for part of my order?" > Bot: "I can see that SEK 600.00 of your SEK 1,200.00 order has been captured so far. This typically happens when items ship separately. The remaining SEK 600.00 will be charged when the rest of your order ships." # Klaviyo Source: https://docs.bubblav.com/user-guide/integrations/klaviyo Connect BubblaV to Klaviyo for unified customer tracking Connect BubblaV to Klaviyo to sync chatbot-captured leads into Klaviyo and power lifecycle automation from trusted server-side flows. ## Why Connect Klaviyo? Create or update Klaviyo profiles instantly when visitors share email, phone, or consent in chat. Identify visitors by email in Klaviyo and send configured lifecycle events from controlled handoff and lead-capture flows. ## Prerequisites Before you start, make sure you have: * An **active Klaviyo account** with admin access * A **BubblaV Pro+ plan** (required for integrations) * At least one **website** set up in your BubblaV dashboard ## Installation ### Option 1 (Recommended): OAuth from BubblaV Dashboard Go to **Dashboard → Integrations → Klaviyo**. If you have multiple websites, choose the one you want to connect. If you only have one, this step is skipped automatically. Click **Connect Klaviyo**. You are redirected to Klaviyo's OAuth authorize page. Approve the requested scopes for profiles, events, lists, and account metadata. BubblaV saves tokens server-side and marks the integration as connected. ### Option 2: Direct install link Navigate to [BubblaV Klaviyo Integration](https://www.bubblav.com/api/integrations/klaviyo/install) to install. You'll be asked to select a website before the OAuth flow begins. ## What Happens After Connection Once connected, BubblaV loads Klaviyo.js on your website for client-side tracking. This enables: * **Identity tracking** — visitors identified by email in Klaviyo * **Lead sync** — chatbot-captured leads can create or update Klaviyo profiles * **List sync** — synced leads can be added to your configured default Klaviyo list * **Event tracking** — configured lifecycle events can be sent from trusted server-side workflows * **Account metadata** — your Klaviyo account name and ID stored for future sync features ## Manage the Integration ### Disconnect Klaviyo Go to **Dashboard → Integrations → Klaviyo**. Click **Disconnect** to remove the connection. BubblaV deletes stored tokens and stops loading Klaviyo.js. Disconnecting stops all tracking immediately. Data already synced to Klaviyo is not affected. ## Next Steps Use website install guides to ensure widget deployment captures enough lead volume. Customize the chatbot appearance to match your brand. # MCP Servers Source: https://docs.bubblav.com/user-guide/integrations/mcp-servers Connect to Model Context Protocol servers for advanced AI capabilities MCP (Model Context Protocol) servers extend your chatbot with standardized AI capabilities. Unlike custom tools that connect to your APIs, MCP servers provide pre-built tools following an open protocol. ## What is MCP? Model Context Protocol is an open standard for connecting AI systems to external tools and data sources. MCP servers expose: * **Tools**: Actions the AI can perform * **Resources**: Data the AI can access * **Prompts**: Pre-defined conversation templates MCP is an advanced feature. Most users should start with [Integrations Overview](/user-guide/integrations/overview) or [Custom Tools](/user-guide/integrations/custom-tools). ## When to Use MCP vs Custom Tools | Feature | Custom Tools | MCP Servers | | ---------------- | ---------------- | ------------------- | | Setup complexity | Simple | Advanced | | Protocol | HTTP/REST | MCP (SSE over HTTP) | | Best for | Your own APIs | Pre-built AI tools | | Authentication | Built-in options | Server-specific | **Use Custom Tools when:** * Connecting to your own backend * Simple API integrations * Need built-in auth options **Use MCP when:** * Using pre-built MCP servers * Need advanced AI capabilities * Building with MCP ecosystem *** ## Adding an MCP Server Go to **Dashboard** → **Integrations** → **MCP Servers** → **Add Server** MCP Servers Overview

Fill in the server configuration: **Server Name** (required) * A friendly name for this server * Example: "File Browser", "Database Query" **Server URL** (required) * The MCP server endpoint URL using Server-Sent Events (SSE) * Example: `https://mcp.example.com/sse` * Must be accessible over HTTPS If your MCP server requires authentication, add custom headers: * **Header Key**: e.g., `Authorization`, `X-API-Key` * **Header Value**: Your authentication token or key Common examples: * `Authorization: Bearer your-token-here` * `X-API-Key: your-api-key` Save the configuration. The server will connect and expose available tools. *** ## Configuration Examples ### Remote MCP Server Connect to a remote MCP server with authentication: | Field | Value | | ------- | --------------------------------------- | | Name | Custom Server | | URL | `https://mcp.example.com/sse` | | Headers | `Authorization: Bearer your-token-here` | ### Public MCP Server Connect to a public MCP server without authentication: | Field | Value | | ------- | ----------------------------------- | | Name | Public Tools Server | | URL | `https://public-mcp-server.com/sse` | | Headers | (none required) | *** ## Available Tools After connecting, the server's tools appear in your dashboard. Common tool types: * **File operations**: Read, write, list files * **Database queries**: SQL or natural language queries * **Web scraping**: Fetch and parse web content * **API integrations**: Pre-built API connectors Each tool shows: * Name and description * Required parameters * Return type *** ## Managing MCP Servers ### View Connected Servers Go to **Dashboard** → **Integrations** → **MCP Servers** to see: * Connection status * Available tools * Last activity ### Disconnect 1. Find the server card 2. Click the settings icon 3. Select **Disconnect** ### Reconnect If a server disconnects: 1. Check the server is running 2. Verify configuration 3. Click **Reconnect** *** ## Troubleshooting * Verify the server URL is correct and accessible * Check that the server supports SSE (Server-Sent Events) transport * Review authentication headers if required * Ensure the server is running and reachable over HTTPS * Wait for server initialization * Check server logs for errors * Verify server exposes tools correctly * Check network stability and HTTPS connectivity * Verify the server URL is still valid * Review server health and availability * Check authentication headers haven't expired *** ## Security Considerations MCP servers can execute code and access data. Only connect trusted servers. * **Verify sources**: Only use official or audited MCP servers * **Limit access**: Configure minimal permissions * **Monitor activity**: Review tool usage in logs * **Authentication headers**: Store sensitive tokens securely and never expose them in logs * **HTTPS only**: Always use HTTPS URLs to protect data in transit *** ## Next Steps Build simple API integrations Connect popular platforms # Facebook Messenger Source: https://docs.bubblav.com/user-guide/integrations/messenger Connect your Facebook Page to add AI chatbot capabilities to your customer support Transform your Facebook Page customer support with an intelligent AI chatbot that can answer questions, provide support, and engage with your customers automatically 24/7. ## Why Connect Messenger? Customers get immediate answers based on your website's knowledge base AI responds day and night, even when your team is offline Support agents can jump into any conversation from the dashboard All Messenger conversations are logged and searchable AI supports 100+ languages for international customers Answers based on your website's content and documentation ## What Can the Messenger Bot Do? ### Answer Customer Questions Instantly Your customers can ask questions about your products, services, or content directly through Messenger: **Example Questions:** ``` What are your business hours? How do I track my order? Tell me about your return policy What payment methods do you accept? ``` ### Provide 24/7 Support * Responds instantly to common questions * No waiting for business hours * Reduces support ticket volume * Consistent, accurate answers ### Search Your Knowledge Base The bot uses your website's content to provide accurate answers: * Product information * Help articles * FAQ sections * Pricing details * Shipping information ### Human Agent Handoff & Unified Inbox Messenger messages now appear in your **Live Support** unified inbox alongside website widget and other platform conversations. Each conversation shows a Messenger badge so you always know the source platform. When replying to Messenger conversations from the dashboard, be aware of Facebook's 24-hour messaging window. Messages sent more than 24 hours after the customer's last message will be blocked with a clear error message. **How agent replies work:** 1. Go to **Live Support** in your dashboard 2. Find the Messenger conversation (look for the 📘 badge) 3. Click to open and type your reply 4. Your message is sent directly to the customer's Messenger 5. The AI remains paused while you're active in the conversation The AI resumes automatically when you leave the conversation. ## Prerequisites * Facebook Page where you have **admin access** * Active BubblaV account with a website * Website with knowledge base content (crawled pages) ## Setup Steps Go to **Dashboard** → **Your Website** → **Integrations** and find the Messenger card Click **Connect Messenger** to open the Facebook authorization flow You'll be redirected to Facebook: 1. Log in to your Facebook account if prompted 2. Review the permissions requested 3. Click **Continue** to authorize BubblaV If you manage multiple Facebook Pages: 1. Select which page to connect 2. Click **Select** to confirm 3. If you only have one page, it will be connected automatically Return to the BubblaV dashboard. The Messenger integration should now show **Connected** with your page name and ID Send a test message to your Facebook Page to verify the AI responds correctly ## Managing Your Integration ### View Connected Page From the Messenger configuration page, you can see: * Page name and ID * Connection date * Current status ### Disconnect Your Page To remove the Messenger integration: 1. Go to **Dashboard** → **Your Website** → **Integrations** 2. Click **Messenger** → **Configure** 3. Scroll to **Danger Zone** 4. Click **Disconnect Page** 5. Confirm the disconnection **Note:** Disconnecting will stop the AI from responding to messages on your page. ## How Messages Are Processed 1. **Customer sends message** → Message arrives at your Facebook Page 2. **Webhook triggers** → BubblaV receives the message 3. **AI analyzes question** → Your website's knowledge base is searched 4. **Response generated** → AI formulates an answer with sources 5. **Sent to Messenger** → Customer receives the response 6. **Conversation logged** → Message stored in your dashboard ## Facebook Messaging Policies ### 24-Hour Messaging Window Facebook has specific policies about when you can send messages: * **Standard messaging**: Within 24 hours of customer's last message * **After 24 hours**: Only specific message tags are allowed * **Our bot tracks**: We automatically respect the 24-hour window ### Rate Limits * 200 messages per user per hour * Messages are truncated at 2000 characters * Our implementation handles these limits automatically ## Troubleshooting ### Messages Not Being Received 1. **Check webhook status** in Meta Developer Console 2. **Verify Page is subscribed** to messaging events 3. **Check BubblaV logs** for errors in the dashboard 4. **Confirm integration is active** in your settings ### Bot Not Responding 1. **Verify integration is active** in the dashboard 2. **Check your website has crawled content** in Knowledge section 3. **Ensure you're within rate limits** (not exceeding 200 messages/hour) 4. **Test with a simple question** like "What are your hours?" ### OAuth Errors 1. **Verify redirect URI** matches: `https://your-domain.com/api/integrations/messenger/callback` 2. **Check Facebook App permissions** include `pages_messaging` 3. **Try disconnecting and reconnecting** the integration 4. **Ensure you're a Page admin** with proper permissions ### Human Takeover Not Working 1. **Check Live Support is enabled** for your website 2. **Verify agent is active** in the conversation 3. **Look for takeover status** in the conversation metadata 4. **Ensure the AI paused** when agent joined ## FAQ For testing with your own Facebook account, no review is needed. For production use where non-admin users interact with the bot, you may need to submit your Facebook App for review with the `pages_messaging` permission. Currently, each website connects to one Facebook Page. To connect multiple pages, you can create additional websites in your BubblaV dashboard, each connected to a different page. Page access tokens obtained through OAuth don't expire. If you lose access to your Page or the token becomes invalid, simply disconnect and reconnect through the integration settings. The AI uses your website's content to generate responses. To improve answer quality, ensure your website has comprehensive, up-to-date information. You can also add custom content through the Knowledge section. Instagram DM uses the same Messenger API infrastructure. Support for Instagram is planned for a future update. If the AI is unsure or the customer needs complex help, they can be escalated to a human agent. You'll see all conversations in the Live Support dashboard and can jump in anytime. ## Next Steps * Set up your [Live Support](/user-guide/live-support) to monitor conversations * Improve your [Knowledge Base](/user-guide/knowledge) content for better answers * Explore other [Integrations](/user-guide/integrations/overview) to connect more platforms # Newsletter Integration Source: https://docs.bubblav.com/user-guide/integrations/newsletter Grow your audience by collecting newsletter subscribers directly through your chatbot. # Newsletter Integration The **Newsletter** integration empowers your chatbot to proactively gather visitor emails and drive conversions. It supports newsletter subscriptions and optional discount incentives. ## Features * **Newsletter Subscription**: The chatbot can ask visitors to subscribe to your newsletter. * **Discount Codes**: Offer incentives (discount codes) in exchange for visitor contact information to boost sign-ups. * **Configurable**: Enable only the scenarios you need and customize the offers. ## Setup 1. Go to your **BubblaV Dashboard** > **Integrations**. 2. Find the **Newsletter** integration card. 3. Click **Connect**. 4. You will be redirected to the **Configuration** page. ## Configuration ### Newsletter Subscription This is the core feature. * The bot will ask for the visitor's email address and optionally their name when they express interest in subscribing. ### Newsletter Discount Code Enable this to offer a discount code to visitors as an incentive to subscribe. * **Discount Code**: Enter the code you want to give (e.g., `SAVE10`). * **Offer Description**: Describe the offer (e.g., "10% off your first purchase"). The bot will use this information to answer questions like "Do you have any coupons?" or proactively offer the discount if contextually appropriate, asking for an email address before revealing the code. ## Requirements * **Plan**: Available on all plans. # Notion Source: https://docs.bubblav.com/user-guide/integrations/notion Use your Notion workspace as a knowledge source for your AI chatbot Transform your Notion workspace into an intelligent knowledge base for your AI chatbot. Connect pages, docs, and wikis to provide instant answers from content you already maintain. ## Why Connect Notion? Use your existing Notion docs as AI knowledge without duplication Content changes in Notion are automatically detected and synced AI understands context and meaning, not just keywords Choose exactly which pages to include ## Prerequisites * Active Notion workspace with pages you want to use as knowledge * A BubblaV website with an active subscription * Notion OAuth credentials configured in your environment ## Setup Steps Go to **Dashboard** → **Integrations** → **Notion** Click **Connect Notion** and authorize via OAuth Browse your workspace and select pages to sync Content will sync automatically based on your plan's frequency *** ## Content Syncing Notion content is synced automatically according to your plan's crawl frequency: * **Free**: No automatic syncing * **Pro**: Weekly ### Incremental Crawling The integration uses incremental crawling to efficiently update only changed content: * Tracks `last_edited_time` from Notion API * Only fetches and re-processes modified pages * Saves resources and speeds up sync cycles ### Supported Content Types | Block Type | Output | | ---------------- | ---------------------------- | | Headings (H1-H3) | Plain text with markers | | Paragraphs | Plain text | | Bullet lists | `- item` format | | Numbered lists | `1. item` format | | To-do items | `[x]` or `[ ]` format | | Code blocks | Formatted code with language | | Quotes | `> text` format | | Callouts | `> text` format | | Dividers | `---` separator | | Images/Files | `[type]` placeholder | *** ## Selecting Sources After connecting, you can browse and select specific sources: 1. Go to **Dashboard** → **Integrations** → **Notion** 2. Click **Browse Pages** to see accessible content 3. Toggle pages to include or exclude 4. Click **Save Selection** Start with your most important documentation pages and expand from there. Selective syncing keeps your knowledge focused and relevant. *** ## Sync Status Each selected page has a sync status: * **pending**: Waiting to be synced * **syncing**: Currently being processed * **synced**: Successfully synced and up-to-date * **failed**: Error during sync (check error message) View status and last sync time for each source in the integration settings. *** ## Test Your Integration Try these queries on your website: * "What's your return policy?" (if in your docs) * "How do I reset my password?" * "What are your pricing plans?" The AI will search your Notion content and provide accurate answers. *** ## Troubleshooting * Verify you granted access to your workspace during OAuth * Check that you're selecting from the correct workspace * Ensure pages are shared with the integration * Page may have been deleted or moved * You may have lost access to the page * Check error\_message in the integration settings * Try re-syncing the page * Wait for sync to complete (check status) * Verify the page is selected as a source * Check that content has actual text content * Wait for next scheduled sync based on your plan * Verify changes are saved in Notion **Security**: Notion connections use OAuth 2.0 for secure, authenticated access. Your credentials are never stored or shared. # Optimizely Source: https://docs.bubblav.com/user-guide/integrations/optimizely Add the BubblaV widget to your Optimizely Content Cloud site Add the BubblaV AI chatbot to your **Optimizely Content Cloud** (formerly Episerver) site in minutes. Paste one widget snippet and BubblaV starts answering visitor questions from your published content — no code or rebuild required. Optimizely Content Cloud is the CMS formerly known as **Episerver**. This guide covers both. ## Why Add BubblaV to Optimizely? Paste a single snippet into a layout template or block — no SDK or build step. BubblaV crawls your published Optimizely pages and answers from your real content. Answers visitors in Swedish, English, and 30+ languages out of the box. Escalate complex conversations to your team with full chat history. ## Prerequisites * An Optimizely Content Cloud site with **edit and publish** access * A BubblaV account and your site added in the dashboard * Your BubblaV widget snippet (from **Dashboard → Installation**) ## Setup Steps In BubblaV, go to Dashboard → Installation for your site and copy the one-line widget snippet. Choose one of the methods below — all three work on Optimizely Content Cloud. Save and publish your changes so the snippet is live on your site. ### Method 1: Edit a Layout Template (Recommended) Adds the chatbot globally so it appears on every page. 1. Go to **UI Mode → File Manager**. 2. Open your layout template (for example, `Layout.cshtml` or `_Layout.cshtml`). 3. Paste the widget snippet just before the closing `` tag. 4. **Save and publish** the template. ### Method 2: Use a Script Container / HTML Block A no-code option that avoids editing templates. 1. In **Edit Mode**, open the page where you want the chatbot. 2. Add a **Script Container** or **HTML block** to the footer area. 3. Paste the widget snippet (use the full snippet including the ` ``` Search Widget Installation

### What is data-element-id? The `data-element-id` attribute is **required** and tells the widget which HTML element to embed into. The widget will render inside the specified element on your page. **How to use it:** 1. Create a container element in your HTML with an ID: ```html theme={null}

``` 2. Use that same ID as the value for `data-element-id` in your script tag: ```html theme={null} ``` The widget will automatically find the element with the matching ID and render inside it. *** ## How It Works 1. **User types a query**: Search widget captures the input 2. **AI searches your knowledge base**: Uses semantic search to find relevant content 3. **Results appear instantly**: Shows concise answers with source links 4. **User clicks a result**: Jumps directly to the relevant page *** ## Best Practices Put the search widget where users expect to find search functionality—typically in the header or navigation. Icon mode for minimal designs, compact for headers, full mode for search-focused pages. Choose a theme (light or dark) that matches your website's design. Try common queries your visitors might ask to ensure good results. *** ## Troubleshooting * Check the installation script is correct * Verify the container element with the ID specified in `data-element-id` exists on the page * Ensure `data-element-id` matches the ID of your container element * Check browser console for errors * Ensure your site ID is correct * Verify your knowledge base has content * Check that pages are crawled and indexed * Try different search queries * Check if your site's CSS is overriding widget styles * Try using a different display mode * Contact support for custom styling help *** ## Next Steps Ensure your content is indexed for good search results Customize your chatbot appearance # Settings Source: https://docs.bubblav.com/user-guide/settings Configure your website settings and preferences Manage your website settings, notifications, and team access all in one place. Bot behavior and custom instructions are now configured in the **Behavior** page in the sidebar. See [Human Handoff Scenarios](/user-guide/human-handoff) for details. Settings Overview

## Accessing Settings Go to [bubblav.com/dashboard](https://www.bubblav.com/dashboard) Click on the website you want to configure Click **Settings** in the sidebar menu *** ## General Settings Basic configuration for your website. ### Website Name The display name shown in your dashboard. This is for your reference only—customers don't see this. ### Website URL The primary domain where your chatbot is installed. Used for: * Crawling your website content * CORS security (widget only loads on this domain) * Analytics tracking Changing the URL may affect your widget installation. Update your embed code if needed. ### Allowed Domains Control which domains can embed and use this chat widget. #### Allow All Domains (Recommended) By default, **Allow all domains** is enabled. This means your widget will work on any domain without restrictions. This is the best option if you: * Use **Framer**, **Shopify**, **Webflow**, or similar platforms that may add preview or custom domains over time * Have multiple domains or subdomains pointing to the same site * Are unsure which domains will serve your widget in the future #### Restrict to Specific Domains If you want tighter control, disable **Allow all domains** to restrict the widget to specific domains only. Once disabled, you can add allowed domains: 1. Enter the domain in the input field (e.g., `stage.example.com`) 2. Supports wildcards like `*.example.com` for all subdomains 3. Click **Add** to add it to the list 4. Click **Save Changes** to apply When restricted mode is on, the primary domain (website URL) and your dashboard domain are always allowed automatically. If you restrict domains and your widget stops working on a domain, go to Settings → Allowed Domains, toggle **Allow all domains** on (or add the missing domain), and save. *** *** ## Danger Zone Irreversible actions that affect your website. ### Delete Website Permanently removes: * All conversations * Knowledge base content * Settings and integrations * Team member access This action cannot be undone. Export your data first if needed. At the bottom of Settings Opens confirmation dialog Type the exact website name to confirm Click **Delete Permanently** *** ## Troubleshooting * Check your internet connection * Ensure you clicked "Save Changes" * Refresh the page and try again * Check browser console for errors * Check spam/junk folder * Verify email address is correct * Resend the invitation * Ask them to add [notifications@bubblav.com](mailto:notifications@bubblav.com) to contacts * Verify email address is correct * Check spam folder * Enable browser notifications in Settings * Check notification toggles are enabled *** ## Next Steps Configure bot instructions and human handoff Customize appearance Track performance # Team Management Source: https://docs.bubblav.com/user-guide/team Invite callers to collaborate on your chatbots BubblaV enables you to invite team members to help manage your chatbots, knowledge base, and customer conversations. Team management is **website-specific**, meaning you invite members to specific websites rather than your entire account. ## Inviting Team Members Team member limits depend on your subscription plan. Free is limited to 1 user (Owner). Pro allows 3 members. 1. Open the specific website you want to share from your Dashboard. 2. Navigate to the website's main dashboard page (overview). 3. Locate the **Team Members** section on the right side of the page. 4. Click **Invite Member**. 5. Enter their **Email Address**. 6. Click **Send Invitation**. The user will receive an email with a unique link to join your team. Team management is **website-specific**. Each website has its own team members. When you invite someone, they get access to that specific website only. ## Team Member Access All invited team members have full access to manage the website, including: * Editing chatbot settings and design * Managing knowledge base and content * Viewing conversations and analytics * Using live support features * Managing integrations Only the website **Owner** can: * Manage billing and subscription * Delete the website * Invite and remove team members ## Managing Invitations ### Pending Invitations Once sent, an invite appears in the "Pending" list. You can: * **Resend**: If the user didn't receive the email. * **Revoke**: Cancel the invitation before they accept. ### Accepting an Invitation 1. The invitee clicks the link in their email. 2. They will be prompted to log in or sign up. 3. Once authenticated, they must click **Accept Invitation**. 4. They will be redirected immediately to the website dashboard. ## Removing Members To remove access for a team member: 1. Go to the **Team Members** section. 2. Find the user in the list. 3. Click the **Remove** (trash icon) button. 4. Confirm user removal. Access is revoked immediately. # Testing Source: https://docs.bubblav.com/user-guide/testing Preview and test your chatbot before going live Before adding the chatbot to your public website, it's important to test its responses and behavior. ## Testing Environments There are two ways to test your chatbot within the dashboard: the **Design Preview** for visuals and the **Dedicated Test Page** for behavior. ### 1. Design Preview The **Design** page features a real-time preview of your widget's appearance. 1. Navigate to your website dashboard. 2. Click **Design** in the sidebar. 3. The right side of the screen shows a fully interactive preview. **Best for:** Checking visual changes like colors, positioning, and welcome messages. ### 2. Dedicated Test Page For evaluating the chatbot's **intelligence and responses**, use the dedicated Test page. 1. Click **Test** in the sidebar menu. 2. This opens a full-screen chat interface with a **Debug & Improve** side panel. **Features of the Test Page:** * **Full-screen chat**: Focus entirely on the conversation without distraction. * **Debug & Improve panel**: A side panel (desktop only) that shows confidence scores, sources, and improvement tips for each bot response. * **Confidence monitoring**: Every bot response is analyzed and given a confidence score — helping you quickly spot weak answers. * **Quick Q\&A creation**: Add Q\&A entries directly from the test page when the bot struggles with a question. * **Reset Chat**: Start a new conversation by clicking "New Chat". ## Debug & Improve Panel The **Debug & Improve** side panel (visible on desktop) gives you real-time insight into how the bot answered each question. ### Confidence Scores After each bot response, the panel displays a confidence indicator: | Level | Score | Meaning | | ---------- | --------- | ----------------------------------------------------------------------------------------- | | **High** | 70%+ | The bot found relevant content and answered confidently. | | **Medium** | 40–69% | The bot found some content but may not have fully answered. Consider adding a Q\&A entry. | | **Low** | Below 40% | The bot could not find enough information. Adding a Q\&A entry will help. | ### Sources The panel lists the **sources** the bot used to generate its answer. You can click any source to open it and verify the content is accurate and up to date. ### Low-Confidence Alerts When the bot's confidence drops below 70%, a low-confidence alert appears below the response. On mobile devices, this alert appears inline; on desktop, the side panel highlights the issue. ### Quick Actions For medium and low-confidence responses, a **"Add Q\&A for this question"** button appears in the panel. Clicking it opens a dialog pre-filled with the question you asked, so you can quickly provide the correct answer. ## What to Test ### Knowledge Accuracy Ask questions about your business to ensure the AI has learned your content correctly. * **Product details**: "What is the price of X?" * **Policies**: "What is your return policy?" * **Support**: "How do I contact support?" Use the confidence score and sources in the Debug panel to verify each answer. If the score is low or the sources are wrong, update your content. ### Behavior Check that the bot adheres to your settings: * Does it use the correct tone? * Does it escalate to human support when needed? * Does it capture lead information? ### Debugging If the bot says "I don't know" or gives wrong information: 1. Check the **confidence score** and **sources** in the Debug panel to understand why. 2. Add missing information to the **Knowledge Base**. 3. Use the **"Add Q\&A"** button in the panel to provide a direct answer for that specific question. 4. Use the **Q\&A** section or resolve **Content Gaps** for broader improvements. ## Best Practices To learn how to get the most out of testing and continuous improvement, check out our [Best Practices](/user-guide/best-practices) guide which covers the full cycle of crawling, testing, adding knowledge, and monitoring. # Widget Design Source: https://docs.bubblav.com/user-guide/widget-design Customize the look and feel of your chatbot widget Make your chatbot feel like a natural part of your website. Customize colors, position, branding, and messaging to match your brand perfectly. ## Accessing Design Settings Go to [bubblav.com/dashboard](https://www.bubblav.com/dashboard) Click on the website you want to customize Click **Design** in the sidebar menu Widget Design Overview

*** ## Design Options The design settings are organized into collapsible sections to help you focus on specific parts of the widget. ### 🎨 Color Palette Presets Choose from professionally designed color themes if you want a quick start. **Automatic Color Detection**: When you add a new website, BubblaV automatically analyzes your site's colors and applies a matching theme to your widget. **Manual Color Extraction**: You can also extract colors from any website URL: 1. Expand the **Color Palette Presets** section 2. Enter a website URL in the text field at the bottom 3. Click **Extract Colors** to analyze and apply the color scheme *** ## Basic Settings Configuration for the widget's general behavior and appearance. ### General * **Show Expand Button**: Allow users to expand the chat widget to a larger size. * **Show "Powered by" branding**: Toggle the BubblaV branding (available on Pro+ plans). ### Dimensions Customize the size of the widget window: * **Widget Width**: Default is `400px`. * **Widget Height**: Default is `650px`. ### Bubble Appearance Customize the floating chat button: * **Bubble Color**: The background color of the chat button. * **Bubble Icon Color**: The color of the icon inside the button. ### Positioning Choose where the chat button appears on Desktop and Mobile: * **Bottom Right**: Standard convention. * **Bottom Left**: useful if you have other widgets on the right. *** ## Screen Configuration The widget is divided into three main screens, each with its own customization options. ### 🏠 Home Screen The first screen users see when they open the widget. * **Welcome Message**: The greeting text displayed at the top. * **Background Style**: Solid color or gradient. * **Chat Suggestions**: Quick-start questions to guide users. ### 💬 List Screen (Messages) The screen displaying the history of conversations. * Customize the title, background colors, and unread indicator settings. ### 💭 Chat Screen The active conversation interface. * **Bot Identity**: Set the Bot Name and upload a custom Avatar. * **Colors**: Customize message bubbles (User vs Bot), text colors, and the input area. * **Placeholder Text**: The text shown in the message input field before typing. *** ## Advanced Settings ### Exclude URLs Prevent the widget from appearing on specific pages: 1. Expand the **Advanced Settings** section. 2. Enter the URLs where you want to hide the widget (one per line). 3. You can use specific paths like `/checkout` or full URLs. ### Product Card Layout Control how product cards are displayed in chat responses: **Vertical Layout** (default): * Product cards stack vertically. * Each card takes full width. * Best for detailed product information. **Horizontal Layout**: * Product cards display side-by-side (carousel). * Users can scroll horizontally to see more products. * Compact view, good for showing multiple options. *** ## Live Preview The design page includes a real-time preview: * **Desktop view**: See how it looks on larger screens. * **Mobile view**: Toggle to see mobile responsiveness. * **Inline Editing**: Click on any text, button, or color in the preview to edit it directly. Live Widget Design and Preview

For a full-screen testing experience, use the dedicated **Test** page available in the dashboard sidebar. This allows you to test the chat behavior without the design tools cluttering the view. ### ⚡ Inline Editing The fastest way to customize your widget is by clicking on elements directly in the live preview. * **Text Editing**: Click on titles, labels, or names to edit them in-place. * **Color Picking**: Click on any colored area (like the header or bubble) to open the color picker. * **Images**: Click on the bot avatar or logo to update their URLs. * **Layout Toggles**: Switch between product card layouts by clicking on the cards. Clicking on an element opens an inline editor. Make your changes and click **Save** to apply them, or **Cancel** to revert. *** ## Saving Changes Inline edits are saved to your history as you confirm them. You can use Undo/Redo to manage changes. Sidebar changes are not live until you save! Check your changes in the live preview. Click **Save** at the bottom of the form. Reload your website to see the updates — changes appear within 1 minute. *** ## Design Best Practices Your brand colors are automatically extracted when you add a website. You can also manually extract colors from any URL in the Color Palette Presets section, or set your primary brand color for the Bubble and User Messages manually. Ensure high contrast between text and background colors. Dark text on light backgrounds is generally the most readable. If you enable the **Expand Button**, check that the larger widget size doesn't cover important content on your site. Customize the **Welcome Message** on the Home Screen to sound friendly and helpful. *** ## Troubleshooting * Ensure you clicked **Save**. * Reload the page — changes appear within 1 minute. * If still not showing, clear your browser cache and reload. * Try changing the **Positioning** (Left vs Right). * Use **Advanced Settings > Exclude URLs** if it shouldn't appear on certain pages. *** ## Next Steps Preview your chatbot in action Add the widget to your website