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 on visitor request (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) * Flows (visual scenario builder): smart triggers, AI handoff routing, form notifications * 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). Only AI responses are counted. * **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. # Make Your Bot Collect Leads, Quotes & Reviews Source: https://docs.bubblav.com/user-guide/configure-bot-leads-quotes-reviews Configure your chatbot to handle "Get Free Quote", share review links, and collect leads Most "can the bot do X?" questions are answered by three features working together: **Forms**, **Q\&A**, and **Integrations**. This page maps the most common requests to the exact setup steps. Not sure where to start? You can also open the [help assistant](/user-guide/help-assistant) from the **question-mark icon** in the top menu of your dashboard and ask in plain English — e.g. *"How do I make the bot give customers a review link?"* *** ## "I want the bot to handle 'Get Free Quote' requests" Use a **Form** so the bot collects the visitor's details inside the chat instead of sending them elsewhere. **Dashboard** → select your website → **Flows** → open a flow (or create one) → add a **Show form** node → **Create form**. Add the fields you need (e.g. Name, Email, Company, Service, Message). Use something like: *"Show this form when a visitor asks about pricing, a quote, an estimate, a free quote, or wants to discuss business terms."* Saving it creates an active companion flow that shows the form when the intent matches. If you placed the form in a flow you built yourself, switch it to **Active** — the editor autosaves. (The auto-created companion flow is already active.) See [Forms](/user-guide/forms) for the full field list and the ready-made **Quote Requests** example. Connect a [CRM & Marketing integration](/user-guide/integrations/attio) (Attio, HubSpot, Klaviyo) so every submitted quote becomes a lead in your pipeline automatically. *** ## "I want the bot to give customers a review link" Two simple options: Best for a single review link. Add a Q\&A whose question covers review phrasings ("how do I leave a review", "review link", "rate my order") and whose answer contains the exact URL. Best when you want to collect the review content in-chat. Use the **Product Review** form example so the bot gathers feedback before linking out. For the Q\&A approach, **Dashboard** → your website → **Knowledge** → **Q\&A** → **Add Q\&A**. Set: * **Question:** *"How do I leave a review / where is the review link?"* * **Answer:** *"We'd love your feedback! Leave a review here: [https://your-review-url.com](https://your-review-url.com)"* *** ## "I want the bot to collect email leads" Combine a **Form** (to capture email + consent) with a **CRM & Marketing integration** (to sync the lead): * Create a "Newsletter Signup" or "Contact Me" form with an Email field. * Connect [HubSpot](/user-guide/integrations/hubspot), [Klaviyo](/user-guide/integrations/klaviyo), or [Attio](/user-guide/integrations/attio) so submissions flow into your marketing tool. *** ## Related configuration The bot answers from your website + knowledge base. Add pages, files, and Q\&A. Edit the greeting, tone, and persona in Widget Design. Add Q\&A for exact phrasings. Add the chatbot to your site with one script snippet — no coding required. Route complex questions to your team with human handoff. *** ## Tips for reliable answers * **Write Q\&A questions the way visitors actually ask** (e.g. "free quote", not "pricing enquiry form"). * **Keep answers short and actionable** — lead with the link or the next step. * After adding Q\&A, give the bot a moment to index the new entry before testing. # Flows: Build Multi-Step Chatbot Scenarios Visually Source: https://docs.bubblav.com/user-guide/flows Compose chatbot scenarios on a visual canvas — match visitor intent, collect answers, run tools, call webhooks, notify your team, and hand off to a human — without writing code. Sometimes a conversation needs more than a single AI answer: collect a few details, look something up in your systems, then act on it. **Flows** is a visual builder where you compose those scenarios as a graph of steps — a trigger that starts the flow, then condition and action nodes that run in order. Two examples of what a flow can do: * **Multi-source answer** — a visitor asks a question → the flow searches your Discourse forum and your CRM via Custom Tools → the AI aggregates the results into one answer. * **Ticket intake** — the flow asks for email, company, and the problem → submits everything to your webhook → notifies your team. Flows list — flow cards with trigger type, run count, and active toggle

Flows list — flow cards with trigger type, run count, and active toggle

