@dora-cell/sdk-react

React bindings, hooks, and UI components for @dora-cell/sdk.

Features

• DoraCellProvider for app-wide SDK lifecycle, user login auth, and call state
• Automatic cookie session restoration across page refreshes when autoInitialize={true}
• Hooks for calls, connection status, wallet balance, and extensions (useCall, useConnectionStatus, useWallet, useExtensions)
• Built-in logout() helper on useDoraCell() and useConnectionStatus() for one-click sign out and session cleanup
• Pre-built Dialpad, CallInterface, and CreditBalance components
• Incoming and outgoing call state management
• DID/caller ID selection
• Self-contained CSS with dora- prefixed classes

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

@dora-cell/sdk is a peer dependency. react and react-dom 18 or 19 are supported.

Quick Start

1. Import the styles

Import the bundled CSS once in your app entry file, root layout, or top-level component.

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

2. Wrap your app with DoraCellProvider

Configure DoraCellProvider with User Login Credentials (type: "login"). The provider automatically persists session tokens in browser cookies (dora_cell_auth_token).

1. For Agent Accounts (email required):

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

export function App() {
  return (
    <DoraCellProvider
      config={{
        auth: {
          type: "login",
          userType: "agent",
          email: "[email protected]", // Agent accounts must use email
          password: "password",
        },
        environment: "production",
      }}
      autoInitialize={true}
    >
      <MainApp />
    </DoraCellProvider>
  );
}

2. For Admin Accounts (username required):

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

export function App() {
  return (
    <DoraCellProvider
      config={{
        auth: {
          type: "login",
          userType: "admin",
          username: "admin_user", // Admin accounts must use username instead of email
          password: "password",
        },
        environment: "production",
      }}
      autoInitialize={true}
    >
      <MainApp />
    </DoraCellProvider>
  );
}

Automatic Cookie Recovery: If a user previously logged in, their session token is saved in document.cookie (dora_cell_auth_token). When autoInitialize={true} is enabled, DoraCellProvider will automatically read the saved cookie token on reload and reconnect without re-prompting for email/username/password.

3. Use hooks in your components

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

function DashboardBar() {
  const { call, callStatus, callDuration } = useCall();
  const { isConnected, extension, logout } = useConnectionStatus();

  return (
    <div className="flex items-center justify-between p-4 bg-white shadow rounded-lg">
      <div>
        <p className="font-semibold">{isConnected ? `Ready (${extension})` : "Connecting..."}</p>
        {callStatus === "ongoing" && <p className="text-emerald-600">Talking: {callDuration}</p>}
      </div>
      
      <div className="flex gap-2">
        <button
          onClick={() => call("+2348012345678")}
          disabled={!isConnected || callStatus !== "idle"}
          className="px-4 py-2 bg-emerald-500 text-white rounded-md disabled:opacity-50"
        >
          Call
        </button>
        
        {isConnected && (
          <button
            onClick={() => logout()}
            className="px-4 py-2 bg-rose-500 text-white rounded-md hover:bg-rose-600"
          >
            Logout
          </button>
        )}
      </div>
    </div>
  );
}

UI Components

CallInterface

A slide-over interface for incoming and active calls. It handles remote audio playback, answering, hanging up, mute controls, minimized state, and auto-open for incoming calls.

Render it near the root of your app so incoming calls can display no matter where the user is.

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

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

  return (
    <CallInterface
      isOpen={isOpen}
      onOpenChange={setIsOpen}
      onCallEnded={() => console.log("Call ended")}
      maximizeIcon={<Maximize size={18} />}
      minimizeIcon={<Minimize2 size={16} />}
    />
  );
}

Props

• isOpen?: boolean: Controls whether the interface is visible.
• onOpenChange?: (open: boolean) => void: Called when the interface requests to open or close.
• onCallEnded?: () => void: Called when a call ends.
• maximizeIcon?: React.ReactNode: Custom icon for the maximize button.
• minimizeIcon?: React.ReactNode: Custom icon for the minimize button.
• ringtoneUrl?: string: Reserved for custom ringtone audio.
• ringbackUrl?: string: Reserved for custom ringback audio.

