Skip to content

SDK & Embed Pages

Purpose: Widget embedding and SDK documentation
Category: Integration
Pages: 1 page
Audience: Developers

SDK Chatbot Page

File: src/app/sdk-chatbot/page.tsx
Route: /sdk-chatbot
Type: Public
Purpose: Embedded chatbot widget and SDK documentation

Features

1. Widget Preview

  • Live chatbot widget demo
  • Embedded in page
  • Shows actual chatbot in action
  • Customizable theme preview

2. Embed Code Generator

  • Copy-paste embed code
  • HTML snippet
  • JavaScript SDK
  • Customization options

3. Configuration Options

  • Avatar selection
  • Color theme
  • Position (bottom-right, bottom-left, etc.)
  • Size (small, medium, large)
  • Initial greeting message
  • Popup delay

4. SDK Documentation

  • Installation instructions
  • API reference
  • Configuration options
  • Event listeners
  • Methods
  • Examples

Embed Code Format

HTML Snippet:

<!-- MachineAvatars Chatbot Widget -->
<script>
  window.MachineAvatarsConfig = {
    botId: "your_bot_id_here",
    theme: "light", // or "dark"
    position: "bottom-right",
    primaryColor: "#FF6622",
    greeting: "Hi! How can I help you today?",
    avatar: "Emma",
  };
</script>
<script src="https://cdn.machineavatars.com/widget.js" async></script>

React Component:

import { MachineAvatarsWidget } from "@machineavatars/react";

function App() {
  return (
    <MachineAvatarsWidget
      botId="your_bot_id_here"
      theme="light"
      position="bottom-right"
    />
  );
}

SDK Methods

Initialize:

MachineAvatars.init({
  botId: "your_bot_id",
  theme: "light",
});

Show/Hide:

MachineAvatars.show();
MachineAvatars.hide();
MachineAvatars.toggle();

Send Message (Programmatic):

MachineAvatars.sendMessage("Hello from code!");

Event Listeners:

MachineAvatars.on("message", (data) => {
  console.log("New message:", data);
});

MachineAvatars.on("widgetOpened", () => {
  console.log("Widget opened");
});

MachineAvatars.on("widgetClosed", () => {
  console.log("Widget closed");
});

Customization Options

Option Type Default Description
botId string Required Unique chatbot ID
theme "light" \| "dark" "light" Color theme
position "bottom-right" \| "bottom-left" \| "top-right" \| "top-left" "bottom-right" Widget position
primaryColor string "#FF6622" Brand color
greeting string "Hi! How can I help?" Initial message
avatar string "Emma" Avatar name
language string "en" Language code
zIndex number 999999 CSS z-index
showBranding boolean true Show "Powered by"

Installation Methods

Via CDN (Recommended):

<script src="https://cdn.machineavatars.com/widget.js"></script>

Via NPM:

npm install @machineavatars/widget
# or
yarn add @machineavatars/widget

Via React:

npm install @machineavatars/react

Widget Behavior

Desktop:

  • Appears in corner
  • Minimizable button
  • Expands to chat window
  • Can be dragged (optional)

Mobile:

  • Full-screen overlay
  • Slide-up animation
  • Native feel

Responsive:

  • Auto-adjusts to screen size
  • Touch-friendly
  • Keyboard accessible

Security

  • HTTPS required
  • Domain whitelist
  • Rate limiting
  • XSS protection
  • CORS configured

Analytics Integration

Track Events:

MachineAvatars.track("custom_event", {
  property1: "value1",
  property2: "value2",
});

User Identification:

MachineAvatars.identify({
  userId: "user123",
  email: "user@example.com",
  name: "John Doe",
});

API Endpoints

  • GET /v2/widget/{botId}/config - Get widget configuration
  • POST /v2/widget/{botId}/message - Send message
  • GET /v2/widget/{botId}/chat-history - Get chat history
  • POST /v2/widget/{botId}/track - Track event

Browser Support

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+
  • Mobile Safari (iOS 13+)
  • Chrome Mobile (Android 8+)

Dependencies

  • None (vanilla JavaScript)
  • Optional: React bindings

File Size

  • Main SDK: ~50KB (minified + gzipped)
  • React wrapper: +15KB

Code Preview Component

Interactive Code Editor:

  • Syntax highlighting
  • Copy button
  • Edit options
  • Live preview

Estimated Lines: ~600 lines

"Embed anywhere, customize everything."