JavaScript SDK - Native Chatbot Embed

Embed your chatbot natively using the botbyte-ai npm package or a single CDN script tag.

Overview

The BotByte JavaScript SDK is the recommended way to add a chatbot to your website. It renders natively in your page's DOM using Shadow DOM for style isolation — no iframes, no sizing issues, no cross-origin limitations.

npm Package (Recommended)

The botbyte-ai npm package provides TypeScript types, ESM/CJS builds, a React component & hook, an event system, and tree-shaking support.

Install

npm install botbyte-ai

Vanilla JavaScript / TypeScript

import { BotByte } from "botbyte-ai";
 
BotByte.init({
  chatbotId: "YOUR_CHATBOT_ID",
  position: "bottom-right",
  userContext: {
    name: "John Doe",
    email: "john@example.com",
  },
});
 
// Programmatic control
BotByte.open();
BotByte.close();
BotByte.toggle();
BotByte.sendMessage("Hello!");
BotByte.setUserContext({ name: "Jane" });
BotByte.destroy();
 
// Events
BotByte.on("message", (msg) => console.log(msg.role, msg.content));
BotByte.on("ready", (config) => console.log("Loaded:", config.chatTitle));
BotByte.on("open", () => console.log("Opened"));
BotByte.on("close", () => console.log("Closed"));
BotByte.on("error", (err) => console.error(err));

React Component

import { BotByteChat } from "botbyte-ai/react";
 
export default function App() {
  return (
    <BotByteChat
      chatbotId="YOUR_CHATBOT_ID"
      position="bottom-right"
      userContext={{ name: "John" }}
      onReady={(config) => console.log(config)}
      onMessage={(msg) => console.log(msg)}
      onOpen={() => console.log("opened")}
      onClose={() => console.log("closed")}
      onError={(err) => console.error(err)}
    />
  );
}

React Hook

import { useBotByte } from "botbyte-ai/react";
 
function ChatButton() {
  const { open, close, toggle, sdk } = useBotByte({
    chatbotId: "YOUR_CHATBOT_ID",
  });
 
  return (
    <div>
      <button onClick={open}>Open Chat</button>
      <button onClick={close}>Close Chat</button>
      <button onClick={() => sdk.current?.sendMessage("Hi!")}>Say Hi</button>
    </div>
  );
}

TypeScript Types

import type {
  BotByteInitOptions,
  ChatMessage,
  ChatbotConfig,
  BotByteEventMap,
} from "botbyte-ai";

CDN / Script Tag

For projects without a bundler, use the CDN build.

Quick Start

Add one line before </body>:

<script src="https://botbyte.in/sdk/botbyte-sdk.js" data-chatbot-id="YOUR_CHATBOT_ID"></script>

Or use the npm CDN:

<script src="https://unpkg.com/botbyte-ai/dist/botbyte.global.js" data-chatbot-id="YOUR_CHATBOT_ID"></script>

The SDK automatically:

Fetches your chatbot's configuration (colors, title, welcome message)
Renders a floating chat button
Opens a chat window when clicked
Streams AI responses in real-time
Adapts to mobile screens (fullscreen on small devices)

Programmatic Initialization

For more control, initialize manually:

<script src="https://botbyte.in/sdk/botbyte-sdk.js"></script>
<script>
  BotByte.init({
    chatbotId: "YOUR_CHATBOT_ID",
    position: "bottom-right",   // or "bottom-left"
    userContext: {
      name: "John Doe",
      email: "john@example.com",
      plan: "Pro"
    }
  });
</script>

Configuration Options

Option	Type	Default	Description
`chatbotId`	string	required	Your chatbot's ID
`position`	string	`"bottom-right"`	Button position: `"bottom-right"` or `"bottom-left"`
`userContext`	object	`null`	Key-value pairs passed to the AI for personalization
`baseUrl`	string	`"https://botbyte.in"`	API base URL (for self-hosted instances)

API Reference

After initialization, the global BotByte object exposes these methods:

`BotByte.init(options)`

Initialize the SDK with configuration options. Only call once.

`BotByte.open()`

Open the chat window programmatically.

`BotByte.close()`

Close the chat window.

`BotByte.toggle()`

Toggle the chat window open/closed.

`BotByte.setUserContext(context)`

Update user context at runtime without reinitializing:

BotByte.setUserContext({
  name: "Jane Smith",
  email: "jane@example.com",
  plan: "Enterprise"
});

`BotByte.destroy()`

Remove the chatbot from the page entirely and clean up all resources.

Framework Integration

React / Next.js

Recommended: Use the npm package instead — import { BotByteChat } from "botbyte-ai/react" provides a proper React component with lifecycle management. See the npm Package section above.

If you prefer the CDN approach in React:

import { useEffect } from 'react';
 
export default function ChatWidget({ user }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://botbyte.in/sdk/botbyte-sdk.js';
    script.async = true;
    document.body.appendChild(script);
 
    script.onload = () => {
      window.BotByte.init({
        chatbotId: 'YOUR_CHATBOT_ID',
        userContext: user ? {
          name: user.name,
          email: user.email,
        } : undefined,
      });
    };
 
    return () => {
      window.BotByte?.destroy();
      document.body.removeChild(script);
    };
  }, [user]);
 
  return null;
}

Vue.js

<script setup>
import { onMounted, onUnmounted } from 'vue';
 
const props = defineProps({ user: Object });
 
onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://botbyte.in/sdk/botbyte-sdk.js';
  script.async = true;
  document.body.appendChild(script);
 
  script.onload = () => {
    window.BotByte.init({
      chatbotId: 'YOUR_CHATBOT_ID',
      userContext: props.user || undefined,
    });
  };
});
 
onUnmounted(() => {
  window.BotByte?.destroy();
});
</script>

Angular

import { Component, OnInit, OnDestroy } from '@angular/core';
 
@Component({ selector: 'app-chat', template: '' })
export class ChatComponent implements OnInit, OnDestroy {
  ngOnInit() {
    const script = document.createElement('script');
    script.src = 'https://botbyte.in/sdk/botbyte-sdk.js';
    script.async = true;
    document.body.appendChild(script);
 
    script.onload = () => {
      (window as any).BotByte.init({
        chatbotId: 'YOUR_CHATBOT_ID'
      });
    };
  }
 
  ngOnDestroy() {
    (window as any).BotByte?.destroy();
  }
}

Features

Feature	Details
Shadow DOM	Complete style isolation from host page
Streaming	Real-time word-by-word response rendering
Markdown	Bold, italic, code blocks, links, lists, headers
File Upload	Users can attach files in the chat
Mobile Responsive	Auto fullscreen on screens under 640px
Animations	Smooth open/close, typing indicator
User Context	Personalize responses with logged-in user data
Escape to Close	Press Escape to close the chat window
Accessibility	ARIA labels on interactive elements

SDK vs Iframe Comparison

Feature	JS SDK	Iframe
No sizing issues	Yes	No
Native DOM rendering	Yes	No
Programmatic API	Full	Limited
Mobile responsive	Automatic	Manual
Style isolation	Shadow DOM	Iframe boundary
SEO impact	None	None
User context	Yes	Yes
File attachments	Yes	Yes

Troubleshooting

Chat button does not appear

Check the browser console for errors
Verify the data-chatbot-id matches your chatbot's ID
Ensure the script loads from the correct URL

Styles look broken

The SDK uses Shadow DOM, so host page styles should not interfere
Check if another script is removing the SDK's root element

CORS errors

The BotByte API allows all origins by default
If self-hosting, ensure your server returns proper CORS headers

Embedding Overview Pricing