daba-agent

Embeddable voice AI assistant widget for dabalabs projects. Drop it into any site and visitors can press Ctrl+Space, talk in any language, and get a spoken reply — the agent can also read the page, fill out and submit forms, and navigate to other pages on request.

Works natively in Plain HTML, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, and any modern JavaScript stack.

Install

npm install @dabalabs/agent

Quick Start

1. Web Component (<daba-agent>) — Works in Any JS Framework / HTML

Simply import @dabalabs/agent (or @dabalabs/agent/custom-element) and use <daba-agent> directly in your HTML or JSX/Vue/Svelte template:

<daba-agent
  project-id="YOUR_PROJECT_ID"
  api-key="YOUR_API_KEY"
  position="bottom-right"
></daba-agent>

Plain HTML / Script Tag

<script src="https://unpkg.com/@dabalabs/agent/dist/daba-agent.min.js"></script>
<daba-agent project-id="YOUR_PROJECT_ID" api-key="YOUR_API_KEY"></daba-agent>

Vue 3 / Nuxt 3

<script setup>
import '@dabalabs/agent/custom-element';
</script>

<template>
  <daba-agent
    project-id="YOUR_PROJECT_ID"
    api-key="YOUR_API_KEY"
    position="bottom-right"
  />
</template>

Svelte / SvelteKit / Astro

<script>
  import '@dabalabs/agent/custom-element';
</script>

<daba-agent project-id="YOUR_PROJECT_ID" api-key="YOUR_API_KEY" />

2. React Component (<DabaAgent />) — React & Next.js

Import it at the top of the file like any other component and pass the configuration as props. No useEffect, no dynamic import(), no next/dynamic.

"use client";

import { DabaAgent } from "@dabalabs/agent/react";

export function App() {
  return (
    <DabaAgent
      projectId="YOUR_PROJECT_ID"
      apiKey="YOUR_API_KEY"
      position="bottom-right"
      historyEnabled
      launcher={{ size: "64px", iconText: "👋" }}
      panel={{ width: "440px", height: "700px" }}
      onStatusChange={(status) => console.log("Agent status:", status)}
    />
  );
}

Props are DabaAgentOptions minus container — the component owns where the widget mounts. They are compared by value, so an inline theme={{ accentColor: "#0c8c5e" }} does not rebuild the widget on every render of the parent.

Note the entry point. @dabalabs/agent/react gives you the React component; the package root gives you the class. Both are named DabaAgent, because in each context that is the right thing to get:

import { DabaAgent } from "@dabalabs/agent";        // class  — new DabaAgent({...})
import { DabaAgent } from "@dabalabs/agent/react";  // component — <DabaAgent {...} />

3. Programmatic Class API (new DabaAgent())

import { DabaAgent } from "@dabalabs/agent";

const agent = new DabaAgent({
  projectId: "YOUR_PROJECT_ID",
  apiKey: "YOUR_API_KEY",
  position: "bottom-right",
});

Every entry point is safe to import on a server: the module evaluates to nothing that touches the DOM, so Next.js, Remix and Astro can render the file that imports it. The widget itself is created when you construct it or when the component mounts, both of which only ever happen in a browser.

Get a project ID and API key from the Developer section of your dabalabs dashboard — the same API key used for the dabalabs video player works here too.

Custom Events on Web Component (<daba-agent>)

The <daba-agent> element dispatches native DOM Custom Events:

• daba-status-change (e.detail.status) — Fired when status changes (idle, connecting, listening, thinking, speaking)
• daba-transcript (e.detail: { role, text, isFinal }) — Fired on user or agent transcript deltas
• daba-error (e.detail.error) — Fired on network or session errors

Example:

const agentEl = document.querySelector('daba-agent');
agentEl.addEventListener('daba-status-change', (e) => {
  console.log('Status:', e.detail.status);
});

API keys are publishable

The API key is meant to sit in your site's frontend source, the same trust model as a Stripe.js or Google Maps JS key. Server-side, it's restricted to the exact origins you list when you create it, and to the one agent project it was scoped to. It can't create, modify, or delete anything, and it can be revoked instantly from your dashboard.

Options