Flows consolidate four older features into one canvas: * **Smart Triggers** → a `page_behavior` trigger + `send_message` node * **Human handoff scenarios** → a `visitor_intent` trigger + `request_human` node * **Forms** → embedded in a flow with a `show_form` node * **Cart Recovery** → a `cart_abandoned` trigger + `delay` + `cart_recovery_touch` nodes The old Smart Triggers, Forms, and Cart Recovery pages redirect here — everything is built and edited in the flow editor. Flows require a **Pro plan**. Messages a flow sends don't consume your monthly message quota. ## How Flows work 1. A **trigger** starts a run — either a visitor message that matches your intent description, or an event like a form submission. 2. The flow walks the graph node by node: asking questions, branching on conditions, calling tools and webhooks, sending messages. 3. While a flow is running or waiting for the visitor's answer, it **owns the conversation** — the visitor's replies resume the flow instead of going to the AI. 4. The run ends when the graph ends, when an **AI respond** node hands the collected results to the chatbot for a final answer, or when the visitor cancels ("cancel", "stop", "never mind"). ## Triggers Every flow has exactly one trigger — the first node on the canvas. | Trigger | Starts a run when… | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `visitor_intent` | A visitor's chat message matches your natural-language intent description (e.g. "wants a callback", "asks about order status"). The AI scores each active flow's intent and the best match above the threshold runs. | | `page_behavior` | The widget detects page behavior — time on page, exit intent, or (Shopify) cart threshold / product page — and the flow opens the conversation proactively. | | `form_submitted` | A visitor submits one of your BubblaV forms. | | `conversation_started` | A new conversation is created. | | `conversation_rated` | A visitor rates a conversation (thumbs up/down). | | `handoff_requested` | A live-support ticket is created. | | `lead_captured` | A visitor's email is captured. | | `cart_abandoned` | (Shopify) A synced abandoned checkout starts a run — the sync runs every 15 minutes. Payload exposes `{{trigger.email}}`, `{{trigger.recoveryUrl}}`, `{{trigger.totalPrice}}`, `{{trigger.currency}}`, `{{trigger.items}}`. | | `inbound_webhook` | An external system POSTs to the flow's secret webhook URL — for events from your own backend. | `visitor_intent` and `page_behavior` are the **chat triggers**: the flow runs inside the conversation and can talk to the visitor. The others are **event triggers** that run in the background. Event triggers that carry a conversation (`form_submitted`, `conversation_started`, `handoff_requested`) can still message the visitor; `conversation_rated`, `lead_captured`, `cart_abandoned`, and `inbound_webhook` have no conversation, so chat nodes aren't allowed under them — the editor enforces this. ### Page behavior triggers A `page_behavior` trigger turns the flow into a proactive opener: the widget watches the visitor's page behavior and, when it matches, the flow starts a conversation with an AI-personalized message. | Subtype | Fires when… | | ------------------- | -------------------------------------------------------------------------------------- | | `time_on_page` | The visitor has spent a set dwell time on a matching page. | | `exit_intent` | The visitor is about to leave (mouse toward the top on desktop, tab switch on mobile). | | `cart_threshold` | (Shopify) The cart total crosses your configured amount. | | `product_page` | (Shopify) The visitor dwells on a product page. | | `new_visitor` | The page loads during the visitor's first session on your site. | | `returning_visitor` | The page loads for a visitor returning after their first session (\~30 min window). | Config: `subtype`, `urlMatchType` (`exact`/`contains`/`prefix`/`regex`), `urlPatterns`, `dwellSeconds`, `cooldownMinutes`, `sortOrder`, plus `config.cart_threshold` for e-commerce subtypes (`threshold_cents`, `min_cart_cents`, `currency`). `new_visitor` and `returning_visitor` fire on page load and ignore `dwellSeconds`. When the static greeting message is enabled it owns the first pageview — a `new_visitor` flow then fires on the next page view or SPA navigation once the greeting is dismissed or no longer showing. Pair it with a `send_message` node for the opener — or `generate_text` → `send_message` when you want the AI to write the opener from instructions. ## Node catalog Nodes are the steps of your flow. Drag them from the palette onto the canvas and connect them. Node configuration panel — a Collect input node's question and expected value

Node configuration panel — a Collect input node's question and expected value

| Node | What it does | Settings (`data`) | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `trigger` | Entry point — exactly one per flow. | `triggerType`, plus `intent` (required for `visitor_intent`) | | `condition` | Branches the flow. Its outgoing edges are labeled `true`/`false`. | `mode: 'context'` → `field`, `op` (`equals`, `not_equals`, `contains`, `exists`, `not_exists`), `value`; or `mode: 'ai'` → `question` answered against collected variables | | `delay` | Parks the run until a timer fires, then resumes on the next node. Visitor messages during the wait go to the AI, not the flow. | `minutes` | | `collect_input` | Sends a question as a bot message and waits; the visitor's reply is stored in a variable. | `question`, `variable`, `expected` (optional, e.g. `email`, `phone` — the AI checks the reply contains a usable value and re-asks once if not) | | `show_form` | Sends a bot message with one of your forms embedded and waits for the submission. | `formId`, `introMessage`, `variable` | | `run_tool` | Runs one of your Custom Tools or MCP tools and stores the result. | `toolId`, `args` (values can be literals or `{{var}}`), `variable` | | `send_message` | Sends a bot message. | `message` | | `call_webhook` | Calls an external URL with the same SSRF and timeout guards as Custom Tools; optionally signs the request (HMAC) and stores the response. | `url`, `method` (`POST`/`GET`/`PUT`/`PATCH`), `headers`, `body`, `secret`, `variable` | | `send_email` | Sends a transactional email. | `to`, `subject`, `body` | | `notify_team` | Sends a notification to your website's team members (bell, push, and email per their preferences). | `title`, `message` | | `request_human` | Creates a live-support ticket so a teammate can take over. | `message` | | `ai_respond` | **AI answer — terminal, chat flows only.** The chatbot answers the visitor using the knowledge base and all collected variables. Must be the last node. | `instructions` (optional) | | `generate_text` | Generates text mid-flow into a variable — e.g. summarize the conversation for a `send_email` body. Includes the transcript automatically. | `instructions` (required), `variable` (required) | | `cart_recovery_touch` | Sends an AI-written recovery message for the run's abandoned cart — chat widget if the visitor is reachable (first touch only), else an unsubscribe-compliant email with a one-click recovery link. Skips when the cart is recovered, expired, or suppressed. | `aiInstructions` (optional), `discountCode` (optional) | ## Variables and `{{var}}` interpolation Every value a flow collects — visitor replies, form submissions, tool results, webhook responses — is stored in a named **variable**. Use `{{variable}}` (or a nested path like `{{order.status}}`) inside any message, question, webhook body, or email to insert the value. The trigger's payload is available as `{{trigger}}`. Missing variables resolve to an empty string. ## Build a flow In the dashboard, open your website and go to **Flows**, then click **New Flow**. Give the flow a name and choose what starts it — a visitor intent or an event. Drag nodes from the palette and connect them. Click a node to configure it in the side panel — pick forms and tools from your website's existing ones, or create a new one from the panel without leaving the editor. The editor autosaves as you work (watch for "Saving…"/"Saved" in the header). Open the **Test** panel to run the flow — chat with it like a visitor, or fire a test event for event triggers. When the test run looks right, switch the flow to **active**. New flows are saved inactive — they never run until you turn them on. Flow editor — node palette, canvas with connected nodes, and test button

