DocsBrew Documentation

DocsBrew turns your catalog, website, and messaging channels into one conversational AI sales agent. Your bot sells on your website, WhatsApp, Telegram, Instagram, and Facebook Messenger — using a single source of truth for products and knowledge.

Quickstart

Get DocsBrew running on your site in under 5 minutes.

<script
  src="https://api.docsbrew.com/widget/embed.js"
  data-project-id="your-project-id"
></script>

How DocsBrew works

1. Connect

You give DocsBrew two kinds of data: a structured Catalog (CSV, Excel, or Shopify sync — what you sell, with prices) and an unstructured Knowledge Base (website crawl, uploaded PDFs, or typed FAQs — what your bot knows). They live in separate tables so the bot never confuses a blog post with a product.

2. Converse

When a visitor asks a question on any channel, DocsBrew runs a retrieval pipeline: it searches your catalog for matching products, your knowledge base for relevant context, and stitches the best pieces into the LLM prompt. The unified AI agent handles intent classification, product recommendations, objection handling, and lead capture — all in one model call per turn.

3. Convert

The agent tracks conversation state (browsing → considering → ready_to_buy), captures contact info naturally when the visitor is warm, scores the lead, and fires a notification to the business owner. Conversations from every channel flow into one unified inbox on the dashboard.

Widget installation

The DocsBrew widget can be embedded on any website with a single script tag. It loads asynchronously and won't block your page rendering.

Script tag embed

The simplest way to add DocsBrew. Paste this snippet before </body>:

<script
  src="https://api.docsbrew.com/widget/embed.js"
  data-project-id="proj_abc123"
></script>

The embed script creates a secure cross-origin iframe that loads the chat widget. This approach is CSP-friendly and works on any hosting platform including Shopify, WordPress, Squarespace, and static sites.

How it loads

1. The embed.js bootloader (~3KB) reads your data-* attributes
2. It collects page context (URL, title, referrer, visitor timezone, screen size)
3. An iframe is created pointing to your DocsBrew widget endpoint
4. The widget and your page communicate via the postMessage API

Widget customization

Control the widget's appearance and behavior through data-* attributes on the script tag or from the dashboard's Widget page.

Available attributes

All attributes below are read from the <script> tag that loads embed.js (and are forwarded to the widget iframe as URL params). Every attribute is optional except data-project-id.

Example with customization

<script
  src="https://api.docsbrew.com/widget/embed.js"
  data-project-id="proj_abc123"
  data-accent="#6366f1"
  data-position="bottom-left"
  data-welcome="Hi! Looking for the perfect pair? I can help."
  data-name="ShoeVault"
  data-theme="light"
></script>

Widget events & callbacks

The widget communicates with your page via the postMessage API. You can listen for events to trigger custom behavior.

Listening for events

window.addEventListener('message', function(event) {
  // Always verify the origin in production
  if (event.data && event.data.type) {
    switch (event.data.type) {
      case 'docsbrew:ready':
        console.log('Widget loaded');
        break;
      case 'docsbrew:resize':
        console.log('Widget resized:', event.data.width, event.data.height);
        break;
      case 'docsbrew:navigate':
        console.log('Navigation requested:', event.data.url);
        break;
    }
  }
});

Event reference

Iframe embed (advanced)

If you need full control over the iframe, you can embed it manually instead of using the bootloader script.

<iframe
  src="https://api.docsbrew.com/widget/frame?project-id=proj_abc123&accent=%230070f3"
  style="position:fixed; bottom:0; right:0; width:420px; height:100vh;
         border:none; z-index:999999;"
  allow="clipboard-write"
></iframe>

Dashboard overview

The DocsBrew dashboard is your control center. After logging in at /login, you'll land on the Projects page — the hub for all your AI sales agents.

Navigation

The sidebar gives you quick access to your projects, settings, and these docs. Inside a project, the sidebar switches to project-specific pages: Knowledge Base, Widget, Leads, and Analytics.

Projects

Each project represents one website or storefront. You can run multiple projects under a single account.

Creating a project

1. Click New Project from the dashboard
2. Enter your project name and business name
3. Choose your business type (E-commerce, Restaurant, Travel, Accommodation, SaaS, Services, or Other)
4. Pick a sales tone (consultative, direct, friendly, or professional)
5. Add optional sales instructions — these guide the AI's selling approach
6. Click Create, then connect a data source (website URL, Shopify, WordPress, or uploaded files) to begin indexing

Business types

Business types shape how the AI agent behaves. An e-commerce type knows about products, pricing, and carts. An accommodation type understands rooms, availability, and bookings. Choose the one that best matches your business.

Catalog — what you sell

The Catalog tab on your project holds everything you sell: products, services, tours, packages, menu items. Each row has a name, price, optional image/URL/SKU, and custom attributes. The AI agent uses it for recommendations, comparisons, and quotes.

