> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use AI Agents to Manage & Improve Your Chatbot

> Connect Claude, ChatGPT, or OpenClaw to BubblaV via MCP and let your AI diagnose content gaps, write knowledge, tune behavior, set up human handoff, and build custom tools — with copy-paste prompts.

You don't have to manage your chatbot by hand. BubblaV exposes its data and settings over an
**MCP server**, so an AI assistant like **Claude**, **ChatGPT**, **Google Antigravity**, or
**OpenClaw** can run the same tasks you'd do in the dashboard — diagnose weak answers, write and
add knowledge, tune the bot's persona, set up human handoff, and build custom tools.

This page is a recipe book. Each recipe has a **goal**, a **copy-paste prompt**, and the **MCP
tools** it triggers. For the full tool-by-tool reference and connection details, see the
[MCP Server](/developer-guide/mcp-server) developer guide.

## What you can do

<CardGroup cols={2}>
  <Card title="Diagnose" icon="search">
    Find the questions your bot struggles with and the topics visitors ask about most.
  </Card>

  <Card title="Improve knowledge" icon="database">
    Draft and add Q\&A, upload files, and turn resolved tickets into reusable answers.
  </Card>

  <Card title="Tune behavior" icon="settings">
    Rewrite the chatbot persona and edit the widget's words, colors, and starters.
  </Card>

  <Card title="Automate" icon="robot">
    Configure human-handoff triggers and build custom webhook tools.
  </Card>
</CardGroup>

## Connect your AI (one time)

Add BubblaV as an MCP server in your assistant. The setup differs slightly by client — full
screenshots are in the [MCP Server guide](/developer-guide/mcp-server).