Flow editor — node palette, canvas with connected nodes, and test button

Stuck? Click **Ask BubblaV** in the editor toolbar and describe the scenario — the assistant can draft the flow on your canvas for you. ## Test before activating The editor's **Test** panel runs the flow without touching real conversations. Clicking **Test** saves any pending canvas edits first, so the run always exercises what you see. * For `visitor_intent` flows, a chat-style transcript lets you play the visitor — send messages, answer the flow's questions, and watch each step's status. The panel reports the intent-match score your message would get in production, and typing "cancel" or "stop" exercises the same escape hatch visitors have. `show_form` nodes render the real form inline — submitting it resumes the run, and an `ai_respond` node previews the actual AI reply. * For event triggers, fire a test event with a JSON payload preview. If the run then waits on a chat node (`collect_input`, `show_form`), the input row switches to a chat box so you can continue the run like a visitor. * While a test runs, the canvas highlights the executed path — green for completed nodes, red for failures, and a pulsing amber ring on the node the run is waiting on. * Each step in the trace expands to show its exact input and output JSON, so you can see what data flowed between nodes. Steps that touch the outside world (`run_tool`, `call_webhook`, `send_email`, `notify_team`, `request_human`, `cart_recovery_touch`) carry a `live` badge. Test runs execute **real side effects** — tools run, webhooks are called, emails are sent. Only message delivery is simulated (nothing is sent to a visitor). Point test webhooks at a service like webhook.site if you don't want to hit production endpoints. Test panel — visitor transcript and per-step status

Test panel — visitor transcript and per-step status

## Runs and history Every execution is recorded as a **run**. Open a flow's **Runs** page to see each run's status (`running`, `waiting`, `completed`, `failed`, `cancelled`), when it started, and a per-step trace showing every node's input, output, or error — the fastest way to debug a flow that didn't behave as expected. Flow runs — a completed run with its per-step trace expanded

Flow runs — a completed run with its per-step trace expanded