Getting products in

• CSV / Excel upload — the fastest path. See Bulk upload below.
• Shopify — connect your store URL + access token and we sync products on demand (Starter plan and above).
• Add manually — the "Add Products" button lets you enter one item at a time with a simple form.

What each item holds

Core fields: name (required), description, price (required), currency, category, brand, sku, url, image_url, in_stock, item_type. Everything else becomes a custom attribute stored on the product, searchable by the bot (e.g. duration, difficulty, dietary, rooms).

Knowledge Base — what your bot knows

The Knowledge tab holds unstructured content: your website pages, PDFs, FAQs, policies, and anything else that helps the bot answer visitor questions confidently. This is never mixed with your catalog — it's only used as context for the LLM.

Three ways to add knowledge

• Crawl a website — paste a URL. We discover your pages, extract the main content (stripping navigation and footers), and index it. Great for About pages, FAQs, policies, and blog posts.
• Upload files — PDF, Markdown, HTML, or plain text. File size limits depend on your plan (5 MB Free, 10 MB Starter, 25 MB Pro, 100 MB Team).
• Type it out — no website? No problem. Use one of the templates (Business FAQ, About Your Business) or paste plain text directly. Perfect for businesses that sell primarily through WhatsApp or Instagram.

How retrieval works

Your content is chunked with overlap, embedded into a vector index, and searched on every visitor message. Each query hits two retrieval calls — one against your catalog, one against your knowledge — and the best matches flow into the AI's context. You don't need to tune any of this.

Re-indexing

Your website changed? Trigger a re-crawl from the Knowledge tab. Files can be replaced individually; typed-out entries can be edited in place.

CSV & Excel upload

The fastest way to get a catalog in. Supports .csv, .tsv, and Excel .xlsx. Maximum 1,000 rows per file; run several uploads for larger catalogs.

The import wizard

1. Upload the file. Drag-and-drop, or click to browse.
2. Map columns. We auto-detect common headers (title → name, cost → price, etc.) and show a preview with 5 sample rows. Override any mapping with a dropdown.
3. Pick options. item_type (product / menu_item / itinerary / room / service / plan), default currency (defaults to KES), and Replace all existing products vs. add to the current catalog.
4. Review results. We report rows created, skipped, and errors — expandable list of every bad row so you can fix and re-upload.

Recognised column names

Required: name, price. Optional: description, currency, category, brand, sku, url, image_url, in_stock, item_type. Common variants are auto-mapped (title → name, cost → price, product_url → url, etc.). Anything we don't recognise becomes a searchable attribute on the product.

Example

name,price,currency,duration,difficulty,image_url
Masai Mara 3-Day Migration Safari,45000,KES,3 days,easy,https://...
Mount Kenya Summit Expedition,120000,KES,5 days,challenging,https://...
Amboseli Elephant Weekend,38000,KES,2 days,easy,https://...

Channel: Web widget

The default channel. One script tag on your website and the chat bubble is live. See Widget installation for details.

Channel: WhatsApp

WhatsApp is included on every plan, including Free. In Kenya it's the most-used customer channel, so DocsBrew treats it as core rather than an upsell lever.

Setup

1. Go to Connectors → WhatsApp in your project.
2. Create a WhatsApp Business App on Meta for Developers and get your Phone Number ID, Access Token, App Secret.
3. Paste them into the Connectors form. We auto-generate a webhook verify token.
4. Copy the webhook URL from the Connectors page into your Meta App → Webhooks tab and subscribe to messages.

Behaviour

Inbound messages flow through the same unified agent as the widget. Product recommendations render as interactive buttons or lists when ≤10 options. The 24-hour customer service window is tracked automatically.

Channel: Telegram

Included from the Starter plan. Easiest connector to set up — no OAuth, no app review.

1. Open Telegram, message @BotFather, run /newbot, give it a name.
2. Copy the bot token.
3. Go to Connectors → Telegram, paste the token, and click Connect. We validate it via getMe and register the webhook automatically.

Channel: Instagram & Facebook Messenger

Both are included from the Pro plan. Both use Meta's Graph API and share a setup flow similar to WhatsApp.

Instagram DMs

Requires an Instagram Business or Creator account connected to a Facebook Page. In Connectors → Instagram, enter the Page ID, Page Access Token, and App Secret. Subscribe to the messages webhook field in your Meta App. Needs instagram_manage_messages permission.

Facebook Messenger

Requires a Facebook Page with the Messenger product enabled in your Meta App. Same setup: Page ID, Page Access Token, App Secret, plus pages_messaging permission. Subscribe to messages and messaging_postbacks webhooks.

Leads & analytics

Every conversation is a potential lead. DocsBrew automatically captures visitor information and scores engagement.

Lead scoring

