SourceBytes SDK

npm License Downloads

Easily integrate SourceBytes AI Bots into your web applications with full support for multiple bots, custom launchers, branding options, and configuration overrides.

📚 Table of Contents

Installation
Usage in React / Next.js
Usage in Plain HTML (CDN)
Multiple Bot Integration
Configuration Options
Branding Info
Styling
Best Practices
Full Example
License

🚀 Installation

npm install sourcebytes_chatbot_sdk
# or
yarn add sourcebytes_chatbot_sdk

⚡ Usage in React / Next.js

Wrap your widget inside SourceBytesProvider and configure it:

"use client";

import { SourceBytesProvider, SourceBytesWidget, useSourceBytes } from "sourcebytes_chatbot_sdk";
import "sourcebytes_chatbot_sdk/dist/styles.css";

function MyCustomLauncher() {
  const { isOpen, toggleWidget } = useSourceBytes();
  return (
    <button onClick={toggleWidget} style={{ padding: 10, background: "blue", color: "white" }}>
      {isOpen ? "Close Chat" : "Open Chat"}
    </button>
  );
}

export default function BotIntegration() {
  const options = {
    botId: "YOUR_BOT_ID",
    userId: "user@example.com",
    onBeforeSendMessage: async ({ userId, message }) => {
      const res = await fetch("/api/v1/bot/usage", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ userId, message }),
      });

      if (!res.ok) throw new Error("Usage check failed");

      const data = await res.json();
      // returning messagesLeft from api is mandatory for sdk validation
      return {
        messagesLeft: data.messagesLeft,
        userMetadata: data.userMetadata,
      };
    },
    onMessageLimitReached: () => {
      console.warn("Message limit reached");
    },
    configOverrides: {
      widget_shape: "round",
      action_color: "#E91E63",
    },
    avatar: {
      image: "https://dev.sourcebytes.ai/media/avatar3.svg",
    },
  };

  return (
    <SourceBytesProvider options={options}>
      <SourceBytesWidget />
      <MyCustomLauncher />
    </SourceBytesProvider>
  );
}

🌐 Usage in Plain HTML (CDN)

You can also embed the widget directly via a script tag:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>SourceBytes Bot</title>
  <script src="https://cdn.jsdelivr.net/npm/sourcebytes_chatbot_sdk/dist/sourcebytes-embed.js"></script>
</head>
<body>
  <div id="sourcebytes-widget"></div>

  <script>
    SourceBytesEmbed.init({
      botId: "YOUR_BOT_ID",
      userId: "user@example.com",
      branding_info: {
        logo: "https://example.com/logo.png",
        organisation_name: "My Company"
      },
      showChatLaunchButton: true,
      welcomeScreen: true,
    });
  </script>
</body>
</html>

🤖 Multiple Bot Integration

You can integrate multiple bots by creating separate providers:

import { SourceBytesProvider, SourceBytesWidget } from "sourcebytes_chatbot_sdk";
import "sourcebytes_chatbot_sdk/dist/styles.css";

export default function MultiBotExample() {
  const bots = [
    {
      id: "sales-bot",
      options: { botId: "BOT_ID_1", userId: "user@example.com" },
    },
    {
      id: "support-bot",
      options: { botId: "BOT_ID_2", userId: "user@example.com" },
    },
  ];

  return (
    <div>
      {bots.map((bot) => (
        <div key={bot.id} style={{ marginBottom: "2rem" }}>
          <h2>{bot.id}</h2>
          <SourceBytesProvider options={bot.options}>
            <SourceBytesWidget />
          </SourceBytesProvider>
        </div>
      ))}
    </div>
  );
}

⚙ Configuration Options

Option	Type	Required	Description
`botId`	`string`	✅	The Bot ID from your SourceBytes dashboard
`userId`	`string`	✅	Unique ID for the user (email, UUID, etc.)
`onBeforeSendMessage`	`function`	❌	Hook before message is sent (can validate usage)
`onMessageLimitReached`	`function`	❌	Callback when user hits message limit
`configOverrides`	`object`	❌	UI customization for widget
`customConversationStarters`	`array`	❌	Predefined starter messages
`avatar`	`{ image: string }`	❌	Bot avatar image URL
`branding_info`	`{ logo: string, organisation_name: string }`	❌	Add company branding

🎨 Branding Info

You can customize the bot branding:

<SourceBytesProvider
  options={options}
  branding_info={{
    logo: "https://example.com/logo.png",
    organisation_name: "SourceBytes AI"
  }}
>
  <SourceBytesWidget />
</SourceBytesProvider>

🎨 Styling

The SDK ships with default styles:

import "sourcebytes_chatbot_sdk/dist/styles.css";

You can override styles with CSS variables:

:root {
  --sourcebytes-primary-color: #E91E63;
}

✅ Best Practices

Always pass a unique userId for tracking.
Use onBeforeSendMessage for rate-limiting and quota checks.
For multiple bots, wrap each in its own SourceBytesProvider.
Use branding_info for consistent brand identity.

📄 License

MIT

Package detail

sourcebytes_chatbot_sdk

readme