A run that waits more than 24 hours for a visitor reply is cancelled automatically — timer waits on a `delay` node are exempt and resume when the timer fires. A visitor can always escape a waiting flow by saying "cancel" or "stop" — the conversation then goes back to the normal AI. ## Debug and troubleshoot When a flow misbehaves, work through it in this order: 1. **Reproduce in the Test panel.** The transcript, intent-match score, and canvas highlight show exactly which path executed. Expand each step's input/output to see the data it received and produced. 2. **Check the Runs page.** Every real and test execution is recorded. A `failed` step shows its error inline; a `waiting` run means the flow is parked on a `collect_input` or `show_form` node expecting a visitor reply. 3. **Common causes:** * *Flow never triggers* — the visitor's phrasing doesn't match the intent closely enough. Test the exact message in the panel; if the score is below the 0.6 threshold, broaden the intent description. * *Flow stops mid-run* — a `waiting` status means it's waiting for input, not broken. Check whether the visitor escaped with "cancel"/"stop" (status `cancelled`) or the run timed out after 24h. * *Webhook/tool step failed* — expand the step output for the HTTP status or error. Test webhooks against a service like webhook.site first. * *AI reply looks wrong* — `ai_respond` composes from the collected variables; check the step inputs to confirm the right values were captured, and tighten the node's `instructions`. ## Example flows Six recipes to copy — each is a chain of nodes you can build in a few minutes. ### Lead qualification `visitor_intent` ("interested in pricing / wants a quote") → `collect_input` email (`expected: email`) → `collect_input` company → `call_webhook` to your CRM → `notify_team` → `send_message` confirmation. The visitor asks about pricing, the flow collects their email and company, posts the lead to your CRM, pings your team, and confirms to the visitor — all inside one conversation. ### Proactive opener (Smart Trigger) `page_behavior` (`time_on_page`, 30s on `/pricing*`) → `generate_text` → `send_message` → `ai_respond`. The widget watches visitors dwell on your pricing page, opens the chat with an AI-written opener, then lets the chatbot answer follow-ups. This is the old Smart Triggers pattern as a flow. ### Human handoff `visitor_intent` ("wants to speak to a human / asks for sales") → `collect_input` email → `request_human`. The old handoff-scenario pattern: the flow matches the visitor's intent, optionally collects contact details first, then creates a live-support ticket so a teammate can take over with the full transcript attached. See [Human handoff](/user-guide/human-handoff). ### Form in a flow `visitor_intent` ("wants a demo / wants to sign up") → `show_form` (your signup form) → `send_message` confirmation. Instead of the AI deciding when to surface a form, the flow controls it: the form renders in chat at exactly the step you place it, and the submission lands in a variable you can pass to a webhook or email downstream. ### Ticket intake (event) `inbound_webhook` → `condition` on `{{trigger.priority}}` → `send_email` to support / `notify_team`. Your backend POSTs a ticket payload to the flow's webhook URL; the flow routes high-priority tickets to the support inbox and notifies the team about the rest. Event triggers have no visitor conversation, so only non-chat nodes are used. ### Cart recovery (Shopify) `cart_abandoned` → `delay` 60m → `cart_recovery_touch` → `delay` 24h → `cart_recovery_touch`. Every synced abandoned checkout starts a run: the flow waits an hour, sends an AI-written recovery message (chat widget if the visitor is still around, email otherwise), waits a day, then sends one follow-up. A completed purchase cancels the run mid-wait. See [Shopify](/user-guide/integrations/shopify#ai-abandoned-cart-recovery). ## Best practices * **Write intents like a visitor would phrase them** — "wants to speak to sales", not "sales intent trigger". * **Collect one thing per `collect_input`** — short questions get better answers, and each answer lands in its own variable. * **Set `expected` when the answer has a shape** — `email`, `phone`, `order number` — so the flow re-asks once instead of storing "I don't know". * **End chat flows with `ai_respond` or `send_message`** — don't leave the visitor hanging on a silent last step. * **Test with real-looking data** — `run_tool` and `call_webhook` hit your real endpoints even in test runs. ## Plans & limits Flows require a **Pro plan** or higher. There's no limit on the number of flows per website. Messages a flow sends don't consume your plan's message quota. See [Billing & Plans](/user-guide/billing) for details. ## Related The webhook tools a flow can call with `run_tool`. Build the forms a `show_form` node embeds in chat. What happens after a `request_human` node creates a ticket. How the chat widget looks when a flow opens with your message. # Forms Source: https://docs.bubblav.com/user-guide/forms Collect structured data from visitors through AI-powered forms Forms let your chatbot collect structured data from visitors—like feedback, contact details, or survey responses—directly inside the chat. Instead of redirecting visitors to external pages, a flow presents the form at exactly the step you place it. Forms are now part of **Flows**. The standalone Forms page redirects to the flows list — create and edit forms inside a flow's `show_form` node, which shows the form in chat and stores the submission in a variable. See [Flows](/user-guide/flows). ## How It Works 1. You **create or pick a form** inside a flow's `show_form` node 2. The form's **AI Instructions** become the intent of a companion `visitor_intent → show_form` flow that's created automatically — or you can place the form in any flow you build yourself 3. When a visitor message matches the intent, the form **appears in the chat** and the flow waits 4. The visitor **fills it out and submits** — the submission is stored in a variable you can pass to later nodes (webhooks, emails, tools) The AI matches each visitor message against your AI Instructions (the companion flow's intent). Write clear, specific instructions so the form triggers at the right moment. ## Detected Forms When BubblaV crawls your website, it detects lead and contact forms on your pages and imports each one with two flows: an **active companion flow** (`visitor_intent` built from the detected AI instructions → `show_form`) that shows the form in chat, and an **inactive notification flow** (`form_submitted` → team notification) you can activate in **Flows** (requires Pro). To keep things focused, at most **5 forms per website** are ever auto-imported; you can always create additional forms manually inside a flow's `show_form` node. *** ## Creating a Form Go to **Dashboard** → select your website → **Flows**, open a flow (or create one), and add a **Show form** node — its side panel lets you pick an existing form or create a new one without leaving the editor. 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") — they become the intent of the form's companion flow 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. Saving them creates (or updates) a companion flow — a `visitor_intent` trigger using your instructions, wired to a `show_form` node — so the wording is exactly what the intent matcher scores visitor messages against. This is the most important part of form configuration—if the instructions are unclear, the form won't surface at the right moment. ### 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 best-matching intent wins. Editing the instructions later updates the companion flow's intent automatically. *** ## Enabling and Disabling Forms Forms are **enabled by default** when created, and there is no toggle in the dashboard — the `bubblav_update_form` MCP tool can disable one. Disabling a form deactivates its companion flow and makes any `show_form` node that references it fail at run time ("not found or disabled"), so leave forms enabled. *** ## Viewing Submissions Every form submission is stored. To see them, open the flow that uses the form, click the `show_form` node, and click **View submissions** — a dialog lists the latest 50 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 Open the flow that uses the form, click the `show_form` node, and click **Edit form** — the form builder opens in place and changes save automatically. ### Delete a Form There's no delete button in the dashboard — use the `bubblav_delete_form` MCP tool instead. Deleting a form also deletes all submissions for that form. Consider exporting important data before deleting. *** ## How Visitors Experience Forms When a flow reaches a `show_form` step: 1. The flow 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 — they become the companion flow's intent. 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** — a disabled form deactivates its companion flow * Review your **AI Instructions** — they are the companion flow's `visitor_intent`; make them more specific * Test the phrasing in the flow editor's **Test** panel and check the intent-match score * Ensure the form has at least one field * Check if multiple forms have overlapping AI instructions — the best-matching intent wins * Make each form's instructions distinct and specific to its purpose * Open the flow, click the `show_form` node, and check **View submissions** * Verify the form is enabled * Check your email notifications settings *** ## Next Steps Embed forms in scenarios with show\_form nodes 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** | On visitor request | Yes (incl. AI intent routing) | | **Email to visitors** | Yes | Yes | | **Live Support** | - | Yes | | **Flows** (smart triggers, forms, AI handoff) | - | 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 Custom Instructions on the Behavior page Match your brand colors and style Website details, notifications, team access ### 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 # In-Dashboard Help Assistant Source: https://docs.bubblav.com/user-guide/help-assistant Ask the BubblaV Assistant to configure your chatbot or update settings for you — without leaving your dashboard Not sure how to set something up? The **BubblaV Assistant** is an inline help chat built into your dashboard. Ask how to configure your bot in any language you like, and get answers right where you're working — no need to open a separate tab or dig through docs. The assistant can also **update settings for you** — it doesn't just answer questions, it can make changes directly, so you don't have to hunt for the right toggle. ## Where to Find It You can open the BubblaV Assistant from two places: * The **Assistant** on the **Dashboard Home page** — available as soon as you log in. * The **question-mark icon** in the workspace header on any website page. On the Dashboard Home page. Or, inside a website page, click the question-mark icon in the top header. Type in any language — ask how to configure something, or ask the assistant to update a setting for you. For changes the assistant makes on your behalf, review the summary and confirm before it's applied. The first time you open a website page, a small nudge points out the help icon. Dismiss it, or simply open the assistant — it won't show again. ## What to Ask (and Do) The assistant is tuned for setup and configuration. It can both answer questions and apply changes, such as: * "How do I make the bot collect leads?" * "Add a review link to my chatbot." * "Turn on lead collection for the 'Get Free Quote' button." * "Connect my Google Business integration." * "Update my chatbot's greeting message." For the full mapping of common requests to setup steps, see [Make Your Bot Collect Leads, Quotes & Reviews](/user-guide/configure-bot-leads-quotes-reviews). ## How It Works * The assistant opens as a **side panel** that stays in view as you scroll — your page remains visible alongside it. * It's powered by the same BubblaV chatbot, answering from BubblaV's documentation and your setup. * When you ask it to change a setting, it performs the update through the dashboard — no manual clicking required. * Close it with the **X** or press `Esc`. Think of it as a guided helper for the dashboard: ask where something is, how to enable a feature, or just tell it to make the change — then follow along in the same window. ## Credits Each BubblaV account gets **100 free assistant credits per month**. These assistant credits are **separate from your monthly message quota** — using the assistant does not count against the messages your chatbot uses with visitors. When you run out of free credits for the month, the assistant will let you know and point you to alternative ways to get help until your credits reset on the first of the next month. ## Next Steps Set up your first website Common bot setup walkthroughs # Human Handoff Source: https://docs.bubblav.com/user-guide/human-handoff Route conversations to your team with a visitor-intent flow # Human Handoff Route conversations to a human teammate when the visitor's intent calls for it — sales inquiries, enterprise pricing, or anything you describe in natural language. Handoffs are built as a **Flow**: a `visitor_intent` trigger that matches what the visitor asks, followed by a `request_human` node that creates a live-support ticket for your team. ## Plan Availability This feature is available on **Pro** plans. ## Setting Up a Handoff Flow 1. Navigate to **Flows** in your dashboard and click **New Flow** 2. Pick the **Visitor intent** trigger and describe when to hand off in natural language — e.g. "wants to speak to sales" or "asks about enterprise pricing" 3. Add a **Request human** node and set its **message** — shown to the visitor while they wait (required) 4. Optionally add `collect_input` nodes before the handoff to gather the visitor's email, name, or order number first 5. Test the flow in the editor's **Test** panel, then switch it to **Active** ## Example Intents ### 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**: the AI scores the message against each active `visitor_intent` flow 2. **Match Detection**: the best match above the threshold runs the flow 3. **Info Collection**: optional `collect_input` nodes ask for email, name, or details 4. **Ticket Created**: the `request_human` node opens a live-support ticket 5. **Team Notified**: teammates are notified per their notification preferences ## 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 flows. ## Related The visual builder where handoff automations live. The inbox where handoff tickets land. # 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 ### Zoho Commerce Installation **Option 1: Connect from your BubblaV dashboard (Recommended)** Go to **Dashboard** → **Integrations** → **Zoho Commerce** Click **Connect** and sign in to your Zoho account Accept the requested read-only permissions in Zoho Order and product tools activate automatically **Option 2: Manual Installation** Add the chat widget to your Zoho Commerce storefront: Log in to your Zoho Commerce admin Go to **Online Store** → **Settings** → **Code** Paste your BubblaV widget snippet into the **Footer Code** section Click **Save** to apply changes ### Quickbutik Installation **Recommended: Connect with your API key** You need edit access to a BubblaV website and a Quickbutik store whose owner can generate and use an API key. Create or select the BubblaV website for your Quickbutik storefront. Have the store owner generate an API key in **Quickbutik Control Panel** → **Settings** → **API**. See [Quickbutik's API authentication documentation](https://quickbutik.dev/api-v1/authentication.md). Open that website's **Dashboard** → **Integrations** → **Quickbutik**, click **Connect**, paste the key into **Quickbutik API Key**, and submit. BubblaV validates the key, provisions product and order tools, and attempts to install the widget automatically. A **Connected** status alone does not prove that widget installation or tool provisioning succeeded. Open the live storefront and confirm a single chat bubble. Test a visible product keyword, then a real order number with its matching checkout email. If the widget is missing, follow the manual fallback below. Do not add another snippet over an already working widget. **Manual installation (fallback)** Copy the snippet from your BubblaV website's **Installation** page. If using the example below, replace only `YOUR_WEBSITE_ID` with your website ID. Never put your API key in the snippet. ```html theme={null} ``` Back up the Quickbutik theme, then open **Utseende** → **Tema** → **Kod under huven**. See [Quickbutik's template structure documentation](https://quickbutik.dev/theme-development/template-structure.md). Place the snippet before the closing `` tag of the shared storefront layout. If no shared body or layout is exposed, ask Quickbutik support for theme-specific placement instead of guessing a filename. Save and apply the theme change, then check the live storefront for a single chat bubble. Do not install a duplicate snippet over an already working widget. Manual installation adds chat only; product and order access still requires the API-key connection. Disconnecting attempts to remove API-managed scripts on a best-effort basis, but does not remove manually pasted theme code. Remove that code separately when uninstalling. See the [Quickbutik setup guide](/user-guide/integrations/quickbutik) for tools, test queries, and troubleshooting. ### 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. > **Scope note**: Attio provides **CRM contact context** — contact sync, transcript notes, and visitor insights. It does not sync support tickets into the Live Support inbox (Attio has no ticketing API). For ticket sync, use the [HubSpot](/user-guide/integrations/hubspot) or [Zendesk](/user-guide/integrations/zendesk) integration. > **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. * **Two-Way Sync**: Contact detail changes made in Attio (name, job title, company, phone, description) sync back into the BubblaV visitor profile automatically. * **Configurable Sync**: Toggle contact syncing and transcript logging independently based on your workflow needs. * **Custom Attribute Mapping**: Map visitor and form fields to your own Attio attributes — standard or custom — so lead capture writes exactly the data you care about. ## 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. * **Custom attribute mapping**: Map visitor and form fields to your own Attio attributes. ### Custom attribute mapping In **Integrations → Attio → Custom attribute mapping**, map any visitor or form field (for example `utm_source`, `company`, or one of your own form field names) to any writable Attio attribute — standard or custom. The mapped value is written to the Person record whenever a lead is captured. * Pick the Attio attribute from the dropdown, loaded straight from your workspace. If the list can't be loaded, type the attribute slug directly. * Select/status values must already exist as options in Attio — unmatched options are skipped. * Mappings override the built-in defaults (UTM parameters, lead source, company, job title, phone, website) when both target the same attribute. ## 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 # ChatGPT Source: https://docs.bubblav.com/user-guide/integrations/chatgpt Connect BubblaV to ChatGPT via MCP to search your knowledge base, view analytics, and manage your chatbot Connect BubblaV to ChatGPT through the BubblaV MCP Server. Ask ChatGPT to search your knowledge base, pull analytics, find content gaps, and tune your chatbot — no API key required. Install the BubblaV app from the [ChatGPT apps page](https://chatgpt.com/apps/bubblav-ai-chatbot/asdk_app_69c3e9a175b481919947b413dee0979f), or add `https://www.bubblav.com/mcp` as an MCP connector in ChatGPT. OAuth runs automatically — sign in to BubblaV and pick a website. ChatGPT is granted the `mcp:read` and `mcp:tools:execute` scopes. ## Why Connect ChatGPT? * **Ask your knowledge base in chat**: Search and manage content without opening the dashboard * **Analytics on demand**: Full reports for any date range, summarized in plain language * **Close content gaps**: See what your bot couldn't answer and add the missing answers * **Tune the persona**: Change the chatbot's voice, greetings, and widget appearance from ChatGPT * **Inspect conversations & leads**: Filter and full-text search across chats * **No API key**: OAuth handles everything ## Prerequisites * A BubblaV account with at least one website set up and some content indexed * A ChatGPT plan that supports MCP apps/connectors ## Install the BubblaV ChatGPT App Click **Add to ChatGPT** on the [ChatGPT apps page](https://chatgpt.com/apps/bubblav-ai-chatbot/asdk_app_69c3e9a175b481919947b413dee0979f); *or* in ChatGPT go to **Settings → Connectors → Add connector** and enter `https://www.bubblav.com/mcp`. ChatGPT starts OAuth automatically. Sign in to BubblaV, select the website to connect, and approve the requested scopes. No API key is needed. The BubblaV connector shows as connected in ChatGPT. An API key labeled **ChatGPT** is created in your BubblaV account to power the connection. Ask ChatGPT something like *"Search my knowledge base for our return policy"* or *"Give me this month's chatbot report."* ChatGPT is one of several MCP clients. For API-key setup, other clients (Claude Desktop, Google Antigravity), and the full tool reference, see the [MCP Server developer guide](/developer-guide/mcp-server). To add other MCP servers inside BubblaV, see [MCP Servers](/user-guide/integrations/mcp-servers). ## What You Can Ask ChatGPT receives BubblaV's tools automatically and picks the right one for your request. A representative subset: | Tool | What it does | Example prompt | | ---------------------------------- | -------------------------------------------------------- | --------------------------------------------------------- | | `bubblav_search_knowledge` | Search your knowledge base | "What does our returns policy say?" | | `bubblav_add_knowledge` | Add a knowledge entry | "Add a FAQ about holiday shipping deadlines" | | `bubblav_list_knowledge_sources` | List everything your bot is trained on | "What sources is my bot trained on?" | | `bubblav_upload_knowledge_file` | Upload a PDF/DOCX/TXT/MD file (≤10 MB) to index | "Index this product spec PDF" | | `bubblav_sync_ticket_to_knowledge` | Turn a resolved ticket into an article (Pro+) | "Save last week's refund ticket as a knowledge article" | | `bubblav_add_crawl_url` | Add a URL to crawl and index | "Index our new pricing page" | | `bubblav_get_crawl_status` | Check indexing progress | "How many pages are indexed so far?" | | `bubblav_list_conversations` | List/filter conversations by channel or status | "Show me Instagram conversations this week" | | `bubblav_search_conversations` | Full-text search across chats | "Find chats mentioning 'billing error'" | | `bubblav_list_leads` | List visitors who shared their email | "Show me leads from the last 7 days" | | `bubblav_get_content_gaps` | Questions your bot couldn't answer well | "What should I add to my knowledge base?" | | `bubblav_get_most_asked_questions` | Trending visitor questions | "What are people asking most this month?" | | `bubblav_read_report` | Full analytics report for a date range | "Give me June's chatbot performance report" | | `bubblav_get_hourly_activity` | Hourly activity breakdown | "When are my busiest support hours?" | | `bubblav_update_website_settings` | Update the chatbot persona / settings | "Make the bot more friendly and concise" | | `bubblav_update_widget_appearance` | Update bot name, greetings, colors, position | "Rename the bot to 'Sunny' and use a teal bubble" | | `bubblav_create_custom_tool` | Create a webhook custom tool (Pro+) | "Add a tool that checks order status from our API" | | `bubblav_create_flow` | Build a flow — e.g. route a topic to a live agent (Pro+) | "Hand off to a human when someone mentions large refunds" | This is a representative subset. ChatGPT always receives the full, current tool list via the MCP `tools/list` method. ## Rate Limits MCP calls are metered separately from your chatbot messages, on a rolling 30-day window: | Plan | MCP calls / month | | ------ | ----------------- | | Free | 100 | | Pro | 5,000 | | Custom | Unlimited | When you exceed the limit, requests return a `429` with a `Retry-After` header. Check your usage under **Integrations → MCP Settings** in the dashboard. ## Reconnecting To disconnect or switch the website ChatGPT is linked to, revoke the **ChatGPT** API key from your BubblaV dashboard, then add the connector again in ChatGPT and pick the website you want during OAuth. ## Troubleshooting * Make sure your ChatGPT plan supports MCP apps/connectors. * Try removing the connector and re-adding `https://www.bubblav.com/mcp`. * Revoke the ChatGPT API key in BubblaV and reconnect, picking the correct website during OAuth. * Check usage under **Integrations → MCP Settings**, wait for the 30-day window to reset, or upgrade your plan. * The ChatGPT app intentionally does not expose arbitrary URL scraping. To add new content, use `bubblav_add_crawl_url`, `bubblav_upload_knowledge_file`, or `bubblav_add_knowledge` instead. ## Next Steps Full tool reference and other MCP clients Webhook tools you can create from ChatGPT Recipes to diagnose gaps and tune your bot # 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 # Email (IMAP) Source: https://docs.bubblav.com/user-guide/integrations/email Connect any email mailbox via IMAP to bring support emails into your unified BubblaV inbox, with AI-drafted replies from Copilot Bring your support emails into the same BubblaV inbox as your live chat, Messenger, WhatsApp, and other channels. Connect any mailbox over IMAP, triage inbound email alongside everything else, and reply by email directly from the dashboard — keeping the original thread intact. ## Why Connect Email? Triage chat, social DMs, and email conversations in a single place Agent replies are sent over SMTP and thread correctly in the customer's mail client Works with Gmail, Outlook/Microsoft 365, and any custom-domain mailbox that supports IMAP Inbound attachments are stored and shown with the conversation The Email channel creates a support conversation your team owns. The AI doesn't auto-send email replies — but Copilot can **draft** every reply for you. See [Draft a Reply with Copilot on Email](#draft-a-reply-with-copilot-on-email) below. ## Prerequisites * A mailbox that supports **IMAP** (for receiving) and **SMTP** (for sending replies). * **IMAP access enabled** in your email provider's settings. Gmail, Zoho, and Outlook all require you to turn IMAP on for the mailbox before it can be polled. * The mailbox **login credentials**: your username (the full email address) and a password. If two-factor authentication is on, your regular account password will be rejected — you must use the provider's **App Password**: * **Gmail**: Google Account → Security → 2-Step Verification → **App passwords**. * **Zoho**: Zoho Mail → Settings → Mail Accounts → **IMAP/POP Access** → enable IMAP, then generate an **App Password** under the same section. * **Outlook / Microsoft 365**: Microsoft account → Security → Advanced security options → **App passwords**. ## Setup Steps ### Gmail — Sign in with Google (recommended) In your dashboard, go to **Integrations** and find **Email** under the Communication category, then choose **Gmail** as the provider. Click **Sign in with Google**. After you approve, you're returned to the dashboard. New mail arriving from that moment on is fetched automatically (mail already in the inbox before connecting is skipped). ### Other providers — IMAP / App Password In your dashboard, go to **Integrations** and find **Email (IMAP)** under the Communication category. Provide your IMAP host and port, SMTP host and port, username, password (or App Password), and the address replies should be sent from. BubblaV verifies both the IMAP and SMTP login before saving. If both succeed, your mailbox is connected and polling begins automatically. ### Common provider settings | Provider | IMAP | SMTP | | ----------------------- | --------------------------- | ------------------------- | | Gmail | `imap.gmail.com:993` | `smtp.gmail.com:587` | | Zoho (global) | `imap.zoho.com:993` | `smtp.zoho.com:465` | | Zoho (EU) | `imappro.zoho.eu:993` | `smtppro.zoho.eu:465` | | Outlook / Microsoft 365 | `outlook.office365.com:993` | `smtp.office365.com:587` | | Custom domain / hosting | Your provider's IMAP host | Your provider's SMTP host | TLS is automatic based on the port: **993** and **465** use implicit TLS, while **143** and **587** use STARTTLS. You don't need to configure TLS separately. ## Managing Your Integration * **New mail** is fetched automatically every couple of minutes and appears as a conversation in **Live Support**, tagged with an Email badge. * **Reply** from the conversation view — your reply is sent from your connected address and threaded under the customer's original email. * **Change credentials**: disconnect and reconnect with the new details. * **Disconnect** from the integration's configure page to stop polling. ## How Replies Are Threaded Each reply includes the correct `In-Reply-To`, `References`, and `Re:` subject headers so it lands inside the customer's existing email conversation in Gmail, Outlook, Apple Mail, and other clients — rather than starting a new thread. ## Draft a Reply with Copilot on Email You don't have to write every reply from scratch. On any email conversation in the unified inbox, click **Draft reply with Copilot** and BubblaV writes a complete draft straight into your composer. In **Live Support**, open the email ticket you want to answer. Copilot reads the customer's email (including attachments) and writes a complete, source-cited draft based on your knowledge base and the customer's context. Check the draft, adjust the tone, and add anything Copilot couldn't know. Your reply goes out from your connected mailbox, threaded under the customer's original email — exactly as if you'd written it yourself. Copilot only drafts — a human always reviews and sends. Nothing goes out from your mailbox without an agent clicking send. This makes email support safe to hand to brand-new agents: Copilot supplies the answer, they stay in charge. # 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 the [BubblaV Haravan App listing](https://apps.haravan.com/products/bubblav) and click **Install app**. 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. *** ## What the Chatbot Can Do Once connected, the chatbot can answer customer questions using your live store data: Customers describe what they want ("vòng tay bạc dưới 2 triệu", "quà tặng cho mẹ") and the chatbot searches your catalog with price, availability, size/color and brand filters — then shows product cards with images and prices in VND. Product cards include an **Add** button. On your storefront, items go straight into the customer's cart; from other sites, a new tab opens with the items pre-added. Customers track an order with its number plus the email or phone used at checkout, and get a status card with payment state, delivery tracking and a buy-again button. Returning customers can list their past orders by email or phone number. **Always Connected**: Haravan access tokens refresh automatically — your chatbot keeps working without periodic reconnections. (Stores connected before August 2026 may be asked to reconnect once when their token expires.) *** ## Available Tools After Connection | Tool | What It Does | Example Query | | -------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `haravan_track_order` | Track orders by number/ID | "Kiểm tra đơn hàng #1025" / "Track order #1025" | | `haravan_search_products` | Advanced product search with filters (price range, availability, size/color variants, brand, sort) | "Vòng tay bạc dưới 2 triệu" / "Silver bracelet under 2 million VND" | | `haravan_get_product` | Get full product details (complete description, specs, variants, stock) | "Gửi thông số thang gấp 604" / "Tell me more about product #1" | | `haravan_customer_orders` | Customer order history | "Cho tôi xem các đơn hàng của email này" / "My orders for [john@example.com](mailto:john@example.com)" | | `haravan_initiate_return` | Start a return request | "Tôi muốn trả hàng" / "I want to return my order" | | `haravan_create_return` | Process return authorization | "Xử lý trả hàng giúp tôi" / "Process my return" | | `haravan_validate_discount_code` | Validate promo codes | "Mã SUMMER25 còn hiệu lực không?" / "Is code SUMMER25 valid?" | ## Test Your Integration Visit your Haravan store and open the chatbot widget. Try asking: * "What are your business hours?" * "Show me charm bracelets under 2 million" (product search) * "Gửi thông số \[product]" (full product specs via product details) * "Where is my order #1025?" with the email used at checkout (order tracking) ## 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 * Your Haravan session expired; click **Reconnect** on the Haravan integration card * This is expected at most once for stores connected before August 2026 **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, contacts, and support tickets to your CRM — and let visitors book meetings in chat Sync your chatbot conversations, contacts, leads — and now support tickets — 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. * **Ticket Sync to the Unified Inbox**: HubSpot conversations and tickets sync into BubblaV's Live Support inbox, and agent replies go straight back into the HubSpot thread. ## 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. ## Ticket Sync to the Unified Inbox HubSpot conversations and tickets sync directly into BubblaV's unified **Live Support** inbox: * Tickets and their conversation threads created in HubSpot appear in the inbox within **\~2 minutes** — no forwarding or copy-pasting. * Each HubSpot conversation thread becomes its own ticket, with the HubSpot channel chip so agents can see at a glance where the customer is writing from. * New customer replies in the thread update the same ticket automatically; agent-side notes in HubSpot stay private and are not mirrored. * Ticket sync is on by default. You can pause it any time in **HubSpot integration settings → Ticket sync**. BubblaV's default OAuth request asks for exactly the scopes it uses — `crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.objects.companies.read`, `crm.objects.deals.read`, `crm.objects.owners.read`, `tickets`, `conversations.read`, `conversations.write`, `automation`, and `sales-email-read` — nothing more. ## Meeting Scheduling Visitors can book a meeting right in the chat using your HubSpot Meetings scheduling pages. When someone asks to book a call, the chatbot shares your HubSpot meeting links as booking cards; picking one opens HubSpot's own scheduler inside the chat — availability, form fields, and legal consent are all handled by HubSpot, and the booked meeting appears in your HubSpot CRM like any other meeting. | Tool | What it does | | ---------------------------- | ---------------------------------------------------------------------------- | | `hubspot_find_meeting_links` | Lists your HubSpot Meetings scheduling pages and shows booking cards in chat | | `hubspot_find_meetings` | Looks up a contact's HubSpot meetings by email address | Reconnecting: existing HubSpot connections need to reconnect **once** to grant the new scope (`scheduler.meetings.meeting-link.read` — meeting records themselves are covered by the existing contacts scope). Private-app users should add the same scope to their private app and reconnect. No other setup is required. Rescheduling and cancelling stay in HubSpot — the Meetings API doesn't support rescheduling. Visitors can change or cancel via their HubSpot confirmation email or their meeting link. ## Reply & Draft with AI Manage HubSpot conversations without leaving BubblaV: * **Reply from the inbox**: An agent reply in BubblaV is posted into the HubSpot conversation thread as a customer-visible message — the customer sees it in HubSpot, exactly where they started the conversation. * **One-click Draft reply**: The **Draft reply** button uses your knowledge base to draft a grounded response for any HubSpot ticket. Review, edit, and send it into the thread. * If a ticket has no conversation thread yet (e.g. created via API without one), the reply is saved to the ticket and flagged as not delivered so you can retry. # 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 Pick how BubblaV authenticates against the server: **Headers / API key** (default) * Add custom headers if the server requires them * **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` **OAuth login** * For MCP servers that support OAuth 2.1 (e.g. [Spoks](https://mcp.spoks.com/mcp)) * No headers or tokens to copy — BubblaV discovers the server's OAuth endpoints and registers itself automatically * **Headers mode**: save, then click **Refresh** to fetch the server's tools. * **OAuth mode**: save and you are redirected to the provider's sign-in/consent screen. Approve access — BubblaV stores the tokens encrypted, syncs the server's tools, and returns you to the dashboard. Tokens refresh automatically before they expire. *** ## 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` | ### OAuth MCP Server Connect with one-click OAuth instead of headers: | Field | Value | | -------------- | --------------------------- | | Name | Spoks Marketing | | URL | `https://mcp.spoks.com/mcp` | | Authentication | OAuth login | ### 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** OAuth servers also show a **Connect** / **Reconnect** button on their card. Use it when the authorization expired or was revoked on the provider side — it restarts the OAuth consent flow. *** ## 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 * If you denied the consent screen, click **Connect** on the server card and approve access * Confirm the server advertises OAuth support (most hosts expose `/.well-known/oauth-protected-resource`) * A `mcp_oauth_failed` error usually means the provider rejected automatic client registration — contact the server provider *** ## 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 * **Encrypted tokens**: OAuth tokens and header secrets are stored encrypted at rest, never returned by the API, and refreshed server-side before expiry * **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 `