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

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'
  }
})

function

Closes voice connection and cleans up resources

disconnect()

string

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

VoiceMessage[]

Array of conversation messages (user and assistant)

boolean

Whether microphone is actively capturing audio

boolean

Whether text-to-speech audio is currently playing

boolean

Whether waiting for AI assistant response

ConnectionMetadata

Connection information including session ID, timestamps

NextEVIError | null

Current error state, if any

function

Clears all conversation messages

clearMessages()

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();

string

Current connection state

NextEVIError | null

Current error, if any

ConnectionMetadata

Connection details and session information

boolean

Computed boolean: readyState === 'connected'

boolean

Computed boolean: readyState === 'connecting'

boolean

Computed boolean: readyState === 'disconnected'

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();

VoiceMessage[]

All conversation messages

VoiceMessage[]

Filtered array of user messages only

VoiceMessage[]

Filtered array of assistant messages only

VoiceMessage[]

Filtered array of system messages

VoiceMessage[]

Filtered array of error messages

VoiceMessage | null

Most recent message in conversation

boolean

Whether any messages are currently streaming

number

Total number of messages

number

Total character count of all messages

`useVoiceAudio`

Monitor audio activity and states:

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

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

boolean

Whether microphone is capturing audio

boolean

Whether TTS audio is playing

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"
);

function

Simplified connect method taking individual parameters

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

function

Disconnect from voice session

string

Connection state

VoiceMessage[]

Conversation messages

Advanced Hooks

`useVoiceIdleTimeout`

Monitor and configure idle timeout behavior:

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

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

number

Seconds remaining until idle timeout

boolean

Whether idle warning period is active

function

Reset the idle timeout counter

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();

boolean

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

boolean

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

number

Duration of current turn in milliseconds

number

Duration of current silence in milliseconds

number

Timestamp of last turn change

`useVoiceDebug`

Development and debugging utilities:

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

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

object

Current debug information and internal state

object

WebSocket connection statistics and performance metrics

object

Audio processing statistics and quality metrics

object[]

Raw WebSocket message history for debugging

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

​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