@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 { VerbaChat } from '@verba-ai/chat-sdk'

const chat = new VerbaChat({
    // 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 { VerbaChat } from '@verba-ai/chat-sdk'

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

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

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

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

    // Optional: Show a list of previous conversations
    withThreadList: true,

    // Optional: Required for authenticated sessions
    token: 'your-jwt-token',
})

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 { VerbaChat } = window.VerbaChatSDK

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

API Reference

VerbaChat Class

The main entry point for the widget.

Methods

| Method | Description | | :---------- | :------------------------------------------------------------------------------------- | | init() | Injects the CSS and iframe into the DOM. Returns a VerbaChat instance. | | 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. |

Communication & Security

The SDK communicates with the embedded chat widget via a secure window.postMessage bridge.

Origin Validation

To ensure security, the SDK enforces strict origin validation:

• Outgoing: Messages are only sent to the trusted targetOrigin (default: https://embed.verba.chat).
• Incoming: The SDK ignores any messages that do not originate from the allowed widget source.

Message Protocol

Internally, the SDK uses a namespaced payload structure to avoid collisions with other scripts on the host page:

interface PostMessagePayload<T> {
    source: 'verba-chat-sdk'
    type: MessageType
    data: T
}

Configuration Types

VerbaChat

interface VerbaChat {
    container: HTMLElement | null
    iframe: HTMLIFrameElement | null
    bubble: HTMLButtonElement | null
}

VerbaChatConfig

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

    /**
     * Where to mount the widget iframe.
     * - A CSS selector string (e.g. `'#chat-root'`)
     * - An `HTMLElement` reference
     * - Omit for a floating bubble fixed to the viewport corner.
     */
    targetElement?: string | HTMLElement

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

    /** Configuration for the floating bubble. Has no effect when `targetElement` is provided. */
    bubble?: ChatBubbleConfig

    /** Optional: Custom assistant avatar URL. */
    assistantAvatar?: string

    /**
     * Optional: JWT token for authenticated sessions.
     * Required when the widget is configured to require authentication.
     */
    token?: string

    /**
     * Optional: Token environment passed with the authentication token.
     */
    tokenEnvironment?: string

    /**
     * Optional: Enable the thread list panel.
     * When `true`, users can browse and resume previous conversations.
     * When `false` (default), only a single new chat thread is shown.
     * @default false
     */
    withThreadList?: boolean

    /** Optional: Override the default widget source URL. */
    src?: string
}

MessageType

type MessageType = 'INIT_WIDGET' | 'READY'

PostMessagePayload

interface PostMessagePayload<T = unknown> {
    /** Namespace guard — prevents collisions with other postMessage users. */
    source: 'verba-chat-sdk'
    type: MessageType
    data: T
}

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

    /** Color of the chat icon stroke (Default: '#ffffff') */
    chatIconStrokeColor?: string

    /** Custom CSS color (rgba or hex) for the bubble's box-shadow */
    shadowColor?: string
}

ThemeConfig

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