@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
✅ Pre-built UI - Includes Dialpad, CallInterface, and CreditBalance
✅ Auto state management - Automatic call state and connection tracking
✅ DID Management - Hooks to fetch and switch between caller IDs

Installation

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

[!NOTE] @dora-cell/sdk is a peer dependency of this package. jssip will be installed automatically as a dependency of the SDK.

Quick Start

1. Wrap your app with DoraCellProvider

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

function App() {
  return (
    <DoraCellProvider
      config={{
        auth: {
          type: "api-token",
          publicKey: "pk_...",
          secretKey: "sk_...",
        },
        environment: "production",
      }}
      autoInitialize={true}
    >
      <MainApp />
    </DoraCellProvider>
  );
}

2. Use Hooks in your components

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

function CallManager() {
  const { call, callStatus, callDuration } = useCall();
  const { isConnected } = useConnectionStatus();

  return (
    <div>
      <p>Status: {isConnected ? "Ready" : "Connecting..."}</p>
      {callStatus === "ongoing" && <p>Talking: {callDuration}</p>}
      <button onClick={() => call("08012345678")} disabled={!isConnected}>
        Call Now
      </button>
    </div>
  );
}

UI Components

We provide high-level components that match the Dora Cell design language.

CallInterface

A slide-over interface that handles the entire call lifecycle (Ringing, Connecting, Ongoing, Mute controls).

[!TIP] This component handles audio playback (remote stream and ringtones) automatically. You just need to ensure it's rendered in your tree when a call is active.

Props

• isOpen?: boolean - Controls if the interface is visible.
• onOpenChange?: (open: boolean) => void - Callback when the interface requests to open/close.
• onCallEnded?: () => void - Callback fired when a call ends.
• maximizeIcon?: React.ReactNode - Custom icon for the maximize button.
• minimizeIcon?: React.ReactNode - Custom icon for the minimize button.

import { CallInterface } from "@dora-cell/sdk-react";
import { Maximize, Minimize2 } from "lucide-react";

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

  return (
    <>
      {/* 
        This should be rendered globally (e.g., in your root layout) 
        to handle incoming calls even when the dialer is closed.
      */}
      <CallInterface 
        isOpen={isOpen} 
        onOpenChange={setIsOpen} 
        onCallEnded={() => console.log('Call ended')}
        maximizeIcon={<Maximize size={18} />}
        minimizeIcon={<Minimize2 size={16} />}
      />
    </>
  );
}

Dialpad

A flexible keypad for entering numbers and initiating calls. It automatically fetches available Caller IDs (extensions) and allows switching between them. If you prefer to manage the extensions in your own state, you can pass them as props.

Props

• initialNumber?: string - Pre-fill the dialpad input.
• showKeys?: boolean - Whether to show the numeric keypad by default (default: true).
• className?: string - Custom CSS classes for styling.
• availableExtensions?: Array<{ label: string; value: string }> - Override the automatically fetched caller IDs.
• selectedExtension?: string - Manually select the active caller ID.
• onExtensionChange?: (ext: string) => void - Callback fired when the user selects a different caller ID.
• onCallInitiated?: (number: string) => void - Callback fired right after a call starts.

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

function Dialer() {
  return (
    <Dialpad 
      initialNumber="+2348000000000"
      showKeys={true}
      className="my-custom-class"
      onCallInitiated={(number) => console.log('Calling', number)}
    />
  );
}

CreditBalance

A standalone component that displays the user's current credit balance and currency. It automatically refreshes whenever the SDK initializes and whenever a call ends.

import { CreditBalance } from "@dora-cell/sdk-react";

function Header() {
  return (
    <header>
      <h1>My App</h1>
      <CreditBalance />
    </header>
  );
}

API Reference

useCall()

Returns methods and state for the active call.

• call(number): Initiate a call.
• hangup(): End current call.
• answerCall(): Answer incoming call.
• toggleMute(): Toggle microphone.
• callStatus: 'idle' | 'connecting' | 'ringing' | 'ongoing' | 'ended'.
• callDuration: Formatted string "00:00".
• isMuted: Boolean state.

useConnectionStatus()

Returns the SIP registration state.

• isConnected: true when registered and ready.
• connectionStatus: 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed'.
• extension: The currently registered extension number.
• error: Any connection error object.

useWallet()

Returns the user's credit balance.

• balance: Numerical balance.
• currency: Currency code (e.g., "NGN").
• isLoading: Boolean loading state.
• refresh(): Fetch the latest balance.

useExtensions()

Returns available Caller IDs.

• extensions: Array of available DID numbers/extensions.
• setExtension(ext): Switch to a different Caller ID.
• isLoading: Boolean loading state.

Styling

The components use Tailwind CSS internally. To avoid conflicts, all styles are prefixed with dora-. You must import the CSS file in your main entry file (e.g., layout.tsx or App.tsx):

import "@dora-cell/sdk-react/styles.css";

License

MIT