@vagel/ai

Official JavaScript/TypeScript SDK for the Vagel AI platform. Add voice AI to any application with just a few lines of code.

🚀 Quick Start

Installation

npm install @vagel/ai

Basic Usage

import VagelAI from '@vagel/ai';

const vagel = new VagelAI('pk_live_your_key_here');

// Start a voice call
const call = await vagel.calls.start({
  assistantId: 'asst_customer_support',
  phoneNumber: '+1234567890'
});

console.log('Call started:', call.data.id);

🔑 Authentication

Get your API keys from the Vagel AI Dashboard:

• Public Key (pk_live_*): Safe for client-side use (websites, mobile apps)
• Private Key (sk_live_*): Server-side only (keep secret!)

// Client-side (public key)
const vagel = new VagelAI('pk_live_your_public_key');

// Server-side (private key)
const vagel = new VagelAI('sk_live_your_private_key');

📚 API Reference

Assistants

Manage your voice assistants programmatically.

// List all assistants
const assistants = await vagel.assistants.list();

// Create a new assistant
const assistant = await vagel.assistants.create({
  name: 'Customer Support Bot',
  systemPrompt: 'You are a helpful customer support assistant.',
  voice: 'Cartesia Sonic',
  firstMessage: 'Hello! How can I help you today?'
});

// Get specific assistant
const assistant = await vagel.assistants.get('asst_123');

// Update assistant
const updated = await vagel.assistants.update('asst_123', {
  systemPrompt: 'Updated system prompt'
});

// Delete assistant
await vagel.assistants.delete('asst_123');

Calls

Start and manage voice calls.

// Start a voice call
const call = await vagel.calls.start({
  assistantId: 'asst_customer_support',
  phoneNumber: '+1234567890',
  context: {
    customerName: 'John Doe',
    orderId: '12345'
  }
});

// Get call details
const call = await vagel.calls.get('call_123');

// List calls
const calls = await vagel.calls.list({
  status: 'completed',
  limit: 50
});

// Transfer call to human
await vagel.calls.transfer('call_123', '+1800SUPPORT');

// Get call transcript
const transcript = await vagel.calls.getTranscript('call_123');

Analytics

Access usage statistics and insights.

// Get comprehensive analytics
const analytics = await vagel.analytics.get();

// Get summary statistics
const summary = await vagel.analytics.getSummary();
console.log('Total calls:', summary.data.totalCalls);

// Get usage information
const usage = await vagel.analytics.getUsage();
console.log('Credits remaining:', usage.data.credits.remaining);

// Get call volume over time
const volume = await vagel.analytics.getCallVolume({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  granularity: 'day'
});

🎯 Real-World Examples

E-commerce Customer Support

import VagelAI from '@vagel/ai';

const vagel = new VagelAI('pk_live_your_key');

// Add voice support to your checkout page
document.getElementById('voice-help').onclick = async () => {
  const call = await vagel.calls.start({
    assistantId: 'asst_ecommerce_support',
    context: {
      orderId: getCurrentOrderId(),
      customerTier: 'premium'
    }
  });
  
  // Listen for call events
  vagel.on('call.message', ({ message }) => {
    console.log('AI said:', message.content);
  });
  
  vagel.on('call.transfer', ({ transferNumber }) => {
    console.log('Call transferred to:', transferNumber);
  });
};

Healthcare Appointment Booking

const vagel = new VagelAI('sk_live_your_private_key');

// Create appointment booking assistant
const assistant = await vagel.assistants.create({
  name: 'Appointment Scheduler',
  systemPrompt: `You help patients book medical appointments. 
    Ask for their preferred date, time, and reason for visit.
    If urgent, transfer to our medical team.`,
  transferSettings: {
    enabled: true,
    phoneNumber: '+1800MEDICAL',
    phrases: ['urgent', 'emergency', 'pain', 'doctor now']
  }
});

// Start appointment booking call
const bookAppointment = async (patientPhone) => {
  return await vagel.calls.start({
    assistantId: assistant.data.id,
    phoneNumber: patientPhone,
    context: {
      service: 'appointment_booking',
      priority: 'normal'
    }
  });
};

SaaS Customer Onboarding

const vagel = new VagelAI('pk_live_your_key');