Dialpad

A keypad for entering numbers, selecting caller ID, and starting outbound calls. It fetches extensions automatically through useExtensions(), or you can pass your own extension list.

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

function Dialer() {
  return (
    <Dialpad
      initialNumber="+2348012345678"
      showKeys={true}
      metadata={{ source: "dashboard" }}
      onCallInitiated={(number) => console.log("Calling", number)}
    />
  );
}

Props

• initialNumber?: string: Pre-fill the dialpad input.
• showKeys?: boolean: Show the numeric keypad by default. Defaults to true.
• className?: string: Custom CSS classes for the wrapper.
• availableExtensions?: Array<{ label: string; value: string }>: Override automatically fetched caller IDs.
• selectedExtension?: string: Control the active caller ID.
• onExtensionChange?: (ext: string) => void: Called when the user selects a caller ID.
• onCallInitiated?: (number: string) => void: Called after a call starts.
• metadata?: Record<string, unknown>: Metadata passed to sdk.call().

CreditBalance

Displays the current wallet balance. It fetches after SDK initialization and refreshes shortly after calls end.

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

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

Hooks

useDoraCell()

Returns the full provider context. It must be used inside DoraCellProvider.

• sdk: The DoraCell instance.
• connectionStatus: Current SDK connection status.
• currentCall: Current call object, if any.
• callStatus: Current call status.
• callDuration: Formatted duration string.
• isMuted: Current mute state.
• isInitialized: Whether initialization completed enough for SDK operations.
• error: Latest SDK error.
• extension: Current registered extension, when known.
• call(phoneNumber, extension?, metadata?): Start an outbound call.
• hangup(): End current call.
• toggleMute(): Toggle microphone mute.
• answerCall(): Answer an incoming call.
• logout(): Disconnect User Agent, invoke backend sign-out route (/agent/logout or /logout), and clear browser cookies (dora_cell_auth_token).

useCall()

Focused call state and actions.

• sdk: The DoraCell instance.
• call(phoneNumber, extension?, metadata?): Start an outbound call.
• hangup(): End current call.
• answerCall(): Answer incoming call.
• toggleMute(): Toggle microphone.
• callStatus: "idle" | "connecting" | "ringing" | "ongoing" | "ended" | "terminating".
• callDuration: Formatted string such as "00:42".
• isMuted: Boolean mute state.
• currentCall: Active call object, if any.
• callError: Latest call error message.
• isInitialized: Provider initialization state.

useConnectionStatus()

Connection and registration state.

• isConnected: true when SIP registration is complete.
• connectionStatus: "disconnected" | "connecting" | "connected" | "registered" | "registrationFailed".
• isInitialized: Provider initialization state.
• extension: Current extension, when known.
• error: Latest connection or SDK error.
• logout(): Disconnect User Agent, invoke backend sign-out route (/agent/logout or /logout), and clear browser cookies (dora_cell_auth_token).

useWallet()

Wallet balance state.

• balance: Numeric balance. Defaults to 0.
• currency: Currency code. Defaults to "NGN".
• isLoading: Loading state.
• error: Latest wallet error.
• refresh(): Fetch the latest balance.

useExtensions()

Available DID/caller ID state.

• extensions: Array of extension records returned by the API.
• isLoading: Loading state.
• error: Latest extension error.
• setExtension(extension): Switch the active caller ID and re-register SIP.
• refresh(): Fetch extensions again.

Styling

Components use bundled Tailwind-generated CSS with the dora- prefix to reduce collisions with host apps.

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

If your bundler cannot resolve package CSS exports, import @dora-cell/sdk-react/dist/styles.css instead.

Browser Requirements

The underlying SDK uses WebRTC, so your app must run on HTTPS or localhost, and users must grant microphone permission.

License

MIT