VoiceAgent

The all-in-one component for adding voice AI to your React app. Includes a connect button, audio visualizer, and handles the entire conversation lifecycle.

Import


import { VoiceAgent } from '@vocobase/voice-client-sdk'
import '@vocobase/voice-client-sdk/styles.css'

Basic Usage


<VoiceAgent
  apiKey="rg_live_your_api_key"
  agentName="my-agent"
/>

Props

Required Props

Prop	Type	Description
`apiKey`	`string`	Your Vocobase API key (starts with `rg_live_`)
`agentName`	`string`	The name of the agent to connect to

Callbacks

Prop	Type	Description
`onConnect`	`() => void`	Called when connection is established
`onDisconnect`	`() => void`	Called when session ends
`onError`	`(error: VoiceAgentError) => void`	Called when an error occurs
`onTranscript`	`(entry: TranscriptEntry) => void`	Called for each new message
`onSessionEnd`	`(data: SessionEndData) => void`	Called with session summary
`onReconnecting`	`(attempt: number, maxAttempts: number) => void`	Called during reconnection attempts
`onReconnected`	`() => void`	Called when reconnection succeeds

Labels

Prop	Type	Default	Description
`connectLabel`	`string`	`"Connect"`	Button text when idle
`connectingLabel`	`string`	`"Connecting..."`	Button text while connecting
`disconnectLabel`	`string`	`"Disconnect"`	Button text when connected

Visualizer

Prop	Type	Description
`visualizer`	`VisualizerOptions`	Customize the audio visualization

Visualizer Options


interface VisualizerOptions {
  barCount?: number      // Number of bars (default: 30)
  barColor?: string      // CSS color (default: "#ffffff")
  barGap?: number        // Gap between bars in px (default: 3)
  barWidth?: number      // Bar width in px (default: 4)
  barMaxHeight?: number  // Max bar height in px (default: 60)
}

Types

TranscriptEntry


interface TranscriptEntry {
  role: 'user' | 'bot'
  content: string
  timestamp: string
  latency_ms?: number
}

SessionEndData


interface SessionEndData {
  sessionId: string
  durationSeconds: number
  transcript: TranscriptEntry[]
  latencySummary: { min_ms: number; max_ms: number; avg_ms: number }
  creditsUsed: number
}

VoiceAgentError


interface VoiceAgentError {
  code: VoiceAgentErrorCode
  message: string
}
 
type VoiceAgentErrorCode =
  | 'MIC_PERMISSION_DENIED'
  | 'INVALID_API_KEY'
  | 'INSUFFICIENT_CREDITS'
  | 'CONCURRENCY_LIMIT'
  | 'AGENT_NOT_FOUND'
  | 'NETWORK_ERROR'
  | 'CONNECTION_FAILED'

Full Example


import { useState } from 'react'
import { VoiceAgent, TranscriptEntry } from '@vocobase/voice-client-sdk'
import '@vocobase/voice-client-sdk/styles.css'
 
export default function VoiceInterface() {
  const [transcript, setTranscript] = useState<TranscriptEntry[]>([])
  const [error, setError] = useState<string | null>(null)
 
  return (
    <div>
      {error && <div className="error">{error}</div>}
 
      <VoiceAgent
        apiKey={process.env.NEXT_PUBLIC_VOCOBASE_API_KEY!}
        agentName="customer-support"
        visualizer={{ barColor: '#10b981', barCount: 25 }}
        onTranscript={(entry) => setTranscript(prev => [...prev, entry])}
        onError={(err) => setError(err.message)}
        onSessionEnd={(data) => console.log('Session summary:', data)}
      />
 
      <div className="transcript">
        {transcript.map((entry, i) => (
          <div key={i} className={`message ${entry.role}`}>
            <strong>{entry.role === 'user' ? 'You' : 'Agent'}:</strong>
            <span>{entry.content}</span>
          </div>
        ))}
      </div>
    </div>
  )
}

When to Use VoiceAgent vs Hooks

Use VoiceAgent when…	Use Hooks when…
You want a quick integration	You need complete UI control
Default UI is acceptable	You’re building custom components
You want minimal code	You have specific design requirements

For custom UIs, see Hooks and the Custom UI Example.