Developers

UI Components

Audio visualizers, voice hooks, and chat components. Swap variants without changing props — the state machine drives everything.

bash

npm install @converse/sdk

API keys are server-side only

Call createWebCall(agentId) from your server. Pass only the token to the browser. Never include sk_live_* keys in client bundles.

Live Controls

Color

Theme

Audio Visualizers

Six swappable components with identical props. Change variant — nothing else.state drives all animation: idle → connecting → listening → thinking → speaking.

All-states reference — ConverseBar

idle

connecting

listening

thinking

speaking

tsx

import { ConverseBar } from '@converse/sdk/components';

// Driven by Converse voice agent state
const { agentState: state } = useConverseVoice({ publicKey, agentId });

<ConverseBar
  state={state}           // 'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking'
  size="lg"               // 'icon' | 'sm' | 'md' | 'lg' | 'xl'
  barCount={5}
  color="#7c3aed"
  // CSS overrides via custom properties on a parent:
  // --cva-bar-width: 6px
  // --cva-bar-gap: 6px
  // --cva-bar-radius: 2px
/>

ConverseBar

Vertical bars — the reference component, clean and minimal

barCount=3

barCount=5

barCount=7

barCount=12

tsx

<ConverseBar state="speaking" size="lg" barCount={5} color="#7c3aed" />

ConverseWave

SVG sine wave — flowing waveform, great for horizontal layouts

theme='dark'

theme='light'

tsx

<ConverseWave state="speaking" size="lg" color="#7c3aed" />

ConverseAura

CSS blob morph + conic gradient — no canvas, pure CSS. Premium ambient effect

size='sm'

size='md'

size='lg'

tsx

<ConverseAura state="speaking" size="lg" color="#7c3aed" />

ConverseOrb

Solid sphere + ripple rings when active — sharp and direct

dark

light

tsx

<ConverseOrb state="speaking" size="lg" color="#7c3aed" />

ConverseRadial

Canvas polar bars with motion trail — prominent centered display

tsx

<ConverseRadial state="speaking" size="lg" color="#7c3aed" />

ConverseGrid

Dot matrix — compact layouts, subtle ambient background indicator

dark

light

tsx

<ConverseGrid state="speaking" size="lg" color="#7c3aed" />

Composed Layouts

Combine any visualizer with your own chrome. These are reference patterns, not additional components.

Aurora background + Aura (Aceternity pattern)

speaking

ConverseOrb + Spotlight

tsx

// Aurora background wrapping any visualizer
<div className="relative overflow-hidden rounded-2xl bg-zinc-950
  [--aurora:repeating-linear-gradient(100deg,#7c3aed22_10%,#7c3aed33_20%,#7c3aed18_30%)]
  [background-image:var(--aurora)] [background-size:300%]
  [animation:aurora_8s_linear_infinite]">
  <ConverseAura state={agentState} size="lg" color="#7c3aed" />
</div>

// Spotlight behind orb
<div className="relative">
  <SpotlightSVG /> {/* SVG cone with feGaussianBlur stdDeviation="151" */}
  <ConverseOrb state={agentState} size="lg" color="#7c3aed" />
</div>

Minimal pill — inline control bar style

theme='dark'

speaking

theme='light'

speaking

tsx

// Inline pill — no wrapper component needed
<div className="flex items-center gap-3 px-5 py-2.5 rounded-full bg-zinc-950 border border-zinc-800">
  <ConverseBar state={agentState} size="sm" barCount={5} color="#7c3aed" />
  <div className="w-px h-7 bg-zinc-800" />
  <span className="text-sm font-semibold text-white">{label}</span>
</div>

Chat Components

Type a message below to test. Light and dark themes side by side.

Dark

AI Assistant

Online

Hi! How can I help you today?

Light

AI Assistant

Online

Hi! How can I help you today?

tsx

import { useConverseChat } from '@converse/sdk/components';

function ChatUI() {
  const { messages, isTyping, sendMessage } = useConverseChat({
    publicKey: 'pk_live_...',
    agentId: 'agent_xxx',
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id} className={m.role === 'user' ? 'text-right' : 'text-left'}>
          {m.content}
        </div>
      ))}
      {isTyping && <div>Typing…</div>}
    </div>
  );
}

useConverseVoice

The hook powering all visualizers. Handles audio, mic, and speaker output internally — just connect and go.

tsx

import { useConverseVoice, ConverseBar } from '@converse/sdk/components';

function VoiceUI() {
  const {
    voiceState,  // 'idle' | 'connecting' | 'active' | 'ended' | 'error'
    agentState,  // 'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking'
    session,     // { callId, connected }
    transcript,  // TranscriptEntry[]
    connect,
    disconnect,
    error,
  } = useConverseVoice({
    publicKey: 'pk_live_...',
    agentId: 'agent_xxx',
    onConnect: (session) => console.log('connected', session.callId),
  });

  return (
    <>
      {/* Swap any variant — agentState drives animation */}
      <ConverseBar state={agentState} size="lg" color="#7c3aed" />

      {/* Audio is handled automatically by the hook — no extra setup */}

      <button onClick={voiceState === 'active' ? disconnect : connect}>
        {voiceState}
      </button>
    </>
  );
}

Props Reference

All visualizers (identical interface — swap variants freely)

Prop	Type	Default	Description
state	'idle'\|'connecting'\|'listening'\|'thinking'\|'speaking'	'idle'	Agent conversation state — drives all animation
size	'icon'\|'sm'\|'md'\|'lg'\|'xl'	'lg'	Square container: 24 / 56 / 112 / 200 / 400 px
color	string (hex)	'#7c3aed'	Primary accent color
barCount	number	5	Bar count — ConverseBar only
className	string	—	Additional CSS class
style	CSSProperties	—	Inline style override
onClick	() => void	—	Click handler (adds cursor: pointer)

CSS custom properties (ConverseBar)

css

/* Override on a parent element */
.my-visualizer {
  --cva-bar-width:   6px;    /* default 4px  */
  --cva-bar-gap:     6px;    /* default 4px  */
  --cva-bar-radius:  2px;    /* default 999px (pill) */
}

AgentState → animation mapping

State	Bar	Wave	Aura / Orb
idle	Faint breathing, dim color	Barely visible sine	Near-invisible, static shape
connecting	Mirrored sweep (LK pattern)	Small slow wave	Slow blob, low opacity
listening	Center bar pulses	Single clean wave	Slow pulse, medium glow
thinking	Fast ping-pong sweep	Fast complex wave	Faster spin, brighter glow
speaking	Multi-octave audio simulation	High-amp dual harmonics	Full brightness, conic color, ripple rings