Omnia Voice SDK - Build voice AI experiences with ease
npm install @omnia-voice/sdkBuild voice AI experiences with ease. The Omnia Voice SDK provides a simple way to integrate voice AI agents into your web and mobile applications.
- 🎙️ Real-time voice conversations with AI agents
- 🔊 High-quality audio via WebRTC
- 📝 Live transcription of conversations
- ⚛️ React hooks for easy integration
- 📱 Works on web and mobile
- 🔒 Secure - API key authentication
``bash`
npm install @omnia/voice-sdkor
yarn add @omnia/voice-sdkor
pnpm add @omnia/voice-sdk
`typescript
import { OmniaVoice } from '@omnia/voice-sdk';
// Create client
const voice = new OmniaVoice({
apiKey: 'your-api-key',
});
// Listen for events
voice.on('transcriptUpdated', (entry) => {
console.log(${entry.role}: ${entry.text});
});
voice.on('agentStateChanged', (state) => {
console.log(Agent is now: ${state});
});
// Connect to an agent
await voice.connect({ agentId: 'agent-123' });
// ... conversation happens automatically ...
// Disconnect when done
await voice.disconnect();
`
`tsx
import {
OmniaVoiceProvider,
useOmniaVoice,
} from '@omnia/voice-sdk/react';
// Wrap your app with the provider
function App() {
return (
);
}
// Use the hook in your components
function VoiceChat() {
const {
connect,
disconnect,
isConnected,
agentState,
transcript,
} = useOmniaVoice();
return (
Agent: {agentState}
onClick={() =>
isConnected ? disconnect() : connect({ agentId: 'agent-123' })
}
>
{isConnected ? 'End Call' : 'Start Call'}
{entry.role}: {entry.text}
API Reference
$3
The main client class.
`typescript
const voice = new OmniaVoice(config);
`#### Config Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
|
apiKey | string | Yes | Your Omnia API key |
| baseUrl | string | No | API base URL (default: https://api.play-omnia.com) |
| debug | boolean | No | Enable debug logging |#### Methods
| Method | Description |
|--------|-------------|
|
connect(options) | Connect to a voice agent |
| disconnect() | Disconnect from the call |
| setMicrophoneEnabled(enabled) | Enable/disable microphone |
| sendMessage(text) | Send a text message to the agent |
| on(event, callback) | Add event listener |
| off(event, callback) | Remove event listener |#### Properties
| Property | Type | Description |
|----------|------|-------------|
|
connectionState | ConnectionState | Current connection state |
| agentState | AgentState | Current agent state |
| isMicrophoneEnabled | boolean | Whether microphone is enabled |
| transcript | TranscriptEntry[] | Conversation transcript |
| duration | number | Call duration in ms |#### Events
| Event | Payload | Description |
|-------|---------|-------------|
|
connectionStateChanged | ConnectionState | Connection state changed |
| agentStateChanged | AgentState | Agent state changed |
| transcriptUpdated | TranscriptEntry | New transcript entry |
| callStarted | ConnectionDetails | Call started |
| callEnded | number | Call ended (duration in ms) |
| error | Error | Error occurred |$3
`typescript
interface ConnectOptions {
// Use a pre-configured agent from your dashboard
agentId?: string; // Or provide raw configuration
config?: {
systemPrompt?: string;
greeting?: string;
voice?: string;
language?: string;
temperature?: number;
recordingEnabled?: boolean;
};
// Override specific agent settings
overrides?: {
greeting?: string;
// ... any config field
};
// Custom metadata
metadata?: Record;
}
`$3
#### useOmniaVoice
Main hook for voice functionality.
`typescript
const {
// State
connectionState,
agentState,
isMicrophoneEnabled,
transcript,
duration,
isConnected,
isConnecting, // Actions
connect,
disconnect,
setMicrophoneEnabled,
sendMessage,
} = useOmniaVoice();
`#### useVoiceCall
Simplified hook for call management.
`typescript
const {
startCall,
endCall,
toggleCall,
isLoading,
error,
isConnected,
} = useVoiceCall({ agentId: 'agent-123' });
`#### useMicrophone
Hook for microphone control.
`typescript
const {
isMuted,
isEnabled,
toggle,
mute,
unmute,
} = useMicrophone();
`#### useTranscript
Get the conversation transcript.
`typescript
const transcript = useTranscript();
`#### useFormattedDuration
Get the call duration as mm:ss.
`typescript
const duration = useFormattedDuration(); // "02:30"
`Types
$3
`typescript
type ConnectionState =
| 'disconnected'
| 'connecting'
| 'connected'
| 'reconnecting'
| 'failed'
`$3
`typescript
type AgentState =
| 'idle'
| 'listening'
| 'thinking'
| 'speaking'
`$3
`typescript
interface TranscriptEntry {
id: string;
role: 'user' | 'agent';
text: string;
isFinal: boolean;
timestamp: number;
}
`Examples
$3
`tsx
import { OmniaVoiceProvider, useOmniaVoice } from '@omnia/voice-sdk/react';function VoiceChat() {
const { connect, disconnect, isConnected, transcript, agentState } = useOmniaVoice();
return (
Agent: {agentState}
{transcript.map((entry) => (
message ${entry.role}}>
{entry.text}
))}
onClick={() => isConnected ? disconnect() : connect({ agentId: 'my-agent' })}
className={isConnected ? 'end-call' : 'start-call'}
>
{isConnected ? '🔴 End Call' : '🟢 Start Call'}
);
}
`$3
`tsx
function VoiceChatWithMic() {
const { connect, disconnect, isConnected } = useOmniaVoice();
const { isMuted, toggle } = useMicrophone(); return (
{isConnected && (
)}
);
}
`$3
`tsx
function DynamicAgent() {
const { connect } = useOmniaVoice(); const startCustomAgent = () => {
connect({
config: {
systemPrompt: 'You are a friendly sales assistant for our shoe store.',
greeting: 'Welcome to ShoeWorld! What kind of shoes are you looking for today?',
voice: 'Sarah',
language: 'en',
},
});
};
return ;
}
``MIT