@serviceagent/aiva-sdk

@serviceagent/aiva-sdk

AIVA Voice Agent SDK - Real-time voice AI for web and React applications.

Installation

npm install @serviceagent/aiva-sdk
# or
yarn add @serviceagent/aiva-sdk
# or
pnpm add @serviceagent/aiva-sdk

Quick Start

Vanilla JavaScript/TypeScript

import { AivaClient, AudioCapture, AudioPlayer } from '@serviceagent/aiva-sdk';

// Create client
const client = new AivaClient({
  endpoint: 'wss://api.example.com/v1/voice/stream',
  token: 'your-auth-token',
  orgId: 'your-org-id',
  voiceAgentId: 'optional-agent-id',
});

// Set up audio capture and playback (PCM16 frames)
const capture = new AudioCapture({
  echoCancellation: true,
  noiseSuppression: true,
});
const player = new AudioPlayer();

// Event handlers
client.on('connectionStateChange', (state) => {
  console.log('Connection:', state);
});

client.on('transcript', (segment) => {
  console.log(`${segment.role}: ${segment.text}`);
});

client.on('turnStateChange', (state) => {
  console.log('Turn state:', state); // 'listening' | 'thinking' | 'speaking'
});

client.on('callEnd', (metrics) => {
  console.log('Call ended:', metrics);
});

// Wire audio
capture.on('data', (buffer) => client.sendAudio(buffer));
client.on('audioData', (buffer) => player.play(buffer));

// Connect and start
await client.connect();
await player.init(); // Must be called after user interaction
await capture.start();
client.startCall();

// End call when done
client.endCall();
capture.stop();

React

import { AivaProvider, useAiva, AivaCallButton, AivaTranscriptView } from '@serviceagent/aiva-sdk/react';

// Wrap your app with the provider
function App() {
  return (
    <AivaProvider
      config={{
        endpoint: 'wss://api.example.com/v1/voice/stream',
        token: 'your-auth-token',
        orgId: 'your-org-id',
      }}
      autoConnect
      onCallEnd={(metrics) => console.log('Call ended:', metrics)}
    >
      <CallInterface />
    </AivaProvider>
  );
}

// Use the hook in your components
function CallInterface() {
  const { 
    isConnected,
    isCallActive, 
    turnState,
    transcript,
    startCall,
    endCall,
  } = useAiva();

  return (
    <div>
      <div>Status: {isConnected ? 'Connected' : 'Disconnected'}</div>
      <div>Turn: {turnState}</div>
      
      {/* Pre-built button component */}
      <AivaCallButton 
        className="call-button"
        activeClassName="active"
        idleClassName="idle"
      />
      
      {/* Pre-built transcript view */}
      <AivaTranscriptView
        className="transcript"
        userClassName="user-message"
        assistantClassName="agent-message"
      />
    </div>
  );
}

API Reference

AivaClient

The core WebSocket client for voice streaming.

Constructor Options

interface AivaClientConfig {
  endpoint: string;        // WebSocket URL
  token: string;           // Auth token
  orgId: string;           // Organization ID
  voiceAgentId?: string;   // Voice agent ID
  inputFormat?: 'pcm16_16000' | 'opus';
  outputFormat?: 'pcm16_16000' | 'ulaw_8000';
  debug?: boolean;         // Enable debug logging
  autoReconnect?: boolean; // Auto-reconnect on disconnect
  reconnectDelayMs?: number;
  maxReconnectAttempts?: number;
}

Methods

• connect(sessionConfig?) - Connect to server
• disconnect() - Disconnect from server
• startCall() - Start a voice call
• endCall() - End the current call
• sendAudio(data: ArrayBuffer) - Send audio data
• on(event, callback) - Add event listener
• off(event, callback) - Remove event listener
• getConnectionState() - Get current connection state
• getCallState() - Get current call state
• getTurnState() - Get current turn state
• getTranscript() - Get transcript segments

Events

• connectionStateChange - Connection state changed
• callStateChange - Call state changed
• turnStateChange - Turn state changed (listening/thinking/speaking)
• transcript - Received transcript segment
• audioData - Audio data for playback
• callEnd - Call ended with metrics
• error - Error occurred

AudioCapture

Microphone audio capture using Web Audio API. Uses AudioWorklet when available and falls back to ScriptProcessorNode for older browsers.

const capture = new AudioCapture({
  sampleRate: 16000,
  channels: 1,
  frameDurationMs: 20,
  bufferSize: 4096, // ScriptProcessor fallback only
  echoCancellation: true,
  noiseSuppression: true,
  autoGainControl: true,
});

capture.on('data', (buffer: ArrayBuffer) => {
  // PCM16 audio data (Int16 little-endian)
});

await capture.start();
capture.stop();

PCM16 Encoder + Sender (WebSocket/WebRTC)

Use this for spec-compliant { type: "audio" } messages.

import { Pcm16Encoder, AivaAudioSender } from '@serviceagent/aiva-sdk';

const sender = AivaAudioSender.fromWebSocket(ws);
// const sender = AivaAudioSender.fromDataChannel(dc);

const encoder = new Pcm16Encoder({ sampleRate: 16000, frameDurationMs: 20 });
encoder.on('data', (pcmFrame) => sender.sendPcm16(pcmFrame));

await encoder.start();

AivaAudioSender

const sender = AivaAudioSender.fromWebSocket(ws);
sender.sendPcm16(pcmFrame);

AudioPlayer

Audio playback using Web Audio API.

const player = new AudioPlayer(16000); // sample rate

await player.init(); // Call on user interaction
await player.play(audioBuffer);
player.stop();
player.close();

React Components

AivaProvider

Context provider for AIVA functionality.

<AivaProvider
  config={clientConfig}
  autoConnect={true}
  sessionConfig={{ contactId: '...' }}
  onCallEnd={(metrics) => {}}
  onError={(error) => {}}
  onTranscript={(segment) => {}}
>
  {children}
</AivaProvider>

useAiva Hook

const {
  // Connection
  connectionState,
  isConnected,
  connect,
  disconnect,

  // Call state
  callState,
  turnState,
  isCallActive,
  isSpeaking,
  isListening,
  isThinking,

  // Actions
  startCall,
  endCall,
  toggleCall,

  // Data
  transcript,
  lastMetrics,
  lastError,
} = useAiva();

AivaCallButton

Pre-styled call button.

<AivaCallButton
  className="base-class"
  activeClassName="when-active"
  idleClassName="when-idle"
/>

AivaTurnIndicator

Shows current turn state.

<AivaTurnIndicator
  showLabel={true}
  listeningClassName="listening"
  thinkingClassName="thinking"
  speakingClassName="speaking"
/>

AivaTranscriptView

Displays conversation transcript.

<AivaTranscriptView
  userClassName="user"
  assistantClassName="agent"
  renderSegment={(segment, index) => (
    <CustomSegment key={index} {...segment} />
  )}
/>

Browser Support

• Chrome 66+
• Firefox 76+
• Safari 14.1+
• Edge 79+

Requires:

• Web Audio API
• WebSocket API
• getUserMedia API (for microphone access)
• AudioWorklet (preferred) or ScriptProcessorNode fallback

License

MIT