@vozia/web-sdk

Vozia AI Agent SDK for Web. Embed intelligent chat assistants into any website.

Installation

npm install @vozia/web-sdk
# or
pnpm add @vozia/web-sdk
# or
yarn add @vozia/web-sdk

Quick Start

Headless (Build Your Own UI)

import { VoziaAgent } from "@vozia/web-sdk"

const agent = new VoziaAgent({
  apiKey: "pk_xxx",
  agentId: "agent_xxx"
})

// Subscribe to events
agent.on("message", (msg) => {
  console.log(`${msg.role}: ${msg.content}`)
})

agent.on("token", (chunk) => {
  // Real-time streaming tokens
  process.stdout.write(chunk)
})

agent.on("status", ({ type }) => {
  // "connecting" | "ready" | "thinking" | "responding" | "error"
  console.log("Status:", type)
})

agent.on("error", (err) => {
  console.error("Error:", err.message)
})

// Send a message
agent.send("Hello!")

// Clean up when done
agent.destroy()

Widget (Drop-in UI)

import { VoziaAgent, VoziaWidget } from "@vozia/web-sdk"

const agent = new VoziaAgent({
  apiKey: "pk_xxx",
  agentId: "agent_xxx"
})

const widget = new VoziaWidget(agent, {
  position: "bottom-right", // or "bottom-left"
  theme: "light",           // or "dark" or "auto"
  greeting: "Hi! How can I help?",
})

// Open/close programmatically
widget.open()
widget.close()
widget.toggle()

// Clean up
widget.destroy()
agent.destroy()

API Reference

VoziaAgent

Constructor

new VoziaAgent(config: VoziaConfig)

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your Vozia API key | | agentId | string | Yes | The agent ID to connect to | | baseUrl | string | No | Custom API base URL | | sessionId | string | No | Resume an existing session | | user | object | No | End-user info (id, name, email) |

Methods

| Method | Description | |--------|-------------| | send(text: string) | Send a message to the agent | | destroy() | Clean up resources | | isReady() | Check if agent is ready | | getSession() | Get current session info |

Events

| Event | Payload | Description | |-------|---------|-------------| | message | Message | Complete message received | | token | string | Streaming token chunk | | status | Status | Status change | | error | AgentError | Error occurred | | session | Session | Session created |

VoziaWidget

Constructor

new VoziaWidget(agent: VoziaAgent, config?: WidgetConfig)

| Option | Type | Default | Description | |--------|------|---------|-------------| | position | "bottom-right" \| "bottom-left" | "bottom-right" | Widget position | | theme | "light" \| "dark" \| "auto" | "light" | Color theme | | accentColor | string | "#6366f1" | Primary color (hex) | | greeting | string | "Hi! How can I help?" | Initial greeting | | placeholder | string | "Type a message..." | Input placeholder | | zIndex | number | 9999 | CSS z-index |

Methods

| Method | Description | |--------|-------------| | open() | Open the chat panel | | close() | Close the chat panel | | toggle() | Toggle open/close | | destroy() | Remove widget from DOM |

Types

interface Message {
  id: string
  role: "user" | "agent"
  content: string
  timestamp: number
}

interface Status {
  type: "connecting" | "ready" | "thinking" | "responding" | "disconnected" | "error"
  message?: string
}

interface AgentError {
  code: "NETWORK_ERROR" | "AUTH_ERROR" | "INVALID_CONFIG" | "SESSION_ERROR" | "RATE_LIMITED" | "SERVER_ERROR" | "UNKNOWN_ERROR"
  message: string
}

interface Session {
  id: string
  agentId: string
  createdAt: number
}

Framework-Agnostic

This SDK is framework-agnostic. It works with:

• React
• Vue
• Svelte
• Angular
• Vanilla JavaScript
• Any other framework

The SDK emits events - you decide how to handle them in your app.

License

MIT