// Voice-guided onboarding
const startOnboarding = async (userInfo) => {
  const call = await vagel.calls.start({
    assistantId: 'asst_onboarding_guide',
    context: {
      userName: userInfo.name,
      plan: userInfo.plan,
      experience: userInfo.experience
    }
  });

  // Track onboarding progress
  vagel.on('call.message', ({ call, message }) => {
    if (message.role === 'assistant') {
      trackOnboardingStep(call.id, message.content);
    }
  });
};

🎧 Real-Time Events

Listen to call events in real-time:

const vagel = new VagelAI('pk_live_your_key');

// Listen for call events
vagel.on('call.started', ({ call }) => {
  console.log('Call started:', call.id);
});

vagel.on('call.message', ({ call, message }) => {
  console.log(`${message.role}: ${message.content}`);
});

vagel.on('call.speech.start', ({ call }) => {
  console.log('User started speaking');
});

vagel.on('call.speech.end', ({ call }) => {
  console.log('User stopped speaking');
});

vagel.on('call.transfer', ({ call, transferNumber }) => {
  console.log(`Call transferred to ${transferNumber}`);
});

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

⚙️ Configuration

Basic Configuration

const vagel = new VagelAI('your_api_key', {
  baseUrl: 'https://api.vagel.ai',  // Custom API endpoint
  timeout: 30000,                   // Request timeout (30s)
  retries: 3,                       // Retry failed requests
  debug: true                       // Enable debug logging
});

Update Configuration

vagel.updateConfig({
  timeout: 60000,
  debug: false
});

Test Connection

const test = await vagel.test();
console.log('Connection:', test.success ? 'OK' : 'Failed');
console.log('Key type:', test.keyType);

🔧 Advanced Usage

Error Handling

import { VagelError } from '@vagel/ai';

try {
  const call = await vagel.calls.start({
    assistantId: 'invalid_id'
  });
} catch (error) {
  if (error instanceof VagelError) {
    console.log('Error code:', error.code);
    console.log('Status:', error.statusCode);
    console.log('Details:', error.details);
  }
}

Batch Operations

// Create multiple assistants
const assistants = await Promise.all([
  vagel.assistants.create({ name: 'Support Bot', systemPrompt: '...' }),
  vagel.assistants.create({ name: 'Sales Bot', systemPrompt: '...' }),
  vagel.assistants.create({ name: 'Booking Bot', systemPrompt: '...' })
]);

// Start multiple calls
const calls = await Promise.all(
  phoneNumbers.map(phone => 
    vagel.calls.start({
      assistantId: 'asst_broadcast',
      phoneNumber: phone
    })
  )
);

Quick Start Helper

// Create assistant and start call in one go
const result = await vagel.quickStart({
  assistantName: 'Demo Bot',
  systemPrompt: 'You are a demo assistant',
  phoneNumber: '+1234567890',
  firstMessage: 'Hello! This is a demo call.'
});

console.log('Assistant:', result.assistant.id);
console.log('Call:', result.call.id);

📱 Platform Support

• ✅ Node.js 14+
• ✅ Browser (Chrome, Firefox, Safari, Edge)
• ✅ React / Vue / Angular
• ✅ React Native / Expo
• ✅ Electron
• ✅ TypeScript (full type support)

🔒 Security

• API keys are never logged or exposed
• All requests use HTTPS
• Automatic retry with exponential backoff
• Request timeout protection
• Input validation and sanitization

📖 TypeScript Support

Full TypeScript definitions included:

import VagelAI, { Assistant, Call, Analytics } from '@vagel/ai';

const vagel = new VagelAI('your_api_key');

// Fully typed responses
const assistant: Assistant = await vagel.assistants.create({
  name: 'Typed Bot',
  systemPrompt: 'Hello TypeScript!'
});

const call: Call = await vagel.calls.start({
  assistantId: assistant.id,
  phoneNumber: '+1234567890'
});

🆘 Support

• 📧 Email: [email protected]
• 📚 Documentation: https://docs.vagel.ai
• 💬 Discord: https://discord.gg/vagel-ai
• 🐛 Issues: https://github.com/vagel-ai/sdk/issues

📄 License

MIT License - see LICENSE file for details.

🚀 What's Next?

• WebSocket support for real-time events
• React hooks package (@vagel/react)
• Python SDK (@vagel/python)
• Voice streaming capabilities
• Advanced analytics dashboard

Made with ❤️ by the Vagel AI team