Zerorate VoIP SDK

[BEFORE YOU INSTALL: IMPORTANT NOTICE]: This SDK is customly built to be use by merchants on the freepass.africa platform.

Production-ready, framework-agnostic JavaScript/TypeScript SDK to add in-app VoIP calling to any web application. Handles WebSocket signaling, LiveKit WebRTC integration, call state management, and provides a simple API with optional pre-built UI and framework adapters.

Installation

npm install @freepass/voip-sdk

Quick Start (ESM)

import ZerorateVoIPClient from "@freepass/voip-sdk";
import "@freepass/voip-sdk/dist/voip-sdk.css";

const voip = new ZerorateVoIPClient({
  backendUrl: "https://api.example.com",
  wsUrl: "wss://api.example.com/ws",
  userId: "user_123",
  userName: "John Doe",
  authToken: "your-jwt",
  enableUI: true,
  theme: "light",
});

await voip.connect();

voip.on("incoming_call", (data) => {
  // show incoming UI or auto accept
});

await voip.initiateCall("user_456", "Jane Smith", { isVideo: false });

Quick Start (UMD)

<script src="https://cdn.example.com/voip-sdk.min.js"></script>
<link rel="stylesheet" href="https://cdn.example.com/voip-sdk.css" />
<script>
  const client = new ZerorateVoIPSDK.ZerorateVoIPClient({
    backendUrl: "https://api.example.com",
    wsUrl: "wss://api.example.com/ws",
    userId: "user_123",
    userName: "John Doe",
  });
  client.connect();
  client.initiateCall("user_456", "Jane Smith", { isVideo: false });
</script>

Configuration

• backendUrl: string
• wsUrl: string
• userId: string
• userName: string
• authToken?: string
• enableUI?: boolean
• theme?: 'light' | 'dark' | 'auto'
• ringTones?: { incoming?: string; outgoing?: string }
• autoReconnect?: boolean
• debug?: boolean

Public API

• connect(): Promise
• disconnect(): void
• isConnected(): boolean
• initiateCall(userId: string, userName: string, options?: { isVideo?: boolean }): Promise
• acceptCall(callId: string): Promise
• declineCall(callId: string): Promise
• endCall(callId: string): Promise
• toggleMicrophone(): Promise
• toggleVideo(): Promise
• setMicrophoneEnabled(enabled: boolean): Promise
• setVideoEnabled(enabled: boolean): Promise
• getCallState(): 'idle' | 'calling' | 'ringing' | 'connecting' | 'connected' | 'ending'
• getActiveCall(): CallData | null
• isInCall(): boolean
• on(event, callback): void
• off(event, callback): void
• once(event, callback): void
• showUI(): void
• hideUI(): void
• setTheme(theme): void
• destroy(): void

Events

• connected, disconnected, reconnecting, error
• incoming_call, call_accepted, call_declined, call_missed, call_accepted, call_ended, call:error
• media:microphone-changed, media:video-changed
• state:changed

Optional UI Components

• Include CSS: import '@freepass/voip-sdk/dist/voip-sdk.css'
• Use UIManager to render:
  • showIncomingCall(callData)
  • showOutgoingCall(callData)
  • showActiveCall(callData)
  • hideAllModals(), show(), hide(), setTheme(theme)

React Adapter

import { useVoIP } from "@freepass/voip-sdk/src/adapters/react/useVoIP";
const { isConnected, callState, initiateCall } = useVoIP(config);

Vue Adapter

import { useVoIP } from "@freepass/voip-sdk/src/adapters/vue/useVoIP";
const { state, initiateCall } = useVoIP(config);

Examples

• Vanilla: see examples/vanilla/index.html
• React: see examples/react/App.tsx

Build Scripts

• Build: npm run build (UMD + ESM + CSS copy)
• Typecheck: npm run typecheck
• Lint: npm run lint