sourcebytes_bot_sdk

v1.0.10

Published

3 months ago

SourceBytes SDK makes it easy to embed customizable AI chatbots into any website or web app. Supports React integration, CDN embed script, branding customization, real-time streaming, and usage tracking.

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

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: "[email protected]",
    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: "[email protected]",
      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: "[email protected]" },
    },
    {
      id: "support-bot",
      options: { botId: "BOT_ID_2", userId: "[email protected]" },
    },
  ];

  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