| Option / Attribute | Type | Description | | --- | --- | --- | | projectId / project-id | string | Your agent project ID from the dashboard | | apiKey / api-key | string | Your publishable API key | | position | "bottom-right" \| "bottom-left" \| "top-right" \| "top-left" | Corner of the viewport for the default badge (default: "bottom-right"). | | accentColor / accent-color | string | Accent color hex for the badge's active-state indicator | | hotkey | string \| null | Keyboard shortcut. A combination ("ctrl+space", "alt+k") toggles the assistant. A modifier held alone ("hold:ctrl", also hold:alt, hold:shift, hold:meta) starts it after ~600ms and never stops it — the launcher ends a conversation. The hold is abandoned the moment another key or a click joins it, so Ctrl+C and a Mac's Control-click never trip it. Defaults to alt+space on macOS (the OS takes Ctrl+Space) and ctrl+space elsewhere. null disables it. | | historyEnabled / history-enabled | boolean | Keep past conversations in this browser so the visitor can go back to one. Off by default — see Where your visitors' data lives. | | launcher.size / launcher-size | CSS length | The launcher button (default 56px; 52px below 480px wide, which an explicit value overrides). | | launcher.iconSize / launcher-icon-size | CSS length | The mark inside the button (default 100%). | | launcher.iconUrl / launcher-icon-url | string | Replace the mark with an image. | | launcher.iconSvg / launcher-icon-svg | string | Replace the mark with inline SVG. Wins over iconUrl, and unlike an <img> it survives a strict img-src CSP and can inherit currentColor. Sanitised before it is inserted. | | launcher.iconText / launcher-icon-text | string | Replace the mark with an emoji or a letter or two. | | launcher.shape / launcher-shape | "rounded" \| "circle" \| "pill" | The launcher's silhouette. | | launcher.label / launcher-label | string | Text beside the mark, turning the badge into a labelled pill. | | panel.width / panel-width | CSS length | The chat panel (default 400px). Ignored below 480px wide, where the panel goes full-screen. | | panel.height / panel-height | CSS length | The chat panel (default 740px), still clamped to the viewport. | | logoUrl / logo-url | string | Your logo in the panel header and on the intro screen. | | logoSvg / logo-svg | string | The same, as inline SVG. | | iconBackgroundColor / icon-background-color | string | Recolour the shipped mark's background, in the launcher and the panel. | | iconMarkColor / icon-mark-color | string | Recolour the shipped mark's centre shape. | | mode | "hybrid" \| "voice" \| "chat" | Which media the assistant offers (default: the project's dashboard setting, then hybrid). | | theme | DabaTheme | Colour and shape overrides — accentColor, surfaceColor, textColor, radius, fontFamily, and theme: "auto" \| "light" \| "dark". | | intro | DabaIntro | The first-open screen: headline, subheadline, suggestedPrompts, optional media. | | uiLanguage / ui-language | string | BCP-47 code for the panel's own chrome, or "auto" to follow the page's lang. Independent of what the assistant replies in. | | direction | "auto" \| "ltr" \| "rtl" | Text direction of the panel (default auto). | | gatewayUrl / gateway-url | string (optional) | Base URL of the gateway (defaults to "https://api.dabalabs.com") | | onStatusChange | (status: DabaAgentStatus) => void | Fired as the agent moves through status lifecycle (React / JS API) | | onTranscript | (role: "user" \| "agent", text: string, isFinal: boolean) => void | Fired with transcript deltas (React / JS API) | | onError | (error: DabaError) => void | Fired on connection or session errors (React / JS API) |

Methods (on agent instance or element.dabaAgent)

• agent.toggle() — start or stop a session
• agent.sendText(text) — send a text turn
• agent.openChat() / closeChat() / toggleChat() — the panel
• agent.resetConversation() — start a fresh thread
• agent.listConversations() — the archive, newest first (empty unless historyEnabled)
• agent.openConversation(id) — reopen an archived thread as the live one
• agent.deleteConversation(id) / agent.clearHistory()
• agent.destroy() — tear down the session, release the microphone, remove the badge, and detach all listeners
• agent.currentStatus — the current DabaAgentStatus
• agent.isActive — whether a session is currently running

What the agent can do

• Talk. Full duplex voice in and out over a single realtime connection — no separate transcription/TTS round trip.
• Read the page. On session start, the agent is given the page title, visible text, navigable links, and form fields, so it can answer questions about the page and knows what it can act on.
• Fill out and submit forms. The agent fills fields by label, then confirms with the visitor before submitting — it never submits silently. Password, card, and other sensitive-looking fields are refused outright, whether marked or not.
• Navigate. Ask it to go to another page and it will, resuming the same conversation on the other side rather than starting over.

Security guards

• data-daba-agent-ignore on any element (or a container) excludes it and its subtree from page reading and from form-filling.
• data-daba-agent-restricted on <html>, or <meta name="daba-agent-restricted"> in <head>, opts an entire page out — the agent won't read the page or start a session there at all. Use this on account, billing, or checkout pages.
• Password fields, payment fields (autocomplete="cc-*"), and labels that read like a PIN or security code are never filled or spoken back, regardless of how the model was asked.

Where your visitors' data lives

Everything the widget stores is in the visitor's own browser. None of it is sent anywhere by the widget itself.

| What | Where | How long | | --- | --- | --- | | The open conversation's id and transcript | sessionStorage | The tab. A conversation is a visit, not an identity. | | A short-lived key for resuming a voice session across a page navigation | sessionStorage | 30 seconds | | Past conversations, only with historyEnabled | localStorage | 30 days, 20 conversations |

historyEnabled is off by default on purpose: an archive outlives the tab, and on a shared or public machine that is a decision an embed should make deliberately rather than inherit. When it is on, the visitor gets a history button in the panel header and can delete any single thread or clear the lot.

Browser support

Requires WebSocket, AudioContext, and getUserMedia — every evergreen browser. The widget itself renders no UI beyond the floating badge, so it has no layout dependencies on the host page.

License

MIT

Environments

By default the widget talks to DabaLabs production. Point it at staging with env:

<div data-daba-agent
  data-project-id="YOUR_PROJECT_ID"
  data-api-key="YOUR_API_KEY"
  data-daba-env="staging"
></div>

new DabaAgent({
  // ...
  env: "staging",
});

| env | Gateway | |---|---| | omitted | https://api.dabalabs.com | | "production" | https://api.dabalabs.com | | "staging" | https://api-staging.dabalabs.com |

Production is the default in every direction — an embed that says nothing about its environment is a live site, so staging has to be asked for by name. An unrecognised value warns in the console and falls back to production rather than throwing, so a typo cannot take a customer's page down.

gatewayUrl still overrides env when both are given: it is the only option that can name a host neither tier covers (a self-hosted deployment, a local gateway).