react-sip-kit

A modern React SIP.js toolkit for building web softphones and SIP clients.
Supports audio/video calls, call recording, screen sharing, and device management, all with a clean, extensible, TypeScript-first architecture.

✨ Features

• 📞 Audio & Video Calls — with device auto-detection
• 🎥 Video Support — render local & remote streams easily
• 🔴 Call Recording — audio/video capture
• 🖥️ Screen Sharing — during video calls
• 🎧 Device Management — choose input/output devices
• 🔄 Multi-Account & Multi-Line Support — concurrent calls
• ⚡ TypeScript-first API — safe and clean
• 🛠️ Configurable & Extensible

📦 Installation

npm install react-sip-kit
# or
yarn add react-sip-kit

🚀 Quick Start

1️⃣ Create a SipManager Instance

// main.tsx
import App from './App';
import { SipManager } from 'react-sip-kit';
import { StrictMode, useEffect } from 'react';
import { createRoot } from 'react-dom/client';

export const SipConnection = new SipManager();

const Providers = () => {
  const configs = [
    {
      key: 'support-01', // Optional → If omitted, defaults to account.username
      account: {
        domain: 'sip.example.com',
        username: '1010',
        password: 'password',
        wssServer: 'sip.example.com',
        webSocketPort: '8089',
        serverPath: '/ws',
      },
    },
  ];

  useEffect(() => {
    configs.forEach((config) => SipConnection.add(config));
  }, []);

  return (
    <StrictMode>
      <App />
    </StrictMode>
  );
};

createRoot(document.getElementById('root')!).render(<Providers />);

🔑 Resolving Accounts & Sessions

All lookups use one of the following keys:

| Key | Purpose | Example | | -------------- | ------------------------------------------------------------- | --------------------------------------------------- | | configKey | Refers to a specific SIP account instance | { configKey: 'support-01' } | | lineKey | Refers to an active call / line | { lineKey: 1 } | | remoteNumber | Refers to peer phone number — must be paired with configKey | { configKey: 'support-01', remoteNumber: '1001' } |

2️⃣ Access Methods (Dial, Hold, Mute, etc.)

// Using configKey
const { dialByNumber } = SipConnection.getSessionMethodsBy({ configKey: 'support-01' });
dialByNumber('audio', '1002');

// Using lineKey (after a call is active)
SipConnection.getSessionMethodsBy({ lineKey: 1 }).hold();

3️⃣ Read Account State (Reactive)

const { watch, status } = SipConnection.getAccountBy({ configKey: 'support-01' });
const account = watch(); // contains lines, registration, media devices, etc.

4️⃣ Track Session State (useWatchSessionData)

const isRecording = SipConnection.useWatchSessionData({
  key: { lineKey: 1 },
  name: 'recordMedia.recording',
});

const [mediaStatus, isMuted] = SipConnection.useWatchSessionData({
  key: { configKey: 'support-01', remoteNumber: '1002' },
  name: ['localMediaStreamStatus', 'localMediaStreamStatus.muted'],
});

5️⃣ Resolver Helper Methods

SipConnection.getLineBy({ lineKey: 1 });
SipConnection.getLineBy({ configKey: 'support-01', remoteNumber: '1002' });

SipConnection.getSessionBy({ lineKey: 1 });
SipConnection.getUsernameBy({ configKey: 'support-01', remoteNumber: '1002' });

6️⃣ Render Media Streams

import { VideoStream, AudioStream } from 'react-sip-kit';

<VideoStream type="local" lineKey={1} />
<VideoStream type="remote" lineKey={1} />
<AudioStream type="local" lineKey={1} />
<AudioStream type="remote" lineKey={1} />

🧠 Managing Config Keys & Dynamic Rendering

const configs = SipConnection.useWatchConfigs();
// → [{ key: 'support-01', account: {...} }, { key: 'sales-02', ... }]

✅ When to use useWatchConfigs()

| Scenario | Should you use it? | Reason | | ------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------- | | Static single account | ❌ Not required | configKey is constant | | You manually track configs in your own state | ❌ Optional | You already control the list | | Rendering UI for each config account dynamically | ✅ Yes — recommended | Ensures you always use the correct configKey, even if keys are auto-generated | | Configs can be added or removed at runtime | ✅ Always | Prevents mismatched lookups or stale references |

✔ Best Practice: Always call useWatchConfigs() when rendering lists of lines or accounts, to ensure that each component receives the correct and current configKey.

Example (Rendering a phone UI for every config dynamically):

const App = () => {
  const configs = SipConnection.useWatchConfigs();

  return (
    <>
      {configs.map((config) => (
        <Lines key={config.key} configKey={config.key} />
      ))}
    </>
  );
};

⚙️ Configuration Schema

{
  key?: string; // optional → falls back to account.username
  account: {
    domain: 'your.sip.domain',
    username: 'user',
    password: 'secret',
    wssServer: 'your.sip.domain',
    webSocketPort: '8089',
    serverPath: '/ws',
  },
  features?: { enableVideo?: boolean },
  media?: {
    audioInputDeviceId?: string;
    audioOutputDeviceId?: string;
    videoInputDeviceId?: string;
  },
  registration?: { registerExpires?: number },
}

✅ Best Practices

| Task | Recommended Approach | | ---------------------- | --------------------------------- | | Reference active call | Use lineKey when available | | Reference account | Use configKey | | Lookup by phone number | Use { configKey, remoteNumber } | | Track config keys | Use useWatchConfigs() | | Watch configs state | useWatchConfigs() | | Watch account state | getAccountBy().watch() | | Watch session props | useWatchSessionData() |

📂 Examples

Check /example for:

• Multi-account softphone
• Audio/video calls
• Hold / mute / attended transfer
• Call recording & screen sharing
• Stream rendering

📄 License

MIT

👤 Author

Shervin Ghajar

• GitHub: https://github.com/shervin-ghajar
• NPM: https://www.npmjs.com/package/react-sip-kit
• Repository: https://github.com/shervin-ghajar/react-sip-kit