@deftvoice/sdk

Production-ready SDK for integrating ElevenLabs voice agents into any website or application.

Features

• 🎤 Automatic Audio Handling - Microphone capture, processing, and playback
• 🔄 Auto-Reconnection - Handles disconnects automatically with exponential backoff
• 🎯 ElevenLabs Native - Leverages built-in interruption detection
• 📦 Zero Dependencies - Lightweight, no external dependencies
• 🔒 TypeScript Support - Full type definitions included
• 🌐 Universal - Works in browsers and Node.js

Installation

npm / yarn / pnpm

npm install @deftvoice/sdk
# or
yarn add @deftvoice/sdk
# or
pnpm add @deftvoice/sdk

CDN (for HTML/WordPress/Webflow)

<script src="https://cdn.jsdelivr.net/npm/@deftvoice/sdk@latest/dist/index.cdn.js"></script>

Quick Start

TypeScript / JavaScript (ES Modules)

import { DeftvoiceAgent } from '@deftvoice/sdk';

const agent = new DeftvoiceAgent({
  serverUrl: 'wss://api.deftvoice.com',
  agentId: 'your-elevenlabs-agent-id',
  apiKey: 'your-deftvoice-api-key'
});

agent.onInterruption = () => {
  console.log('User interrupted agent');
};

agent.onError = (error) => {
  console.error('Error:', error);
};

await agent.start();

CommonJS

const { DeftvoiceAgent } = require('@deftvoice/sdk');

const agent = new DeftvoiceAgent({
  serverUrl: 'wss://api.deftvoice.com',
  agentId: 'your-elevenlabs-agent-id',
  apiKey: 'your-deftvoice-api-key'
});

agent.start();

CDN / Plain HTML

<script src="https://cdn.jsdelivr.net/npm/@deftvoice/sdk@latest/dist/index.cdn.js"></script>
<script>
  const agent = new DeftvoiceAgent({
    serverUrl: 'wss://api.deftvoice.com',
    agentId: 'your-elevenlabs-agent-id',
    apiKey: 'your-deftvoice-api-key'
  });

  agent.onInterruption = () => {
    console.log('User interrupted');
  };

  agent.start();
</script>

API Reference

Constructor

new DeftvoiceAgent(config: DeftvoiceConfig)

Config Options:

• serverUrl (string, required): WebSocket server URL
• agentId (string, required): ElevenLabs Agent ID
• apiKey (string, required): Deftvoice API Key
• autoReconnect (boolean, default: true): Enable auto-reconnection
• maxReconnectAttempts (number, default: 5): Max reconnection attempts
• reconnectDelay (number, default: 1000): Initial reconnection delay (ms)

Methods

start(): Promise<void>

Start the voice agent connection. Requests microphone access and connects to the server.

stop(): Promise<void>

Stop the voice agent and cleanup all resources.

Properties

status: ConnectionStatus

Current connection status: 'disconnected' | 'connecting' | 'connected' | 'error'

isConnected: boolean

Boolean indicating if currently connected.

Event Handlers

onAudio?: (audioData: AudioData) => void

Called when audio is received from the agent. Audio is automatically played, but you can access the data.

onInterruption?: () => void

Called when ElevenLabs detects user interruption. Audio playback is automatically stopped.

onError?: (error: Error) => void

Called when an error occurs.

onConnect?: () => void

Called when successfully connected.

onDisconnect?: () => void

Called when disconnected.

onStatusChange?: (status: ConnectionStatus) => void

Called when connection status changes.

Examples

React Example

import { useEffect, useState } from 'react';
import { DeftvoiceAgent } from '@deftvoice/sdk';

function VoiceAgent() {
  const [agent, setAgent] = useState<DeftvoiceAgent | null>(null);
  const [status, setStatus] = useState('disconnected');

  useEffect(() => {
    const agent = new DeftvoiceAgent({
      serverUrl: 'wss://api.deftvoice.com',
      agentId: 'your-agent-id',
      apiKey: 'your-api-key'
    });

    agent.onStatusChange = setStatus;
    agent.onInterruption = () => alert('User interrupted');
    agent.onError = (error) => console.error(error);

    setAgent(agent);

    return () => {
      agent.stop();
    };
  }, []);

  const handleStart = async () => {
    await agent?.start();
  };

  const handleStop = async () => {
    await agent?.stop();
  };

  return (
    <div>
      <p>Status: {status}</p>
      <button onClick={handleStart}>Start</button>
      <button onClick={handleStop}>Stop</button>
    </div>
  );
}

Next.js Example

'use client';

import { useEffect, useRef } from 'react';
import { DeftvoiceAgent } from '@deftvoice/sdk';

export default function VoiceAgentPage() {
  const agentRef = useRef<DeftvoiceAgent | null>(null);

  useEffect(() => {
    agentRef.current = new DeftvoiceAgent({
      serverUrl: process.env.NEXT_PUBLIC_DEFTVOICE_URL!,
      agentId: process.env.NEXT_PUBLIC_AGENT_ID!,
      apiKey: process.env.NEXT_PUBLIC_DEFTVOICE_API_KEY!
    });

    agentRef.current.onInterruption = () => {
      console.log('User interrupted agent');
    };

    return () => {
      agentRef.current?.stop();
    };
  }, []);

  return (
    <div>
      <button onClick={() => agentRef.current?.start()}>Start Conversation</button>
      <button onClick={() => agentRef.current?.stop()}>Stop Conversation</button>
    </div>
  );
}

Vue.js Example

<template>
  <div>
    <p>Status: {{ status }}</p>
    <button @click="start">Start</button>
    <button @click="stop">Stop</button>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { DeftvoiceAgent } from '@deftvoice/sdk';

const status = ref('disconnected');
let agent = null;

onMounted(() => {
  agent = new DeftvoiceAgent({
    serverUrl: 'wss://api.deftvoice.com',
    agentId: 'your-agent-id',
    apiKey: 'your-api-key'
  });

  agent.onStatusChange = (newStatus) => {
    status.value = newStatus;
  };
});

onUnmounted(() => {
  agent?.stop();
});

const start = async () => {
  await agent?.start();
};

const stop = async () => {
  await agent?.stop();
};
</script>

Browser Support

• Chrome/Edge: ✅ Full support
• Firefox: ✅ Full support
• Safari: ✅ Full support (iOS 11+)
• Opera: ✅ Full support

Note: Requires HTTPS (or localhost) for microphone access.

License

MIT

Support

For issues and questions:

• GitHub Issues: https://github.com/yourusername/deftvoice-sdk/issues
• Documentation: See INTEGRATION_GUIDE.md for complete integration guide