Sandbox Developer Documentation

Build with Botly Pro in minutes.

One CSS link. One script tag. Two lines of JavaScript. Your fully branded AI chatbot is live on any site, any stack, zero external dependencies.

Installation

CDN or self-hosted

Bot Memory

Train your bot with data

M-Pesa & Cards

Direct payments & links

Webhook API

Connect your own backend

React / Next.js

Framework integration

JS API Reference

Methods & events

Live Interactive Studio: Test, brand, and configure your chatbot visually inside the Botly Pro Customizer Studio, then copy your production embed code in 1 click.

Installation

Add Botly Pro to any website using the jsDelivr CDN. No npm, no build step, no framework required.

HTML

<!-- In <head> -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.css">

<!-- Before </body> -->
<script src="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.js"></script>
<script>
  BotlyChatbot.init({
    company: { name: "Your Company", supportPhone: "+254 700 000 000" },
    bot: { name: "Botly Pro", title: "AI Assistant" },
    goal: "lead_generation"
  });
</script>

Include the stylesheet

Add the <link> tag inside your <head>. Loads the widget design system.

Include the script

Add the <script> before </body>. Exposes the global BotlyChatbot object.

Call BotlyChatbot.init()

Pass your company name, bot persona, memory, and payments. The bot floats ready in the bottom corner.

Full Configuration Reference

JavaScript

BotlyChatbot.init({
  company: {
    name: "Acme Corp",
    supportPhone: "+254 700 000 000",
    supportEmail: "support@acme.com",
    websiteUrl: "https://acme.com"
  },
  bot: {
    name: "Ace",
    title: "Acme AI Assistant",
    avatar: "https://acme.com/bot-icon.svg",
    greeting: "Hi! I'm Ace from Acme. How can I help you today?",
    typingDelayMs: 400,
    initialQuickReplies: [
      { label: "Our Services", payload: "What services do you offer?" },
      { label: "Pricing & Plans", payload: "How much does it cost?" }
    ]
  },
  goal: "lead_generation", // "lead_generation" | "payment_checkout" | "customer_support" | "consultation_booking"
  theme: {
    primaryColor: "#18221c",
    primaryGradient: "linear-gradient(135deg, #18221c 0%, #26352c 100%)",
    accentColor: "#9be553",
    headerBg: "#18221c",
    userBubbleBg: "#18221c"
  },
  currency: { code: "KES", symbol: "KSh" },
  customFaqs: [
    {
      keywords: ["price", "cost", "how much"],
      answer: "Our standard plan starts at KSh 1,299 per month."
    }
  ],
  checkout: {
    enabled: true,
    currency: "KES",
    mpesa: {
      enabled: true,
      type: "paybill",          // "paybill" | "till" | "phone"
      number: "522522",
      accountName: "Acme Corp",
      accountNumber: "ORDER-001" // optional
    },
    card: {
      enabled: true,
      url: "https://checkout.stripe.com/c/pay/cs_live_123",
      gateway: "Stripe",        // "Stripe" | "Flutterwave" | "PayPal" | "Paystack" | "Pesapal" | "Custom"
      label: "Pay with Card / Stripe"
    }
  },
  api: {
    enabled: false,
    endpoint: "https://your-api.com/webhook",
    mode: "hybrid"
  }
});

company

Property	Type	Status	Description
`name`	string	Required	Your brand name. Appears in bot replies and escalation messages.
`supportPhone`	string	Optional	Phone shown when users request a human agent or need phone handover.
`supportEmail`	string	Optional	Support email shown in escalation replies.
`websiteUrl`	string	Optional	Website URL used for context and citation attribution.

bot

Property	Type	Status	Description
`name`	string	Optional	Bot display name. Default: "Botly Pro"
`title`	string	Optional	Subtitle below name. Default: "AI Assistant"
`avatar`	string (URL)	Optional	URL to bot avatar image (SVG or PNG). Stays isolated from site logo.
`greeting`	string	Optional	Opening message. Supports markdown bold.
`typingDelayMs`	number	Optional	Delay before bot replies (default: 400ms).
`initialQuickReplies`	array	Optional	Array of { label, payload } quick-reply chips.

theme

Property	Description
`primaryColor`	Main brand color (buttons, header, user bubbles).
`primaryGradient`	CSS gradient for launcher button and header background.
`accentColor`	Accent/highlight color. Default: #9be553 (lime).
`headerBg`	Chat header background color.
`userBubbleBg`	User message bubble color.

