@dora-cell/sdk-react

React hooks and components for the Dora Cell VoIP SDK.

Features

✅ React Hooks - Easy-to-use hooks for call management
✅ Context Provider - Simple setup with DoraCellProvider
✅ TypeScript support - Full type definitions included
✅ Auto state management - Automatic call state and connection tracking
✅ React 18 & 19 compatible - Works with latest React versions

Installation

npm install @dora-cell/sdk @dora-cell/sdk-react jssip
# or
yarn add @dora-cell/sdk @dora-cell/sdk-react jssip
# or
pnpm add @dora-cell/sdk @dora-cell/sdk-react jssip

Quick Start

Authentication

You can authenticate using either an API Token (recommended for production) or Direct SIP Credentials (useful for testing/development).

Option 1: API Token (Production)

The SDK will fetch SIP credentials from your backend using the token.

const config = {
  auth: {
    type: 'api-token',
    apiToken: 'YOUR_API_TOKEN',
    // apiBaseUrl: 'https://api.your-backend.com' (Optional)
  }
};

Option 2: Extension Authentication (Plug & Play)

You can connect using just your extension number. The SDK handles the server configuration automatically.

const config = {
  auth: {
    type: 'extension',
    extension: '1000',
    // password: '...' // Optional override (default: 1234)
  }
};

1. Wrap your app with DoraCellProvider

import { DoraCellProvider } from '@dora-cell/sdk-react';

function App() {
  return (
    <DoraCellProvider
      config={{
        auth: {
          type: 'api-token',
          apiToken: 'your-api-token-here',
          apiBaseUrl: 'https://api.usedora.com'
        },
        debug: true
      }}
    >
      <YourApp />
    </DoraCellProvider>
  );
}

2. Use hooks in your components

import { useCall, useConnectionStatus } from '@dora-cell/sdk-react';

function CallInterface() {
  const { 
    call, 
    hangup, 
    toggleMute, 
    callStatus, 
    callDuration, 
    isMuted,
    currentCall 
  } = useCall();
  
  const { isConnected, status } = useConnectionStatus();
  const [number, setNumber] = useState('');

  const handleCall = async () => {
    try {
      await call(number);
    } catch (error) {
      console.error('Call failed:', error);
    }
  };

  return (
    <div>
      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
      
      {callStatus === 'idle' && (
        <>
          <input
            value={number}
            onChange={(e) => setNumber(e.target.value)}
            placeholder="Enter phone number"
          />
          <button onClick={handleCall} disabled={!isConnected}>
            Call
          </button>
        </>
      )}
      
      {callStatus === 'ongoing' && (
        <>
          <p>Call with: {currentCall?.remoteNumber}</p>
          <p>Duration: {callDuration}</p>
          <button onClick={toggleMute}>
            {isMuted ? 'Unmute' : 'Mute'}
          </button>
          <button onClick={hangup}>Hang Up</button>
        </>
      )}
      
      {callStatus === 'ringing' && (
        <p>Ringing...</p>
      )}
    </div>
  );
}

API Reference

DoraCellProvider

Wrap your app with this provider to enable SDK functionality.

<DoraCellProvider
  config={{
    auth: {
      type: 'api-token',
      apiToken: string,
      apiBaseUrl?: string
    },
    turnServers?: RTCIceServer[],
    debug?: boolean,
    autoSelectExtension?: boolean
  }}
>
  {children}
</DoraCellProvider>

useCall()

Hook for managing calls.

const {
  // Methods
  call: (phoneNumber: string) => Promise<void>,
  hangup: () => void,
  answerCall: () => void,
  toggleMute: () => void,
  
  // State
  callStatus: 'idle' | 'ringing' | 'ongoing',
  callDuration: string, // Formatted as "MM:SS"
  isMuted: boolean,
  currentCall: Call | null,
  error: Error | null
} = useCall();

Methods:

