@verba-ai/chat-sdk

A lightweight, TypeScript SDK for embedding the Verba AI chat widget into any web application.

The SDK acts as a secure, high-performance orchestration layer that manages the injection and lifecycle of the Verba chat iframe. It supports both floating and inline mounting strategies.

Usage

1. Floating Bubble (Default)

The easiest way to integrate the chat. It creates a fixed-position action button in the bottom corner of your screen that toggles the chat window.

import { ChatSDK } from '@verba-ai/chat-sdk'

const chat = new ChatSDK({
    // Required: Your unique Verba tagId
    tagId: 'your-tag-id',

    // Optional
    theme: {
        primaryColor: '#6366f1',
        backgroundColor: '#080b14',
        textColor: '#f1f5f9',
    },

    // You can also our default theme presets
    // theme: 'light' | 'dark',

    // Optional: Configuration for the floating bubble
    bubble: {
        position: 'bottom-right',
        color: '#8b5cf6', // custom background gradient/color
        size: 56, // size in pixels
        icon: '<link>', // src to <img> tag
    },

    // Optional: Overriding the widget source url
    src: '',

    // Optional: Overriding the assistant avatar
    assistantAvatar: 'https://yoursite.com/assistant-icon.svg',
})

// Inject the bubble into the DOM
chat.init()

// Optional programmatic controls
// chat.show();
// chat.hide();
// chat.destroy();

2. Inline Mounting

If you want to render the chat inside a specific part of your page (like a dashboard panel or a dedicated contact page).

import { ChatSDK } from '@verba-ai/chat-sdk'

// Ensure the container exists in your DOM
// <div id="my-chat-container" style="height: 600px;"></div>

const chat = new ChatSDK({
    tagId: 'your-tag-id',

    // Target a CSS selector or pass an HTMLElement directly
    container: '#my-chat-container',

    // Optional: Advanced visual theming
    theme: {
        primaryColor: '#6366f1',
        backgroundColor: '#080b14',
        textColor: '#f1f5f9',
    },
})

chat.init()

3. Usage via CDN (UMD)

If you aren't using a bundler (Webpack/Vite/Rollup), you can load the SDK directly via a script tag.

<script src="https://unpkg.com/@verba-ai/chat-sdk@latest/dist/chat-sdk.umd.cjs"></script>
<script>
    const { ChatSDK } = window.VerbaChatSDK

    new ChatSDK({ tagId: 'your-tag-id' }).init()
</script>

API Reference

ChatSDK Class

The main entry point for the widget.

Methods

| Method | Description | | :---------- | :------------------------------------------------------------------------------------- | | init() | Injects the CSS and iframe into the DOM. | | show() | Makes the widget visible (animates the iframe open in floating mode). | | hide() | Hides the widget (animates the iframe closed in floating mode). | | destroy() | Completely tears down the SDK, removing all injected DOM elements, styles, and events. |

Configuration Types

ChatSDKConfig

interface ChatSDKConfig {
    /** Your Verba tag ID (Required) */
    tagId: string

    /** Where to mount the widget. Omit for floating bubble. */
    container?: string | HTMLElement

    /** Visual theme. String preset or detailed config. */
    theme?: 'light' | 'dark' | ThemeConfig

    /** Configuration for the floating bubble. */
    bubble?: ChatBubbleConfig
}

ChatBubbleConfig

interface ChatBubbleConfig {
    /** Corner position of the floating bubble (Default: 'bottom-right') */
    position?: 'bottom-right' | 'bottom-left'

    /** Background color of the bubble (Default: '#ffffff') */
    color?: string

    /** Size of the bubble in pixels (Default: 56) */
    size?: number

    /** SVG string for a custom open (chat) icon */
    icon?: string

    /** Color of the close (X) icon (Default: '#ffffff') */
    closeIconColor?: string
}

ThemeConfig

interface ThemeConfig {
    primaryColor?: string
    textColor?: string
    backgroundColor?: string
    fontFamily?: string
}