goals

Value	Description
`"lead_generation"`	Captures customer name and phone, routes to sales team.
`"payment_checkout"`	Enables in-chat M-Pesa / Card checkout with payment method selection prompt.
`"customer_support"`	FAQ answering, troubleshooting, and human agent phone handover.
`"consultation_booking"`	Pre-qualifies leads and prompts booking a consultation.
`"product_showcase"`	Showcases offerings and drives intent towards checkout.
`"appointment_booking"`	Collects appointment date, time, and service requirements.

Bot Memory

Give your bot company-specific knowledge in three ways — all can be combined.

1. Paste Company Data (customFaqs)

JavaScript

customFaqs: [
  {
    keywords: ["hours", "open", "when", "location"],
    answer: "We are open Monday to Friday, 8am-6pm EAT at Westlands, Nairobi."
  },
  {
    keywords: ["price", "cost", "how much"],
    answer: "Plans start at KSh 999 per month."
  }
]

2. Website Sitemap Crawler & Multi-Page Indexing (customKnowledge)

Botly Pro can scan your company website link, discover all key pages (Home, Services, Pricing, FAQ, Support, Policies), and allow you to select which pages to train into bot memory. When trained, the bot automatically tunes its persona, greeting, and adaptive quick replies around the website's content.

JavaScript

customKnowledge: [
  {
    source: "website",
    sourceUrl: "https://acme.com",
    question: "What does Acme do?",
    answer: "Acme helps businesses automate customer communication with AI.",
    keywords: ["acme", "about", "services", "what do you do"]
  },
  {
    source: "website",
    sourceUrl: "https://acme.com/pricing",
    question: "What are Acme's pricing packages?",
    answer: "Sprint packages start at $3,500 with ongoing monthly retainer options.",
    keywords: ["pricing", "plans", "cost", "rates"]
  }
]

In the Botly Pro Customizer Studio (Step 4: Teach Your Bot > Website Link), paste your website link to scan the sitemap, check/uncheck pages to train, and auto-tune the bot's greeting and quick replies in 1 click.

3. Live Backend API

Connect a backend that receives queries and returns answers in real time. See Webhook API below.

HTML Drop-in Embed

HTML

<!DOCTYPE html><html><head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.css">
</head><body>
  <script src="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.js"></script>
  <script>
    BotlyChatbot.init({
      company: { name: "Your Company", supportPhone: "+254 700 000 000" },
      bot: { name: "Ace", greeting: "Hi! How can I help you today?" },
      goal: "lead_generation",
      theme: { primaryColor: "#18221c", accentColor: "#9be553" }
    });
  </script>
</body></html>

React / Next.js

JSX (Next.js App Router)

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <link rel="stylesheet"
          href="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.css" />
      </head>
      <body>
        {children}
        <Script
          src="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.js"
          strategy="afterInteractive"
          onLoad={() => {
            window.BotlyChatbot.init({
              company: { name: "Your Company", supportPhone: "+254 700 000 000" },
              bot: { name: "Ace" },
              goal: "lead_generation"
            });
          }}
        />
      </body>
    </html>
  );
}

WordPress

PHP (functions.php)

add_action('wp_footer', function() { ?>
  <link rel="stylesheet"
    href="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.css">
  <script src="https://cdn.jsdelivr.net/gh/NextAIStudios/chatbot@main/dist/insurance-chatbot.js"></script>
  <script>
    BotlyChatbot.init({
      company: { name: "<?php bloginfo('name'); ?>", supportPhone: "+254 700 000 000" },
      bot: { name: "Botly Pro", title: "AI Assistant" },
      goal: "customer_support"
    });
  </script>
<?php });

Webhook & Live Backend API

Open Sandbox Simulator

JavaScript — Config

BotlyChatbot.init({
  api: {
    enabled: true,
    endpoint: "https://your-api.com/botly/query",
    mode: "hybrid",      // "hybrid" | "api_only"
    method: "POST",
    authBearer: "your-secret-token"
  }
});

POST Body Sent to Your Server

JSON

{ "message": "What are your hours?", "sessionId": "session_web_abc123", "company": "Acme Corp" }

Expected Response

JSON

{
  "reply": "We are open Monday-Friday, 8am-6pm EAT.",
  "quickReplies": [{ "label": "Book now", "payload": "I want to book an appointment" }]
}

Node.js Express Example

JavaScript

