Dialog Bot SDK

Embeddable React chat widget for Dialog bots. Drop it into any React app to get a branded floating chat launcher with realtime messaging, rich message types, theming, and optional analytics.

Package: @dialog-ai/dialog-bot-sdk

Features

• Floating chat launcher with open / minimize / clear session
• Realtime messaging over Socket.IO
• Rich messages: text (markdown), buttons, forms, cards, carousels, images
• Full theme customization (brand, colors, size, position)
• Optional analytics via bot-analytics-sdk
• Secure local storage for session tokens

Requirements

• React 18+
• React DOM 18+
• A Dialog bot service endpoint and bot token

Install

npm install @dialog-ai/dialog-bot-sdk

or

yarn add @dialog-ai/dialog-bot-sdk

Import the stylesheet once in your app (e.g. root entry or layout):

import '@dialog-ai/dialog-bot-sdk/style.css';

Quick start

import { ChatBot } from '@dialog-ai/dialog-bot-sdk';
import '@dialog-ai/dialog-bot-sdk/style.css';

function App() {
  return (
    <ChatBot
      apiDomain="https://your-bot-api.example.com"
      token="your-bot-jwt-or-api-key"
      encryptionKey="your-random-32-char-secret"
      position="right"
      theme={{
        companyName: 'Acme Support',
        logoUrl: 'https://example.com/logo.png',
        primaryColor: '#2563eb',
      }}
    />
  );
}

The widget renders a fixed launcher in the corner. Opening it starts a conversation against your bot API.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | apiDomain | string | Yes | — | Bot service REST base URL (no trailing slash), e.g. https://api.example.com | | token | string | Yes | — | Bot JWT / API key sent as Authorization: Bearer … | | encryptionKey | string | No | built-in default | AES key used for secure localStorage. Set a unique value in production | | position | 'left' \| 'right' | No | 'right' | Aligns the launcher and chat window to the left or right of the page | | offset | { x?, y? } \| number | No | { x: 20, y: 20 } | Distance from the viewport edges in px. A number applies to both axes | | theme | object | No | defaultTheme | Partial theme overrides (see Theming) | | analytics | object | No | disabled | Analytics configuration (see Analytics) | | flowId | string | No | — | Optional conversation flow id passed to the socket query |

Position

Pin the widget to either side of the viewport:

{/* Right side (default) */}
<ChatBot apiDomain="…" token="…" position="right" />

{/* Left side */}
<ChatBot apiDomain="…" token="…" position="left" />

{/* Custom edge inset */}
<ChatBot
  apiDomain="…"
  token="…"
  position="left"
  offset={{ x: 24, y: 32 }}
/>

Aliases also accepted: bottom-left, bottom-right, bl, br.

Priority: position prop → theme.widgetPosition → 'right'.

Connection notes

• REST calls go to {apiDomain}/api/v1/… (e.g. POST /api/v1/conversation).
• After a conversation is created, the SDK connects via Socket.IO using the returned connection_url (or apiDomain as fallback).
• Obtain a bot token from your Dialog bot service (e.g. POST /api/v1/bot/token).

Theming

Pass any subset of theme keys. Missing values fall back to the default light theme.

import { ChatBot, defaultTheme, themePresets } from '@dialog-ai/dialog-bot-sdk';

<ChatBot
  apiDomain="…"
  token="…"
  theme={{
    ...themePresets.modern,
    companyName: 'Acme',
    primaryColor: '#7c3aed',
  }}
/>

Built-in presets

| Preset | Use case | |--------|----------| | themePresets.default | Default light blue | | themePresets.corporate | Stronger blue, serif type, tighter radius | | themePresets.modern | Violet accent, softer surfaces | | themePresets.minimal | Near-black primary, no launcher label |

Theme keys

Brand

| Key | Type | Description | |-----|------|-------------| | companyName | string | Header title | | logoUrl | string | Header / brand logo URL | | avatarUrl | string | Bot avatar URL | | widgetLabel | string | Text next to the launcher | | showWidgetLabel | boolean | Show / hide launcher label | | inputPlaceholder | string | Composer placeholder |

Colors

| Key | Description | |-----|-------------| | primaryColor | Primary accent (header, user bubble, buttons) | | primaryColorHover | Hover / gradient end | | secondaryColor | Secondary surfaces | | backgroundColor | Chat window background | | surfaceColor | Panels / secondary areas | | textColor | Primary text | | textColorMuted | Secondary text | | borderColor | Borders / dividers | | headerTextColor | Header text / icons | | userBubbleColor | User bubble fill (defaults to primary gradient) | | userBubbleTextColor | User bubble text | | botBubbleColor | Bot bubble fill | | botBubbleTextColor | Bot bubble text | | botBubbleBorderColor | Bot bubble border | | buttonTextColor | Quick-reply / action button text | | buttonDisabledBackground | Disabled button background | | buttonDisabledText | Disabled button text | | buttonDisabledBorder | Disabled button border |

Typography & layout

| Key | Type | Description | |-----|------|-------------| | fontFamily | string | CSS font stack | | fontSizeBase | string | Base font size (e.g. 14px) | | width | number | Window width in px | | height | number | Window height in px | | borderRadius | number | Corner radius in px | | widgetPosition | 'bottom-right' \| 'bottom-left' | Deprecated — prefer the position prop | | widgetOffsetX | number | Deprecated — prefer the offset prop | | widgetOffsetY | number | Deprecated — prefer the offset prop | | zIndex | number | Stacking order (default 9999) |

Analytics

Analytics are off unless analytics.enabled is true. When enabled, these fields are required:

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Turn analytics on | | accountId | string | Analytics account id | | projectId | string | Analytics project id | | endpointUrl | string | Analytics API base URL (http / https) | | apiKey | string | Analytics API key | | userId | string | Optional end-user id |

<ChatBot
  apiDomain="…"
  token="…"
  analytics={{
    enabled: true,
    accountId: 'acc_enterprise_01',
    projectId: 'proj_chatbot_v2',
    endpointUrl: 'https://analytics.example.com',
    apiKey: 'your-analytics-api-key',
    userId: 'user_123',
  }}
/>

Tracked events include widget open / close / minimize, messages sent and received, and chat cleared.

Exports

| Export | Description | |--------|-------------| | ChatBot | Main widget component | | ThemeProvider / useTheme | Theme context (advanced) | | defaultTheme | Default theme object | | themePresets | Named theme presets | | POSITIONS | Position constants (left, right, …) | | normalizePosition | Normalize position aliases | | setConfig / getConfig | Imperative runtime config helpers |

Styles:

import '@dialog-ai/dialog-bot-sdk/style.css';

CDN (UMD)

<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@dialog-ai/dialog-bot-sdk/dist/style.css" />
<script src="https://unpkg.com/@dialog-ai/dialog-bot-sdk/dist/dialog-bot-sdk.umd.js"></script>

DialogBotSDK is available on window (see build name in the Vite config). Prefer the npm ESM build for React apps.

Local development

npm install
npm run dev       # demo app at Vite default URL
npm run build     # emit dist/
npm run pack:check

Demo env vars (see .env.example):

| Variable | Purpose | |----------|---------| | VITE_API_DOMAIN | Bot API base URL | | VITE_TOKEN | Bot token | | VITE_ENCRYPTION_KEY | Storage encryption key | | VITE_ANALYTICS_* | Optional analytics for the demo |

These env vars are only for the demo app. Library consumers must pass config through ChatBot props.

Publish

npm run build
npm publish --access public

prepublishOnly runs the build automatically before publish.

License

MIT