Each visitor interaction is scored based on behavioral signals: number of questions asked, products viewed, time engaged, and funnel stage progression. Leads are ranked so you can prioritize follow-up.

Lead data captured

• Contact info — email, phone, name (when the visitor provides it naturally in conversation)
• Engagement — messages sent, products discussed, session duration
• Funnel stage — browsing, considering, or ready to buy
• Source — page URL, referrer, UTM parameters
• Lead score — composite score ranking conversion likelihood

Analytics

The analytics view gives you conversation volume, response accuracy, popular questions, and conversion rates over time. Use it to understand what visitors ask about most and where your content gaps are.

Widget configuration

The Widget page in your project dashboard lets you customize appearance and copy the embed code.

Live preview

Changes to colors, position, welcome message, and business name are reflected in a live preview pane. Once you're satisfied, copy the embed snippet and paste it on your site.

Settings available

• Accent color — the primary brand color for buttons and highlights
• Theme — light, dark, or auto (matches the visitor's system preference)
• Corner radius — pixel value for rounding the bubble and panel
• Position — bottom-right or bottom-left placement
• Welcome message — the first thing visitors see
• Widget name — displayed in the chat header
• Input placeholder — hint text shown inside the message box
• Sales instructions — guide the AI's selling style, tone, and product focus

Plans & limits

Four tiers. Free is generous enough for a solo operator to run their business on WhatsApp; paid tiers add volume, channels, analytics, and branding.

Why these numbers?

Free is sized to run one small business with modest volume — a solo safari operator, a single restaurant, a small boutique. Starter is for a growing operator with regular traffic. Pro adds team-sized volume and multi-channel reach. Team is for established operators running multiple properties or lines of business.

What's in each plan

Everything is unlocked by plan: your dashboard always shows every feature, so you can see what you'd get by upgrading. Gated features display a small "Starter" or "Pro" badge.

When a limit is reached

API responses return HTTP 429 with a structured body:

{
  "error": "plan_limit_exceeded",
  "resource": "queries",
  "current": 101,
  "limit": 100,
  "plan": "free",
  "message": "You've reached the queries limit (101/100) on your free plan. Upgrade for higher limits.",
  "upgrade_url": "/settings/billing"
}

Response headers X-Plan-Limit, X-Plan-Current, and X-Plan-Resource make it easy to inspect without parsing the body.

Billing

Payment methods

• M-Pesa — STK Push directly from the dashboard. Enter the phone number, approve on your handset, done.
• Card — Visa / Mastercard checkout for customers outside Kenya (coming soon).

All plans are priced and billed in KES — the amount you see on the pricing page is the amount you pay.

Annual billing

Pay annually and save 2 months on every paid plan. You can switch between monthly and annual from the Billing page.

Upgrades and downgrades

Upgrades take effect immediately and are prorated for the remainder of the month. Downgrades take effect at the end of your current billing period — you keep your existing limits until then. If you downgrade to a tier that doesn't include a feature you're using (e.g. Instagram channel disabled on Starter), inbound messages continue to work but new connects are blocked.

Pilots & custom limits

Running a pilot, a partnership, or a larger deployment than the standard tiers cover? Email support@docsbrew.com — we’ll work out limits and pricing that fit.

API authentication

Account-scoped endpoints (projects, leads, analytics) require an API key passed as a bearer token in the Authorization header.

Authorization: Bearer your-api-key

You can find your API key on the project's settings page in the dashboard. Keep it secret — anyone with your API key can manage your project and read lead data.

Query endpoint

Send a visitor's question and get an AI-generated response grounded in your project's knowledge base.

curl -X POST https://api.docsbrew.com/query \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What running shoes do you recommend for beginners?",
    "site_id": "site_abc123",
    "stream": false,
    "visitor_metadata": {
      "page_url": "https://mystore.com/shoes",
      "referrer": "https://google.com"
    }
  }'

{
  "answer": "For beginners, I'd recommend our CloudStep 2.0...",
  "sources": [
    {
      "document": "Running Shoes Guide",
      "section": "Picking your first pair",
      "chunk_id": "chunk_abc_0042",
      "relevance": "direct"
    }
  ],
  "confidence": "high",
  "usage": {
    "input_tokens": 1240,
    "output_tokens": 186,
    "total_tokens": 1426,
    "model": "gemini-2.5-flash"
  },
  "sales": {
    "products": [
      {
        "product_id": "prod_cloudstep_2",
        "name": "CloudStep 2.0",
        "price": 89.99,
        "currency": "USD",
        "url": "/shoes/cloudstep-2",
        "image_url": "/img/cloudstep-2.jpg",
        "in_stock": true,
        "relevance": "recommended"
      }
    ],
    "cta_actions": [
      { "label": "Add to Cart", "action_type": "add_to_cart", "url": "/cart/add?p=prod_cloudstep_2", "icon": "cart" }
    ],
    "suggestion_chips": ["What size should I pick?", "How is the arch support?"],
    "funnel_stage": "considering",
    "intent": "product_recommendation",
    "agent": "recommender"
  },
  "captured_lead": null
}

