Quick Start

# Header format
Authorization: Token <YOUR_API_KEY>

# Example request
curl -X GET https://api.tryhamsa.com/v1/voice-agents \
  -H "Authorization: Token sk_live_abc123xyz789" \
  -H "Content-Type: application/json"

# Header format
Authorization: Bearer <JWT_TOKEN>

# Example
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "headers": [
    {
      "name": "X-API-Key",
      "value": "your_custom_api_key"
    },
    {
      "name": "X-Client-ID",
      "value": "client_123"
    }
  ]
}

https://api.tryhamsa.com

/v1/voice-agents     # Version 1
/v2/voice-agents     # Version 2 (recommended for new integrations)

Content-Type: application/json
Authorization: Token <YOUR_API_KEY>

{
  "success": true,
  "data": {
    // Response data
  }
}

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

const response = await fetch('https://api.tryhamsa.com/v2/voice-agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Token sk_live_abc123',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Customer Support Agent',
    preamble: 'You are a helpful customer support agent...',
    greeting: 'Hello! How can I help you today?',
    language: 'en-US',
    voiceId: 'voice_abc123'
  })
});

const data = await response.json();
console.log('Created agent:', data.data.id);

const ws = new WebSocket('wss://api.tryhamsa.com/v1/realtime/ws?api_key=YOUR_API_KEY');

ws.onopen = async () => {
  // Get audio from microphone
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const mediaRecorder = new MediaRecorder(stream);
  const chunks = [];

  mediaRecorder.ondataavailable = (e) => chunks.push(e.data);

  mediaRecorder.onstop = async () => {
    const blob = new Blob(chunks);
    const buffer = await blob.arrayBuffer();
    const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));

    ws.send(JSON.stringify({
      type: 'stt',
      payload: {
        audioBase64: base64,
        language: 'ar',
        isEosEnabled: true,
        eosThreshold: 0.3
      }
    }));
  };

  mediaRecorder.start();
  setTimeout(() => mediaRecorder.stop(), 3000); // Record 3 seconds
};

ws.onmessage = (event) => {
  if (typeof event.data === 'string') {
    try {
      const json = JSON.parse(event.data);
      if (json.type === 'error') {
        console.error('Error:', json.payload.message);
      }
    } catch {
      // Plain text transcription result
      console.log('Transcription:', event.data);
    }
  }
};

const response = await fetch('https://api.tryhamsa.com/v1/realtime/tts', {
  method: 'POST',
  headers: {
    'Authorization': 'Token sk_live_abc123',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello, how can I help you today?',
    voiceId: 'voice_abc123',
    speed: 1.0,
    pitch: 1.0
  })
});

const audioBlob = await response.blob();
const audioUrl = URL.createObjectURL(audioBlob);

const response = await fetch('https://api.tryhamsa.com/v1/realtime/tts-stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Token sk_live_abc123',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'This is a longer text that will be streamed...',
    voiceId: 'voice_abc123'
  })
});

// Process streaming response
const reader = response.body.getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  // Process audio chunk
  playAudioChunk(value);
}

npm install @hamsa-ai/voice-agents-sdk

<script src="https://unpkg.com/@hamsa-ai/voice-agents-sdk@latest/dist/index.umd.js"></script>

import { HamsaVoiceAgent } from '@hamsa-ai/voice-agents-sdk';

// Initialize
const agent = new HamsaVoiceAgent('YOUR_API_KEY');

// Start conversation
await agent.start({
  agentId: 'agent_abc123',
  params: {
    user_name: 'John Doe',
    user_id: 'user_123',
    session_id: 'session_abc'
  },
  voiceEnablement: true,
  userId: 'user_123'
});

// Event listeners
agent.on('callStarted', ({ jobId }) => {
  console.log('Call started:', jobId);
});

agent.on('transcriptionReceived', (text) => {
  console.log('User said:', text);
});

agent.on('answerReceived', (text) => {
  console.log('Agent said:', text);
});

agent.on('agentStateChanged', (state) => {
  // state: 'idle' | 'initializing' | 'listening' | 'thinking' | 'speaking'
  updateUI(state);
});

agent.on('callEnded', () => {
  console.log('Call ended');
});

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

