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_bot_sdk
# or
yarn add sourcebytes_bot_sdk

⚡ Usage in React / Next.js

Wrap your widget inside SourceBytesProvider and configure it:

"use client";

import { SourceBytesProvider, SourceBytesWidget, useSourceBytes } from "sourcebytes_bot_sdk";
import "sourcebytes_bot_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",
    apiUrl: "https://api_base_url/",
    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://image/media/avatar.svg",
    },
  };

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

🌐 Usage in Plain HTML (CDN)

You can embed the widget directly via a script tag:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>SourceBytes Bot Example</title>
  <script src="https://cdn.jsdelivr.net/npm/sourcebytes_bot_sdk/dist/sourcebytes-embed.js"
          data-sourcebytes-bot-id="bot_123"
          data-sourcebytes-api-url="https://api_base_url"
          data-sourcebytes-avatar="https://example.com/avatar.png"
          data-sourcebytes-branding-logo="https://example.com/logo.png"
          data-sourcebytes-container="my-sourcebytes-chat">
  </script>

</head>
<body>
  <!-- Chatbot container will be auto-created if not present -->
  <div id="my-sourcebytes-chat"></div>
</body>
</html>

Manual initialization (no auto-init) - HTML (CDN)

If you don’t want <script> auto-parsing, you can manually call:

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

  <script>
    SourceBytesEmbed.init("sourcebytes-widget",{
      botId: "123456789...",
      apiUrl: "https://api_base_url/",
      userId: "user@example.com",
      branding_info: {
        logo: "https://example.com/logo.png",
      },
      showChatLaunchButton: true,
      welcomeScreen: true,
    });
  </script>
</body>
</html>

🤖 Multiple Bot Integration

You can integrate multiple bots by creating separate providers:

import { SourceBytesProvider, SourceBytesWidget } from "sourcebytes_bot_sdk";
import "sourcebytes_bot_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
`apiUrl`	`string`	✅	API URL is required (example: https://sourcebytes.ai/)
`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 }`	❌	Add company logo

🎨 Branding Info

You can customize the bot branding:

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

🎨 Styling

The SDK ships with default styles:

import "sourcebytes_bot_sdk/dist/styles.css";

You can add this style inside <head></head> tag for HTML integration:

<style>
      /* === Reset / Base === */
      *,
      *::before,
      *::after {
        box-sizing: border-box;
        margin: 0;
        padding: 0;
      }

      html {
        line-height: 1.5;
        -webkit-text-size-adjust: 100%;
        -moz-tab-size: 4;
        tab-size: 4;
      }

      body {
        font-family: Arial, Helvetica, sans-serif;
        background-color: hsl(var(--background));
        color: hsl(var(--foreground));
      }

      /* === Utility Classes === */
      .text-balance {
        text-wrap: balance;
      }

      /* === CSS Variables (Light Mode) === */
      :root {
        --background: 0 0% 100%;
        --foreground: 0 0% 3.9%;
      }
    </style>

✅ 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_bot_sdk

readme