React Hooks Reference

Primary Hook

`useVoice`

The main hook for voice interactions, providing comprehensive access to all voice functionality.

import { useVoice } from '@nextevi/voice-react';

const voice = useVoice();

Returns

connect

function

Establishes voice connection

await connect({
  auth: {
    apiKey: "oak_your_api_key",
    projectId: "your-project-id", 
    configId: "your-config-id"
  },
  audioConfig?: {
    sampleRate: 24000,
    channels: 1,
    encoding: 'linear16'
  }
})

disconnect

function

Closes voice connection and cleans up resources

disconnect()

readyState

string

Current connection state: 'disconnected', 'connecting', 'connected', or 'error'

messages

VoiceMessage[]

Array of conversation messages (user and assistant)

isRecording

boolean

Whether microphone is actively capturing audio

isTTSPlaying

boolean

Whether text-to-speech audio is currently playing

isWaitingForResponse

boolean

Whether waiting for AI assistant response

connectionMetadata

ConnectionMetadata

Connection information including session ID, timestamps

error

NextEVIError | null

Current error state, if any

clearMessages

function

Clears all conversation messages

clearMessages()

sendMessage

function

Send text message to assistant (for testing/debugging)

sendMessage("Hello, how are you?")

Specialized Hooks

`useVoiceStatus`

Get detailed connection status information:

import { useVoiceStatus } from '@nextevi/voice-react';

const {
  readyState,
  error,
  connectionMetadata,
  isConnected,
  isConnecting, 
  isDisconnected,
  hasError
} = useVoiceStatus();

readyState

string

Current connection state

error

NextEVIError | null

Current error, if any

connectionMetadata

ConnectionMetadata

Connection details and session information

isConnected

boolean

Computed boolean: readyState === 'connected'

isConnecting

boolean

Computed boolean: readyState === 'connecting'

isDisconnected

boolean

Computed boolean: readyState === 'disconnected'

hasError

boolean

Computed boolean: error !== null

`useVoiceMessages`

Manage conversation messages with enhanced utilities:

import { useVoiceMessages } from '@nextevi/voice-react';

const {
  messages,
  userMessages,
  assistantMessages,
  systemMessages,
  errorMessages,
  lastMessage,
  hasStreamingMessages,
  isWaitingForResponse,
  clearMessages,
  sendMessage,
  messageCount,
  conversationLength
} = useVoiceMessages();

messages

VoiceMessage[]

All conversation messages

userMessages

VoiceMessage[]

Filtered array of user messages only

assistantMessages

VoiceMessage[]

Filtered array of assistant messages only

systemMessages

VoiceMessage[]

Filtered array of system messages

errorMessages

VoiceMessage[]

Filtered array of error messages

lastMessage

VoiceMessage | null

Most recent message in conversation

hasStreamingMessages

boolean

Whether any messages are currently streaming

messageCount

number

Total number of messages

conversationLength

number

Total character count of all messages

`useVoiceAudio`

Monitor audio activity and states:

import { useVoiceAudio } from '@nextevi/voice-react';

const {
  isRecording,
  isTTSPlaying,
  hasAudioActivity
} = useVoiceAudio();

isRecording

boolean

Whether microphone is capturing audio

isTTSPlaying

boolean

Whether TTS audio is playing

hasAudioActivity

boolean

Whether any audio activity is happening (recording or playing)

`useSimpleVoice`

Simplified connection API for basic use cases:

import { useSimpleVoice } from '@nextevi/voice-react';

const voice = useSimpleVoice({ debug: true });

// Connect with individual parameters
await voice.connect(
  "oak_your_api_key",
  "project_id", 
  "config_id"
);

connect

function

Simplified connect method taking individual parameters

await connect(apiKey: string, projectId: string, configId: string, options?: object)

disconnect

function

Disconnect from voice session

readyState

string

Connection state

messages

VoiceMessage[]

Conversation messages

Advanced Hooks

`useVoiceIdleTimeout`

Monitor and configure idle timeout behavior:

import { useVoiceIdleTimeout } from '@nextevi/voice-react';

const {
  timeUntilTimeout,
  isIdleWarning,
  resetIdleTimer,
  configureTimeout
} = useVoiceIdleTimeout();

timeUntilTimeout

number

Seconds remaining until idle timeout

isIdleWarning

boolean

Whether idle warning period is active

resetIdleTimer

function

Reset the idle timeout counter

configureTimeout

function

Configure timeout settings

configureTimeout({
  enabled: true,
  timeoutSeconds: 300,    // 5 minutes
  warningSeconds: 30      // 30 second warning
})

`useVoiceTurnDetection`

Access turn detection and conversation flow data:

import { useVoiceTurnDetection } from '@nextevi/voice-react';

const {
  isUserTurn,
  isAssistantTurn,
  turnDuration,
  silenceDuration,
  lastTurnChange
} = useVoiceTurnDetection();

isUserTurn

boolean

Whether it’s currently the user’s turn to speak

isAssistantTurn

boolean

Whether it’s currently the assistant’s turn to speak

turnDuration

number

Duration of current turn in milliseconds

silenceDuration

number

Duration of current silence in milliseconds

lastTurnChange

number

Timestamp of last turn change

`useVoiceDebug`

Development and debugging utilities:

import { useVoiceDebug } from '@nextevi/voice-react';

