Quick Start

Get a working voice agent in your React app in under 5 minutes.

The Minimal Example

Here’s everything you need for a working voice interface:

App.tsx


import { VoiceAgent } from '@vocobase/voice-client-sdk'
import '@vocobase/voice-client-sdk/styles.css'
 
export default function App() {
  return (
    <VoiceAgent
      apiKey="rg_live_your_api_key"
      agentName="my-agent"
      onTranscript={(entry) => {
        console.log(`${entry.role}: ${entry.content}`)
      }}
      onError={(error) => {
        console.error(error.message)
      }}
    />
  )
}

That’s it! This gives you:

✅ Connect/disconnect button
✅ Audio visualization while speaking
✅ Automatic microphone handling
✅ Connection state management
✅ Automatic reconnection on network issues

What Happens When You Connect


1. User clicks "Connect"
         ↓
2. Browser requests microphone permission
         ↓
3. SDK establishes secure connection
         ↓
4. User speaks → AI listens
         ↓
5. AI responds → User hears response
         ↓
6. Transcript updates in real-time
         ↓
7. User clicks "Disconnect" or closes tab
         ↓
8. Session ends, metrics available

Adding Transcript Display

Show the conversation as it happens:

App.tsx


import { useState } from 'react'
import { VoiceAgent } from '@vocobase/voice-client-sdk'
import '@vocobase/voice-client-sdk/styles.css'
 
export default function App() {
  const [messages, setMessages] = useState<Array<{role: string, content: string}>>([])
 
  return (
    <div>
      <VoiceAgent
        apiKey="rg_live_your_api_key"
        agentName="my-agent"
        onTranscript={(entry) => {
          setMessages(prev => [...prev, entry])
        }}
      />
 
      <div className="transcript">
        {messages.map((msg, i) => (
          <div key={i} className={msg.role}>
            <strong>{msg.role}:</strong> {msg.content}
          </div>
        ))}
      </div>
    </div>
  )
}

Handling Session End

Get session metrics when the conversation ends:

App.tsx


<VoiceAgent
  apiKey="rg_live_your_api_key"
  agentName="my-agent"
  onSessionEnd={(data) => {
    console.log('Session ended:', {
      sessionId: data.sessionId,
      duration: `${data.durationSeconds}s`,
      creditsUsed: data.creditsUsed,
      messageCount: data.transcript.length,
      avgLatency: `${data.latencySummary.avg_ms}ms`
    })
  }}
/>

The onSessionEnd callback receives:

Property	Type	Description
`sessionId`	`string`	Unique session identifier
`durationSeconds`	`number`	Total conversation length
`creditsUsed`	`number`	Credits consumed
`transcript`	`TranscriptEntry[]`	Full conversation history
`latencySummary`	`object`	`{ min_ms, max_ms, avg_ms }`

Customizing the Button Text


<VoiceAgent
  apiKey="rg_live_your_api_key"
  agentName="my-agent"
  connectLabel="Start Conversation"
  connectingLabel="Connecting..."
  disconnectLabel="End Conversation"
/>

Customizing the Visualizer


<VoiceAgent
  apiKey="rg_live_your_api_key"
  agentName="my-agent"
  visualizer={{
    barCount: 20,
    barColor: '#3b82f6',
    barGap: 4,
    barWidth: 6,
    barMaxHeight: 80
  }}
/>

Full Example with All Callbacks

VoiceChat.tsx


import { useState } from 'react'
import { VoiceAgent, TranscriptEntry, SessionEndData, VoiceAgentError } from '@vocobase/voice-client-sdk'
import '@vocobase/voice-client-sdk/styles.css'
 
export default function VoiceChat() {
  const [isActive, setIsActive] = useState(false)
  const [transcript, setTranscript] = useState<TranscriptEntry[]>([])
  const [error, setError] = useState<string | null>(null)
 
  return (
    <div className="voice-chat">
      {error && (
        <div className="error-banner">
          {error}
          <button onClick={() => setError(null)}>Dismiss</button>
        </div>
      )}
 
      <VoiceAgent
        apiKey={process.env.NEXT_PUBLIC_VOCOBASE_API_KEY!}
        agentName="my-agent"
        onConnect={() => {
          setIsActive(true)
          setError(null)
          setTranscript([])
        }}
        onDisconnect={() => {
          setIsActive(false)
        }}
        onTranscript={(entry) => {
          setTranscript(prev => [...prev, entry])
        }}
        onError={(err: VoiceAgentError) => {
          setError(err.message)
          setIsActive(false)
        }}
        onSessionEnd={(data: SessionEndData) => {
          console.log(`Session ${data.sessionId} ended`)
          console.log(`Duration: ${data.durationSeconds}s`)
          console.log(`Credits used: ${data.creditsUsed}`)
        }}
        onReconnecting={(attempt, maxAttempts) => {
          console.log(`Reconnecting... attempt ${attempt}/${maxAttempts}`)
        }}
        onReconnected={() => {
          console.log('Reconnected successfully!')
        }}
      />
 
      <div className="transcript">
        <h3>Conversation {isActive && '(Live)'}</h3>
        {transcript.length === 0 ? (
          <p className="empty">No messages yet. Click Connect to start.</p>
        ) : (
          transcript.map((entry, index) => (
            <div key={index} className={`message ${entry.role}`}>
              <span className="role">{entry.role === 'user' ? 'You' : 'Agent'}</span>
              <p className="content">{entry.content}</p>
              {entry.latency_ms && (
                <span className="latency">{entry.latency_ms}ms</span>
              )}
            </div>
          ))
        )}
      </div>
    </div>
  )
}

Next Steps

Now that you have a working voice agent, explore:

Components — All available props and options
Hooks — Build completely custom UIs
Error Handling — Handle edge cases gracefully
Examples — See more integration patterns