@krosai/voice-sdk

Connect any WebRTC voice agent to phone numbers in minutes. Turn your AI voice agent into a phone agent with just 10 lines of code.

Installation

npm install @krosai/voice-sdk

Quick Start

import { KrosAI } from '@krosai/voice-sdk';

// Initialize with your API key from https://app.krosai.com/developers
const krosai = new KrosAI({ apiKey: 'kros_live_...' });

// Connect your agent's audio to a phone number
const call = await krosai.call({
  phoneNumber: '+14155551234',
  audio: myAgentMediaStream, // Your agent's audio output
});

// Handle events
call.on('connected', () => {
  console.log('Call connected!');
});

call.on('remoteAudio', (stream) => {
  // Feed phone audio to your agent
  myAgent.setInputAudio(stream);
});

call.on('ended', (reason) => {
  console.log('Call ended:', reason);
});

// Control the call
call.mute();    // Mute your agent
call.unmute();  // Unmute your agent
call.hangup();  // End the call

Features

• 10 lines to integrate - No SIP, no WebRTC complexity
• Any WebRTC agent - Works with ElevenLabs, custom agents, any MediaStream
• Full audio control - Mute, unmute, audio levels, remote stream access
• Event-driven - Status changes, transcripts, errors
• TypeScript-first - Full type definitions included

Integrations

ElevenLabs

import { KrosAI } from '@krosai/voice-sdk';
import { useConversation } from '@elevenlabs/react';

function PhoneAgent() {
  const krosai = new KrosAI({ apiKey: 'kros_live_...' });
  const conversation = useConversation({ agentId: 'your-agent-id' });

  async function connectToPhone(phoneNumber: string) {
    // Start ElevenLabs conversation
    await conversation.startSession();

    // Connect to phone
    const call = await krosai.call({
      phoneNumber,
      audio: conversation.getAudioStream(),
    });

    // Feed phone audio back to ElevenLabs
    conversation.setInputAudio(call.getRemoteStream());

    call.on('ended', () => conversation.endSession());
  }

  return (
    <button onClick={() => connectToPhone('+14155551234')}>
      Connect Agent to Phone
    </button>
  );
}

Custom MediaStream

import { KrosAI } from '@krosai/voice-sdk';

const krosai = new KrosAI({ apiKey: 'kros_live_...' });

// Get audio from any source
const audioContext = new AudioContext();
const destination = audioContext.createMediaStreamDestination();
const agentStream = destination.stream;

// Connect to phone
const call = await krosai.call({
  phoneNumber: '+14155551234',
  audio: agentStream,
});

// Get phone audio for your agent
const phoneAudio = call.getRemoteStream();

API Reference

KrosAI

Main SDK client.

const krosai = new KrosAI({
  apiKey: string,      // Required: Your KrosAI API key
  baseUrl?: string,    // Optional: API base URL
  debug?: boolean,     // Optional: Enable debug logging
});

krosai.call(options)

Initiate an outbound call.

const call = await krosai.call({
  phoneNumber: string,            // E.164 format (+14155551234)
  audio: MediaStream | AudioSource, // Your agent's audio
  metadata?: Record<string, string>, // Optional: Custom metadata
});

CallSession

Returned by call(). Provides call control and events.

Properties:

• id: string - Unique call ID
• phoneNumber: string - Phone number being called
• status: CallStatus - Current call status
• duration: number - Call duration in seconds
• inputLevel: number - Your agent's audio level (0-1)
• outputLevel: number - Phone audio level (0-1)
• isMuted: boolean - Whether your agent is muted

Methods:

• mute() - Mute your agent's audio
• unmute() - Unmute your agent's audio
• hangup() - End the call
• getRemoteStream() - Get phone audio MediaStream

Events:

• statusChange(status) - Call status changed
• audioLevel(input, output) - Audio levels updated
• remoteAudio(stream) - Phone audio stream available
• transcript(text, isFinal) - Transcript received
• error(error) - Error occurred
• ended(reason) - Call ended

Call Status Flow

initializing → connecting → ringing → connected → ended
                    ↓           ↓          ↓
                 failed      failed     failed

Error Handling

import { KrosAIError } from '@krosai/voice-sdk';

try {
  const call = await krosai.call({ ... });
} catch (error) {
  if (error instanceof KrosAIError) {
    switch (error.code) {
      case 'INVALID_API_KEY':
        // Handle invalid API key
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Handle rate limit
        break;
      case 'INSUFFICIENT_BALANCE':
        // Handle low balance
        break;
      // ... other error codes
    }
  }
}

Getting an API Key

1. Go to app.krosai.com/developers
2. Click "Create API Key"
3. Select the "Voice SDK" scope
4. Copy your API key (starts with kros_live_ or kros_test_)

Requirements

• Browser with WebRTC support
• A KrosAI account with phone numbers
• API key with voice:connect scope

Support

• Documentation: krosai.com/docs/sdk
• Dashboard: app.krosai.com
• Email: [email protected]

License

MIT