• call(phoneNumber) - Make an outbound call
• hangup() - End the current call
• answerCall() - Answer an incoming call
• toggleMute() - Toggle mute/unmute

State:

• callStatus - Current call status
• callDuration - Formatted call duration (e.g., "01:23")
• isMuted - Whether the call is muted
• currentCall - Current call object with details
• error - Any call-related errors

useConnectionStatus()

Hook for monitoring connection status.

const {
  isConnected: boolean,
  status: 'disconnected' | 'connecting' | 'connected' | 'error',
  error: Error | null
} = useConnectionStatus();

useDoraCell()

Access the underlying SDK instance directly.

const sdk = useDoraCell();

// Use SDK methods directly
sdk.getExtensions();
sdk.on('call:incoming', (call) => {
  console.log('Incoming call from:', call.remoteNumber);
});

UI Components

The SDK includes pre-built UI components for typical call flows.

CallInterface

A complete active call modal that handles ringing, connecting, and ongoing call states.

import { CallInterface } from '@dora-cell/sdk-react';

function MyApp() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <CallInterface 
        isOpen={isOpen}
        onOpenChange={setIsOpen}
        onCallEnded={() => console.log('Call ended')}
      />
    </>
  );
}

Dialpad

A dialpad component for entering phone numbers and placing calls.

import { Dialpad } from '@dora-cell/sdk-react';

function MyApp() {
  return (
    <Dialpad 
      onCallInitiated={(number) => console.log('Calling:', number)}
      initialNumber=""
    />
  );
}

Advanced Usage

Handling Incoming Calls

function IncomingCallHandler() {
  const { currentCall, answerCall, hangup, callStatus } = useCall();
  const sdk = useDoraCell();

  useEffect(() => {
    const handleIncoming = (call) => {
      // Show notification or UI for incoming call
      console.log('Incoming call from:', call.remoteNumber);
    };

    sdk.on('call:incoming', handleIncoming);
    return () => sdk.off('call:incoming', handleIncoming);
  }, [sdk]);

  if (callStatus === 'ringing' && currentCall?.direction === 'inbound') {
    return (
      <div>
        <p>Incoming call from {currentCall.remoteNumber}</p>
        <button onClick={answerCall}>Answer</button>
        <button onClick={hangup}>Decline</button>
      </div>
    );
  }

  return null;
}

Custom Extension Selection

function CallWithExtension() {
  const sdk = useDoraCell();
  const [selectedExtension, setSelectedExtension] = useState('');

  const extensions = sdk.getExtensions();

  const makeCall = async (number: string) => {
    await sdk.call(number, { extension: selectedExtension });
  };

  return (
    <div>
      <select 
        value={selectedExtension} 
        onChange={(e) => setSelectedExtension(e.target.value)}
      >
        {extensions.map(ext => (
          <option key={ext} value={ext}>{ext}</option>
        ))}
      </select>
      {/* Rest of your call UI */}
    </div>
  );
}

Error Handling

function CallWithErrorHandling() {
  const { call, error, callStatus } = useCall();
  const [number, setNumber] = useState('');

  const handleCall = async () => {
    try {
      await call(number);
    } catch (err) {
      console.error('Call failed:', err);
      // Show error to user
    }
  };

  return (
    <div>
      {error && <div className="error">{error.message}</div>}
      {/* Rest of your UI */}
    </div>
  );
}

TypeScript Support

All hooks and components are fully typed. Import types as needed:

import type { Call, CallStatus, ConnectionStatus } from '@dora-cell/sdk';
import type { DoraCellConfig } from '@dora-cell/sdk-react';

Examples

See the /examples directory in the main repository for complete working examples:

• react-app/ - React application with hooks
• nextjs-app/ - Next.js application

Requirements

• React 18.0.0 or higher (including React 19)
• @dora-cell/sdk (peer dependency)
• jssip (peer dependency)

License

MIT

Related Packages

• @dora-cell/sdk - Core VoIP SDK