<Tabs>
  <Tab title="Claude / ChatGPT / Antigravity">
    These clients use **OAuth** — no API key to manage.

    1. In your assistant's settings, add a new MCP server with the URL below.
    2. Authorize: sign in to BubblaV and pick the website to connect.
    3. Done. Your assistant now sees BubblaV's tools.

    ```text theme={null}
    https://www.bubblav.com/mcp
    ```
  </Tab>

  <Tab title="OpenClaw (API key)">
    API-key clients send a header instead of OAuth.

    1. In BubblaV, open **Website Settings → API Keys** and generate a key with the
       `mcp:read` and `mcp:tools:execute` scopes. Copy it — it's shown once.
    2. Point your client at the endpoint below, sending `X-API-Key: bubblav_mcp_…`.
    3. We recommend the [mcporter](https://github.com/jasonacox/mcporter) helper to configure OpenClaw.

    ```text theme={null}
    URL:    https://www.bubblav.com/api/mcp
    Header: X-API-Key: bubblav_mcp_YOUR_KEY
    ```
  </Tab>
</Tabs>

<Note>
  Your assistant can only act on the website you authorized, and every call is logged in
  **Integrations → MCP Settings → Audit Logs**.
</Note>

***

## Recipes

Paste each prompt into your connected assistant and edit the bracketed parts. Your assistant will
call the BubblaV tools for you.

### 1. Find content gaps & trending questions

**Goal:** see where the bot fails and what visitors ask most, grouped into themes.

```text theme={null}
Look at my chatbot's content gaps and most-asked questions from the last 30 days.
Group them by theme, tell me which topics the bot struggles with most, and rank
the top five things I should fix.
```

**Tools it triggers:** `bubblav_get_content_gaps`, `bubblav_get_most_asked_questions`, `bubblav_read_report`.

### 2. Fill content gaps with new knowledge

**Goal:** draft answers for the worst gaps and add them — without writing each one by hand.

```text theme={null}
Take the top three gaps in the [shipping] theme. Here's our policy: [paste text].
Draft a clear Q&A-style answer for each gap, show them to me for approval, then
add each approved answer to the knowledge base. Skip any gap already covered.
```

**Tools it triggers:** `bubblav_search_knowledge` (de-dup check), `bubblav_add_knowledge`.

<Steps>
  <Step title="Upload a file instead">
    ```text theme={null}
    Upload and index this file as knowledge: [attach PDF/DOCX/TXT/MD, ≤10MB]
    ```

    Calls `bubblav_upload_knowledge_file`, then `bubblav_get_crawl_status` to confirm indexing.
  </Step>

  <Step title="Add a single page to the index">
    ```text theme={null}
    Crawl and index this URL into my knowledge base: https://example.com/new-page
    ```

    Calls `bubblav_add_crawl_url`.
  </Step>

  <Step title="Turn a resolved ticket into knowledge (Pro+)">
    ```text theme={null}
    Turn resolved ticket [ticket_id] into a searchable knowledge article.
    ```

    Calls `bubblav_sync_ticket_to_knowledge`.
  </Step>
</Steps>

### 3. Turn conversations into insight

**Goal:** audit specific issues or pull leads out of conversations.

```text theme={null}
Find every conversation from the last two weeks that mentioned a "billing error".
Summarize the common causes. Then list the leads (visitors who gave an email) from
the same period so I can follow up.
```

**Tools it triggers:** `bubblav_search_conversations`, `bubblav_get_conversation`, `bubblav_list_leads`.

### 4. Tune the chatbot persona & widget

**Goal:** change how the bot talks and looks, editing in place rather than overwriting.

```text theme={null}
Read my bot's current instructions. Then update the persona so it's warmer and more
concise, always greets by name, and offers to escalate to a human for anything
billing-related. Also set the widget greeting to "Hi there! How can we help?" and
add three starter suggestions.
```

**Tools it triggers:** `bubblav_get_website_settings`, `bubblav_update_website_settings`
(the `custom_instructions` field is the persona, max 2,000 chars), `bubblav_update_widget_appearance`.

### 5. Set up human handoff triggers (Pro+)

**Goal:** route sensitive intents to a live agent automatically.

```text theme={null}
Create a human-handoff scenario: when a visitor mentions a refund, cancellation, or
complaint, hand off to a live agent with the message "Let me connect you with a
teammate who can sort this out." List the existing scenarios first so we don't duplicate.
```

**Tools it triggers:** `bubblav_list_handoff_scenarios`, `bubblav_create_handoff_scenario`.

### 6. Build a custom webhook tool (Pro+)

**Goal:** let the chatbot take a real action (check an order, query a CRM, get a quote).

```text theme={null}
Create a custom tool called "check_order_status" that takes an order number and
calls my webhook at https://example.com/api/order-status using bearer auth.
Describe it for the AI so it knows when to use it, then activate it for this website.
```

**Tools it triggers:** `bubblav_list_custom_tools`, `bubblav_create_custom_tool`.

<Note>
  The `secret_key` for a bearer/hmac tool is returned **only once**. Tell your assistant to surface
  it to you immediately so you can configure your webhook. See
  [Custom Tools](/user-guide/integrations/custom-tools) for webhook validation details.
</Note>

### 7. Create a scoped API key for another agent

**Goal:** give a second assistant (or Zapier, a script, etc.) limited access.

```text theme={null}
Create a new MCP API key named "Zapier" with read-only (mcp:read) scope.
```

**Tools it triggers:** `bubblav_create_api_key`. (Use `bubblav_list_api_keys` and
`bubblav_revoke_api_key` to audit and revoke.)

***

## The improvement loop

These recipes chain into a weekly habit:

```text theme={null}
1. Diagnose  — "what should I fix this week?"
2. Improve   — "draft & add answers for the top gaps"
3. Measure   — "how did resolution rate change?"
4. Tune      — "adjust tone / handoff based on what you saw"
```

<Warning>
  Your AI drives each cycle — BubblaV does **not** run an autonomous self-improvement job in the
  background. You approve knowledge before it's added and control how the persona evolves. The win
  is collapsing a week of dashboard chores into a single conversation.
</Warning>

## Plans & limits

MCP calls are counted separately from your AI message limits, on a rolling 30-day window.

| Plan   | MCP calls / month |
| ------ | ----------------- |
| Free   | 100               |
| Pro    | 5,000             |
| Custom | Unlimited         |

The following require a **Pro plan or higher** (gated when the tool runs):

* `bubblav_create_custom_tool` and custom-tool management
* `bubblav_create_handoff_scenario` and handoff management
* `bubblav_sync_ticket_to_knowledge`

See [Billing & Plans](/user-guide/billing) for full plan details. When you exceed the limit you'll
get an HTTP `429` with a `Retry-After` header.

## Related

<CardGroup cols={2}>
  <Card title="MCP Server reference" icon="terminal" href="/developer-guide/mcp-server">
    Every tool, parameter, auth flow, and rate limit — the developer reference.
  </Card>

  <Card title="Knowledge Overview" icon="book-open" href="/user-guide/knowledge/overview">
    How crawled pages, Q\&A, and files become answers.
  </Card>

  <Card title="Insights" icon="lightbulb" href="/user-guide/knowledge/content-gaps">
    The dashboard view of content gaps and answerable questions.
  </Card>

  <Card title="Custom Tools" icon="wrench" href="/user-guide/integrations/custom-tools">
    Webhook tools, authentication, and validation.
  </Card>
</CardGroup>