Leads endpoint

Retrieve leads captured from conversations in your project.

[
  {
    "id": "lead_001",
    "project_id": "proj_abc123",
    "conversation_id": "conv_xyz789",
    "email": "jane@example.com",
    "name": "Jane",
    "phone": null,
    "company": null,
    "source_url": "https://mystore.com/shoes/cloudstep",
    "interested_products": ["prod_cloudstep_2"],
    "funnel_stage": "ready_to_buy",
    "score": 87,
    "status": "new",
    "notes": null,
    "intelligence": {
      "score": 87,
      "confidence": "high",
      "reasoning": "Returning visitor with clear buying intent. Asked about sizing and shipping in the same session.",
      "recommended_action": "immediate_followup",
      "action_label": "Follow up today",
      "highlights": ["Returning visitor", "High engagement", "Asked about checkout"],
      "score_breakdown": {
        "engagement": "strong",
        "intent": "high",
        "fit": "excellent"
      },
      "scored_at": "2026-04-08T14:24:12Z",
      "is_scoring": false,
      "top_signals": [
        "Viewed 3 products in a single session",
        "Asked explicit pricing questions",
        "Confirmed shipping destination"
      ],
      "risks": ["No phone number captured"],
      "talking_points": [
        "Mention the current free-shipping offer",
        "Offer a sizing guide link",
        "Ask if they have a deadline for the purchase"
      ],
      "recommended_outreach": {
        "channel": "email",
        "timing": "within 2 hours",
        "opener": "Hi Jane — saw you were looking at the CloudStep 2.0. Want me to send over the sizing guide?"
      }
    },
    "created_at": "2026-04-08T14:23:00Z"
  }
]

Projects endpoint

Manage your projects programmatically.

FAQ

How long does crawling take?

Most sites with under 500 pages are fully indexed within a few minutes. Larger sites may take longer depending on page complexity and server response times.

Does the widget slow down my site?

No. The embed script is ~3KB and loads asynchronously. The chat widget itself loads in an iframe, so its JavaScript and CSS are completely isolated from your page. There's zero impact on your Core Web Vitals.

Can the AI make up information?

DocsBrew uses RAG (Retrieval-Augmented Generation), which means every response is grounded in your actual content. The AI only answers based on what it finds in your knowledge base. If it doesn't have an answer, it says so rather than guessing.

What languages are supported?

DocsBrew detects the language a visitor writes in and replies in the same language automatically — handy for tourism, hospitality, and e-commerce businesses that get customers from outside Kenya. Out of the box we handle English, Swahili, French, German, Italian, Spanish, Portuguese, Dutch, Arabic, and Chinese; admins can also pin a single reply language or restrict the whitelist per project. Free plans reply in one language; Starter unlocks two; Pro and Team unlock the full set. Full details on the pricing page.

Is my data secure?

Yes. All data is encrypted in transit (TLS 1.3) and at rest. Your content is stored in isolated project spaces. We never share your data with other customers or use it to train models. See our security headers (HSTS, CSP, X-Frame-Options) for transport-level protections.

Can I use DocsBrew with Shopify / WordPress / Squarespace?

Yes. The iframe-based embed works on any platform that allows custom HTML. For Shopify, paste the snippet in your theme's theme.liquid file. For WordPress, use a custom HTML block or your theme's footer. For Squarespace, add it via Code Injection in Settings.

What happens when I hit my query limit?

On the free tier, the widget gracefully tells visitors to try again later. No errors, no broken experiences. Upgrade to Pro for 10,000 queries/month or Team for 50,000.

Troubleshooting

Widget doesn't appear

• Check that the data-project-id attribute matches your project ID exactly
• Make sure the script tag is placed before </body>, not in <head>
• Open your browser's developer console (F12) and look for any error messages
• If you have a strict Content-Security-Policy, ensure your CSP allows iframes from your DocsBrew domain

Widget loads but shows no response

• Verify your project has crawled content — check the Knowledge Base page in the dashboard
• If you just created the project, wait a few minutes for crawling to complete
• Check the browser console for network errors (CORS, 401, 500)

Incorrect or outdated answers

• Trigger a re-crawl from the Knowledge Base page if your site content has changed
• Review your sales instructions — overly specific instructions can sometimes steer the AI away from correct answers

API returns 401 Unauthorized

• Verify your API key is correct and includes the Bearer prefix
• Check that the API key belongs to the project you're querying

Support

Need help? We're here for you.

• Email — hello@docsbrew.com
• Twitter — @docsbrew
• GitHub — github.com/docsbrew

Pro and Team customers get priority support with guaranteed response times.