import express from 'express';
const app = express();
app.use(express.json());

app.post('/botly/query', (req, res) => {
  const { message, sessionId } = req.body;
  res.json({
    reply: `Here's what I found about "${message}"...`,
    quickReplies: [{ label: "Talk to someone", payload: "I want to speak to a person" }]
  });
});
app.listen(3000);

M-Pesa Payments

Enable in-chat M-Pesa. When users type "pay with mpesa" or click the M-Pesa option, the bot presents paybill or till details. After payment, users submit their confirmation code (e.g. UIC8E69GLQ), which the bot validates and records in captured leads.

JavaScript

checkout: {
  enabled: true,
  currency: "KES",
  mpesa: {
    enabled: true,
    type: "paybill",          // "paybill" | "till" | "phone"
    number: "522522",
    accountName: "Acme Corp",
    accountNumber: "ORDER-001" // optional
  }
}

Card & External Checkout Link

Direct users to credit card payments or hosted checkout (Stripe, Flutterwave, PayPal, Paystack, Pesapal, or custom links).

JavaScript

checkout: {
  enabled: true,
  currency: "USD",
  card: {
    enabled: true,
    url: "https://checkout.stripe.com/c/pay/cs_live_example",
    gateway: "Stripe",        // "Stripe" | "Flutterwave" | "PayPal" | "Paystack" | "Pesapal" | "Custom"
    label: "Pay with Card / Stripe"
  }
}

Lead Tracking

All captured leads are stored in localStorage under botly_captured_leads and viewable in the Sandbox Leads Manager.

JavaScript

const leads = BotlyChatbot.getLeads();   // array of lead objects
BotlyChatbot.exportLeadsCSV();           // downloads .csv file
BotlyChatbot.clearLeads();               // clears from localStorage

JavaScript API

Method	Description
`BotlyChatbot.init(config)`	Initialize the widget. Call once after script loads.
`BotlyChatbot.open()`	Programmatically open the chat window.
`BotlyChatbot.close()`	Close the chat window.
`BotlyChatbot.toggle()`	Toggle open/closed state.
`BotlyChatbot.triggerAction(text)`	Send a message as if the user typed it.
`BotlyChatbot.reset()`	Clear conversation and reset to greeting.
`BotlyChatbot.getLeads()`	Returns array of all captured leads.
`BotlyChatbot.exportLeadsCSV()`	Downloads leads as a .csv file.
`BotlyChatbot.clearLeads()`	Clears all stored leads from localStorage.
`BotlyChatbot.getKnowledge()`	Returns current trained knowledge entries.
`BotlyChatbot.resetKnowledge()`	Clears trained knowledge.

Events

JavaScript

window.addEventListener('botly:lead', (e) => {
  console.log('Lead captured:', e.detail);
  // { name, phone, inquiredNeed, timestamp }
});

window.addEventListener('botly:payment', (e) => {
  console.log('Payment:', e.detail);
  // { paymentMethod, mpesaCode, amount, timestamp }
});

window.addEventListener('botly:intent', (e) => {
  console.log('Intent:', e.detail.intent);
});

CSS Variables

CSS

:root {
  --ins-primary: #18221c;
  --ins-primary-gradient: linear-gradient(135deg, #18221c 0%, #26352c 100%);
  --ins-accent: #9be553;
  --ins-header-bg: #18221c;
  --ins-header-text: #ffffff;
  --ins-bot-bubble: #f1f5f9;
  --ins-bot-text: #0f172a;
  --ins-user-bubble: #18221c;
  --ins-user-text: #ffffff;
  --ins-radius: 18px;
}

Changelog

v2.5 — September 2026

Moved Docs into the Sandbox suite with direct access inside Customizer Studio
Separated M-Pesa Setup and Card & External Payment Link into distinct tabs
In-chat payment method selection prompt with dedicated M-Pesa and Card checkout cards
Anti-repetition conversation memory tracking and user repeat question handling
Support Phone field in Customizer Identity panel

v2.4 — September 2026

M-Pesa Paybill, Till & Phone number support with confirmation code verification
External checkout URL linking
Lead manager with CSV export
Full mobile widget (100vw full-screen on phones ≤600px, iOS safe-area support)
5-second safety timeout prevents infinite spinning

v2.3 — August 2026

Bot memory: paste data, website URL, live API modes
Logo isolation — custom bot logo stays separate from site logo
Botly Pro Customizer Studio 5-step wizard redesign