Getting Started

This guide will walk you through setting up Vocobase from scratch — creating your account, configuring your first agent, and installing the SDK.

Prerequisites

Before you begin, make sure you have:

Node.js 18+ installed
React 18+ project (Next.js, Vite, Create React App, etc.)
npm, pnpm, or yarn package manager

Step 1: Create a Vocobase Account

Visit dashboard.vocobase.com and sign up
Verify your email address
You’ll receive 100 free credits to get started

Step 2: Create Your First Agent

Navigate to Agents in the dashboard sidebar
Click Create Agent
Configure your agent:

Field	Description	Example
Name	Unique identifier (lowercase, hyphens allowed)	`customer-support`
System Prompt	Instructions that define your agent’s personality	”You are a helpful customer support agent…”
Voice	Select from available voice options	`sophia`
Language	Primary language for the agent	`English`
Greeting	Optional first message when connecting	”Hello! How can I help you today?”

Click Save to create your agent

Step 3: Generate an API Key

Navigate to API Keys in the dashboard sidebar
Click Create API Key
Give it a descriptive name (e.g., “Development Key”)
Copy the key immediately — it won’t be shown again


rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Important: Store your API key securely. Never commit it to version control or expose it in client-side code in production.

Step 4: Install the SDK

Install the Vocobase Voice Client SDK in your React project:


npm install @vocobase/voice-client-sdk

Step 5: Add the Styles

Import the SDK styles in your app’s entry point:

app.tsx


import '@vocobase/voice-client-sdk/styles.css'

Or in your global CSS:

globals.css


@import '@vocobase/voice-client-sdk/styles.css';

Step 6: Add the Voice Agent

Add the VoiceAgent component to your app:

App.tsx


import { VoiceAgent } from '@vocobase/voice-client-sdk'
import '@vocobase/voice-client-sdk/styles.css'
 
export default function App() {
  return (
    <div className="app">
      <h1>My Voice App</h1>
      <VoiceAgent
        apiKey="rg_live_your_api_key"
        agentName="customer-support"
        onError={(error) => {
          console.error('Voice error:', error)
        }}
      />
    </div>
  )
}

Step 7: Test It Out

Run your development server
Click the Connect button
Allow microphone access when prompted
Start talking to your AI agent!

Environment Variables

For production apps, store your API key in environment variables:

.env.local


NEXT_PUBLIC_VOCOBASE_API_KEY=rg_live_your_api_key

Then reference it in your code:


<VoiceAgent
  apiKey={process.env.NEXT_PUBLIC_VOCOBASE_API_KEY!}
  agentName="customer-support"
/>

What’s Next?

Quick Start — See a complete working example
Dashboard Guide — Learn more about configuring agents
Components — Explore all VoiceAgent options
Hooks — Build custom interfaces

Troubleshooting

”Microphone permission denied”

Make sure your site is served over HTTPS (or localhost). Browsers require secure contexts for microphone access.

”Invalid API key”

Double-check that:

The key starts with rg_live_
You copied the full key without extra spaces
The key hasn’t been deleted from the dashboard

”Agent not found”

Verify that:

The agent name matches exactly (case-sensitive)
The agent is active in the dashboard
The API key belongs to the same account as the agent