const {
  debugInfo,
  connectionStats,
  audioStats,
  messageHistory,
  exportLogs
} = useVoiceDebug();

debugInfo

object

Current debug information and internal state

connectionStats

object

WebSocket connection statistics and performance metrics

audioStats

object

Audio processing statistics and quality metrics

messageHistory

object[]

Raw WebSocket message history for debugging

exportLogs

function

Export debug logs for analysis

const logs = exportLogs();
console.log('Debug logs:', logs);

Type Definitions

VoiceMessage

interface VoiceMessage {
  id: string;
  type: 'user' | 'assistant' | 'system' | 'error';
  content: string;
  timestamp: Date;
  metadata?: {
    emotions?: EmotionData;
    transcription?: TranscriptionResult;
    audioChunk?: TTSChunk;
    [key: string]: any;
  };
}

NextEVIConfig

interface NextEVIConfig {
  apiKey?: string;
  accessToken?: string;
  projectId?: string;
  configId: string;
  websocketUrl?: string;
  debug?: boolean;
}

AudioConfig

interface AudioConfig {
  sampleRate?: number;
  channels?: number;
  encoding?: 'linear16' | 'mulaw' | 'alaw';
  echoCancellation?: boolean;
  noiseSuppression?: boolean;
  autoGainControl?: boolean;
}

ConnectionMetadata

interface ConnectionMetadata {
  sessionId: string;
  connectionId: string;
  connectedAt: Date;
  configId: string;
  projectId: string;
  serverInfo?: {
    version: string;
    region: string;
  };
}

Best Practices

Hook Selection

Use useVoice for most applications - it provides everything you need
Use specialized hooks (useVoiceStatus, useVoiceMessages, etc.) when you need specific functionality
Use useSimpleVoice for quick prototypes or simple integrations
Use useVoiceDebug only in development environments

Error Handling

Always handle connection errors in your UI
Monitor the error state from hooks
Implement retry logic for network issues
Validate configuration before connecting

Performance

Use React.memo for message components to prevent unnecessary re-renders
Implement virtual scrolling for long conversation histories
Clean up connections when components unmount
Use useVoiceAudio to show loading states during audio activity

User Experience

Show clear connection status to users
Provide visual feedback for audio activity (recording/playing)
Handle microphone permissions gracefully
Implement idle timeout warnings

Examples

Basic Voice Chat

import React from 'react';
import { useVoice } from '@nextevi/voice-react';

function VoiceChat() {
  const { connect, disconnect, readyState, messages } = useVoice();
  
  const handleConnect = async () => {
    await connect({
      auth: {
        apiKey: process.env.NEXTEVI_API_KEY,
        projectId: process.env.NEXTEVI_PROJECT_ID,
        configId: process.env.NEXTEVI_CONFIG_ID
      }
    });
  };
  
  return (
    <div>
      <button onClick={handleConnect} disabled={readyState === 'connecting'}>
        {readyState === 'connected' ? 'Connected' : 'Connect'}
      </button>
      
      <div>
        {messages.map(message => (
          <div key={message.id}>
            <strong>{message.type}:</strong> {message.content}
          </div>
        ))}
      </div>
    </div>
  );
}

Status Monitor

import React from 'react';
import { useVoiceStatus, useVoiceAudio } from '@nextevi/voice-react';

function VoiceStatusMonitor() {
  const { readyState, error, connectionMetadata } = useVoiceStatus();
  const { isRecording, isTTSPlaying } = useVoiceAudio();
  
  return (
    <div>
      <div>Status: {readyState}</div>
      <div>Recording: {isRecording ? '🎤' : '🔇'}</div>
      <div>Playing: {isTTSPlaying ? '🔊' : '🔇'}</div>
      {error && <div>Error: {error.message}</div>}
      {connectionMetadata && (
        <div>Session: {connectionMetadata.sessionId}</div>
      )}
    </div>
  );
}

Getting Started

Speech-to-Speech

API Reference

Primary Hook

`useVoice`

Returns

Specialized Hooks

`useVoiceStatus`

`useVoiceMessages`

`useVoiceAudio`

`useSimpleVoice`

Advanced Hooks

`useVoiceIdleTimeout`

`useVoiceTurnDetection`

`useVoiceDebug`

Type Definitions

VoiceMessage

NextEVIConfig

AudioConfig

ConnectionMetadata

Best Practices

Examples

Basic Voice Chat

Status Monitor

Getting Started

Speech-to-Speech

API Reference

​Primary Hook

​useVoice

​Returns

​Specialized Hooks

​useVoiceStatus

​useVoiceMessages

​useVoiceAudio

​useSimpleVoice

​Advanced Hooks

​useVoiceIdleTimeout

​useVoiceTurnDetection

​useVoiceDebug

​Type Definitions

​VoiceMessage

​NextEVIConfig

​AudioConfig

​ConnectionMetadata

​Best Practices

​Examples

​Basic Voice Chat

​Status Monitor

Primary Hook

`useVoice`

Returns

Specialized Hooks

`useVoiceStatus`

`useVoiceMessages`

`useVoiceAudio`

`useSimpleVoice`

Advanced Hooks

`useVoiceIdleTimeout`

`useVoiceTurnDetection`

`useVoiceDebug`

Type Definitions

VoiceMessage

NextEVIConfig

AudioConfig

ConnectionMetadata

Best Practices

Examples

Basic Voice Chat

Status Monitor