await agent.start({
  agentId: 'agent_abc123',
  voiceEnablement: true,

  // Custom parameters (echoed in webhooks)
  params: {
    application_id: '12345',
    user_id: 'user_789',
    session_id: 'sess_abc',
    custom_data: JSON.stringify({ key: 'value' })
  },

  // User tracking
  userId: 'user_789',

  // iOS optimization
  preferHeadphonesForIosDevices: true,

  // Platform-specific connection delays
  connectionDelay: {
    android: 3000,  // Android needs longer delay
    ios: 500,
    default: 1000
  },

  // Audio capture for third-party services
  onAudioData: (audioData) => {
    thirdPartyWebSocket.send(audioData);
  },

  // Client-side tools
  tools: [
    {
      function_name: 'getUserInfo',
      description: 'Get user information',
      parameters: [
        { name: 'userId', type: 'string', description: 'User ID' }
      ],
      required: ['userId'],
      fn: async (userId) => {
        return await fetchUserInfo(userId);
      }
    }
  ]
});

// Volume control
agent.setVolume(0.8);
const volume = agent.getOutputVolume();

// Microphone control
agent.setMicMuted(true);
agent.setMicMuted(false);
const isMuted = agent.isMicMuted();

// Audio levels
const inputLevel = agent.getInputVolume();
const outputLevel = agent.getOutputVolume();

// Frequency data for visualization
const inputFreqData = agent.getInputByteFrequencyData();
const outputFreqData = agent.getOutputByteFrequencyData();

// Get comprehensive analytics
const analytics = agent.getCallAnalytics();
console.log(analytics);
/*
{
  connectionStats: { quality: 'good', connectionAttempts: 1, ... },
  audioMetrics: { userAudioLevel: 0.8, agentAudioLevel: 0.3, ... },
  performanceMetrics: { callDuration: 60000, responseTime: 1200, ... },
  participants: [...],
  trackStats: { totalTracks: 2, activeTracks: 2, ... }
}
*/

// Real-time connection quality
agent.on('connectionQualityChanged', ({ quality, metrics }) => {
  if (quality === 'poor') {
    showNetworkWarning();
  }
});

// Custom events from agent
agent.on('customEvent', (eventType, eventData, metadata) => {
  if (eventType === 'tool_execution') {
    console.log('Tool called:', eventData.toolName);
  }
});

// Pause conversation
agent.pause();

// Resume conversation
agent.resume();

// End conversation
agent.end();

// Get current job ID
const jobId = agent.getJobId();

{
  "webhookUrl": "https://api.yourcompany.com/webhook/hamsa",
  "webhookAuth": {
    "authKey": "bearer",
    "authSecret": "Bearer your_secret_token_here"
  }
}

{
  "eventType": "call.ended",
  "callId": "call_uuid_12345",
  "timestamp": "2024-01-15T14:35:00.000Z",
  "projectId": "proj_abc123",
  "agentId": "agent_xyz789",
  "agentName": "Customer Support Agent",
  "data": {
    "timestamp": "2024-01-15T14:35:00.000Z",
    "data": {
      "conversationId": "conv-123-abc-456-def",
      "conversationRecording": "https://storage.tryhamsa.com/recordings/conv-123.mp3",
      "transcription": [
        { "Agent": "Hello! How can I help you today?" },
        { "User": "I need help with my order." },
        { "Agent": "I'd be happy to help. What's your order number?" },
        { "User": "It's ORD-12345." }
      ],
      "outcomeResult": {
        "application_id": "12345",
        "user_id": "user-789",
        "session_id": "sess-abc-def",
        "order_number": "ORD-12345",
        "issue_type": "order_inquiry",
        "resolved": true,
        "sentiment_score": 0.8
      }
    }
  }
}

async function apiRequest(endpoint, options = {}) {
  const maxRetries = 3;
  let lastError;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(`https://api.tryhamsa.com${endpoint}`, {
        ...options,
        headers: {
          'Authorization': `Token ${process.env.HAMSA_API_KEY}`,
          'Content-Type': 'application/json',
          ...options.headers
        }
      });

      const data = await response.json();

      if (!response.ok) {
        // Handle specific error codes
        switch (response.status) {
          case 401:
            throw new AuthenticationError('Invalid API key');
          case 404:
            throw new NotFoundError(data.error?.message || 'Resource not found');
          case 429:
            // Rate limited - wait and retry
            const retryAfter = response.headers.get('Retry-After') || 60;
            await sleep(retryAfter * 1000);
            continue;
          case 500:
          case 503:
            // Server error - retry with backoff
            if (attempt < maxRetries) {
              await sleep(Math.pow(2, attempt) * 1000);
              continue;
            }
            throw new ServerError(data.error?.message || 'Server error');
          default:
            throw new APIError(data.error?.message || 'API request failed', response.status);
        }
      }

      return data;

    } catch (error) {
      lastError = error;

      // Don't retry on authentication or validation errors
      if (error instanceof AuthenticationError || error instanceof ValidationError) {
        throw error;
      }

      // Retry on network errors
      if (attempt < maxRetries && error.name === 'NetworkError') {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
    }
  }

  throw lastError;
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

