Skip to main content
The VoiceSDK provides advanced voice conversation capabilities with automatic chat system integration, and React hooks for building voice-enabled applications. Create natural voice interactions with AI agents, complete with audio visualization, transcription, and conversation management. In this article you find a Quick Start example that will not only get you up and running quicky, but help you understand how it works. The rest of the article details the various methods you can use, what they are used for, and best practices.

Installation

Quick Start

Basic Voice Conversation

In this example, you will learn how to implement real-time voice conversations using the VoiceSDK in both TypeScript and React applications. You start by initializing the VoiceSDK with your API credentials including a specific agentId that defines which AI voice agent will handle the conversation, then use startVoiceConversation() to begin a voice session with callback handlers that let you respond to connection events, receive AI messages, handle disconnections, and process live transcriptions of what the user is saying (with isFinal indicating when a complete phrase has been recognized). The saveToChat option allows you to persist the voice conversation as text in your chat history for later reference. For React applications, you’ll use the useVoiceConversation hook, which provides a cleaner interface with state management built-in: it gives you a status variable to track the connection state, startSession() and endSession() methods to control the conversation, setVolume() to adjust audio levels, getInputByteFrequencyData() for visualizing audio input (perfect for creating waveform displays), and conversationState that contains real-time information like current volume levels. This gives you everything you need to build voice-enabled AI applications with real-time speech recognition and synthesis, perfect for creating voice assistants, hands-free interfaces, or conversational AI experiences—with the React hook handling all the complex state management and WebSocket connections for you.

React Hook Usage

Configuration

VoiceSDKConfig Interface

VoiceSettings

Example Configuration:

Core Features

Voice Conversation Sessions

The VoiceSDK manages voice conversation sessions with automatic chat integration:

Voice Messages

Session Management

startVoiceConversation(options?)

Start a new voice conversation session.
StartVoiceConversationOptions:
Example:

endVoiceSession(sessionId, reason?)

End a voice conversation session.
Example:

getVoiceState(sessionId)

Get current voice conversation state.
Example:

React Integration

useVoiceConversation Hook

The useVoiceConversation hook provides React integration with state management:
Complete React Example:

Voice Controls

Volume Control

Microphone Control

Voice Settings Updates

Audio Visualization

Real-time Audio Data

Audio Visualization Component

Chat Integration

Automatic Chat Saving

Voice conversations can be automatically saved to your chat system:

Manual Chat Integration

Contextual Updates

Send additional context to the voice conversation:

Error Handling

Examples

Voice-Enabled Customer Support

Best Practices

Error Handling and Fallbacks

Resource Management

Performance Optimization

Accessibility