async function handleRateLimit(response) {
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    const resetTime = response.headers.get('X-RateLimit-Reset');

    // Wait for the specified time
    const waitTime = retryAfter
      ? parseInt(retryAfter) * 1000
      : (parseInt(resetTime) - Date.now());

    console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
    await sleep(waitTime);

    return true; // Indicates retry is needed
  }
  return false;
}

// Implement connection health checks
class ConnectionMonitor {
  constructor(sdk) {
    this.sdk = sdk;
    this.reconnectAttempts = 0;
    this.maxReconnectAttempts = 5;

    this.sdk.on('connectionQualityChanged', ({ quality }) => {
      if (quality === 'lost') {
        this.handleDisconnection();
      }
    });

    this.sdk.on('reconnecting', () => {
      console.log('Attempting to reconnect...');
    });

    this.sdk.on('reconnected', () => {
      this.reconnectAttempts = 0;
      console.log('Reconnected successfully');
    });
  }

  async handleDisconnection() {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      this.notifyUser('Connection lost. Please refresh the page.');
      return;
    }

    this.reconnectAttempts++;
    const backoffTime = Math.pow(2, this.reconnectAttempts) * 1000;

    await sleep(backoffTime);

    try {
      await this.sdk.reconnect();
    } catch (error) {
      this.handleDisconnection();
    }
  }
}

// Handle partial webhook data
function processWebhookPayload(payload) {
  const { outcomeResult } = payload.data?.data || {};

  // Safely extract with defaults
  const data = {
    applicationId: outcomeResult?.application_id ?? null,
    userId: outcomeResult?.user_id ?? null,
    expectedSalary: outcomeResult?.expectedSalary ?? 'Not provided',
    noticePeriod: outcomeResult?.noticePeriod ?? 'Not provided',
    sentiment: outcomeResult?.sentiment_score ?? null
  };

  // Log missing critical fields
  if (!data.applicationId) {
    console.warn('Missing application_id in webhook payload');
  }

  return data;
}

// Use a request queue for concurrent operations
class RequestQueue {
  constructor(maxConcurrent = 5) {
    this.maxConcurrent = maxConcurrent;
    this.running = 0;
    this.queue = [];
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ fn: requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.running >= this.maxConcurrent || this.queue.length === 0) {
      return;
    }

    this.running++;
    const { fn, resolve, reject } = this.queue.shift();

    try {
      const result = await fn();
      resolve(result);
    } catch (error) {
      reject(error);
    } finally {
      this.running--;
      this.process();
    }
  }
}

// Usage
const queue = new RequestQueue(3);

const results = await Promise.all([
  queue.add(() => fetchAgent(1)),
  queue.add(() => fetchAgent(2)),
  queue.add(() => fetchAgent(3)),
  queue.add(() => fetchAgent(4)),
  queue.add(() => fetchAgent(5))
]);

// Idempotent operation wrapper
async function idempotentOperation(operationId, operation) {
  const key = `operation:${operationId}`;

  // Check if already processed
  const cached = await redis.get(key);
  if (cached) {
    return JSON.parse(cached);
  }

  // Execute operation
  const result = await operation();

  // Cache result with TTL
  await redis.setex(key, 86400, JSON.stringify(result));

  return result;
}

// Usage
await idempotentOperation(
  `create-agent-${sessionId}`,
  () => createVoiceAgent(agentConfig)
);

// Fallback strategy for service unavailability
async function callWithFallback(primaryFn, fallbackFn, options = {}) {
  const { timeout = 5000, retries = 2 } = options;

  for (let i = 0; i <= retries; i++) {
    try {
      const result = await Promise.race([
        primaryFn(),
        sleep(timeout).then(() => { throw new TimeoutError(); })
      ]);
      return result;
    } catch (error) {
      if (i === retries) {
        console.warn('Primary service failed, using fallback');
        return fallbackFn();
      }
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

// Usage
const result = await callWithFallback(
  () => fetchFromPrimaryAPI(),
  () => fetchFromCachedData(),
  { timeout: 3000, retries: 2 }
);