Dora Cell
DOCUMENTATION

Dora Cell SDK

The Dora Cell SDK lets you add VoIP calling to JavaScript and React applications. It authenticates with Dora Cell API tokens, provisions SIP credentials, registers a browser SIP user, and exposes a simple event-driven API for calls, caller IDs, and wallet balance.

Browser Support

For the best experience, we recommend using Chromium-based browsers (Chrome, Microsoft Edge, Brave, Opera). Our WebRTC implementation is highly optimized for the Chromium engine.

High Performance

Engineered for reliable, low-latency voice communication with crystal-clear audio quality.

Secure Auth

API-token authentication with automatic SIP provisioning and session handling.

Core SDK Installation

Install the base SDK to use it in browser-based JavaScript apps, including vanilla JS, React, Vue, Angular, and other frameworks.

1npm install @dora-cell/sdk

Initialization

Initialize the SDK with Dora Cell API-token credentials. The SDK uses those keys to fetch available extensions, provision SIP credentials, and register the active caller ID.

index.jsjavascript
1import { DoraCell } from "@dora-cell/sdk";
2 
3const sdk = new DoraCell({
4  auth: {
5    type: "api-token",
6    publicKey: "pk_live_your_key",
7    secretKey: "sk_live_your_secret",
8  },
9  environment: "production",
10  debug: false
11});
12 
13sdk.on("connection:status", ({ status, extension, error }) => {
14  console.log("Connection:", status, extension, error);
15});
16 
17await sdk.initialize();
18console.log("SDK is ready!");

Making & Receiving Calls

The SDK provides a simple interface for outbound calls, incoming calls, mute controls, and remote audio streams.

1// Place an outbound call
2const call = await sdk.call("+2348000000000", {
3  metadata: { customerId: "cus_123" }
4});
5 
6call.mute();
7call.unmute();
8call.hangup();
9 
10// Answer an incoming call
11sdk.on("call:incoming", async (call) => {
12  console.log("Incoming call from:", call.remoteNumber);
13  await sdk.answerCall();
14});
15 
16sdk.on("call:stream", (call, stream) => {
17  const audio = document.querySelector("audio#remote-audio");
18  if (audio) audio.srcObject = stream;
19});

Event Handlers

Stay updated with the call state by subscribing to SDK events.

1// Listen for connection status
2sdk.on("connection:status", ({ status, error }) => {
3  console.log("SIP Status changed:", status);
4});
5 
6// Listen for call transitions
7sdk.on("call:connected", (call) => {
8  console.log("Conversation started with:", call.remoteNumber);
9});
10 
11sdk.on("call:ended", (call, reason) => {
12  console.log("Call ended. Reason:", reason);
13});
14 
15sdk.on("call:failed", (call, error) => {
16  console.error("Call failed:", error);
17});

React SDK Installation

The React SDK requires the Core SDK as a peer dependency. Import the bundled stylesheet once in your root layout or app entry.

1npm install @dora-cell/sdk @dora-cell/sdk-react
2# or
3pnpm add @dora-cell/sdk @dora-cell/sdk-react

Setting up the Provider

Wrap your application tree with the DoraCellProvider to enable global call management.

layout.tsxtsx
1import { DoraCellProvider } from "@dora-cell/sdk-react";
2import "@dora-cell/sdk-react/styles.css";
3 
4export default function RootLayout({ children }) {
5  return (
6    <DoraCellProvider
7      config={{
8        auth: {
9          type: "api-token",
10          publicKey: "pk_...",
11          secretKey: "sk_...",
12        },
13        environment: "production"
14      }}
15      autoInitialize={true}
16    >
17      {children}
18    </DoraCellProvider>
19  );
20}

Hooks Overview

useCall()

Manage active calls, mute, and duration.

useConnectionStatus()

Monitor SIP registration and errors.

useWallet()

Read and refresh wallet balance.

useExtensions()

Fetch caller IDs and switch extensions.

Dialer.tsxtsx
1import { useCall, useConnectionStatus } from "@dora-cell/sdk-react";
2 
3export function Dialer() {
4  const { call, callStatus, callDuration } = useCall();
5  const { isConnected, connectionStatus } = useConnectionStatus();
6 
7  return (
8    <div>
9      <p>Status: {connectionStatus}</p>
10      {callStatus === "ongoing" && <p>{callDuration}</p>}
11      <button 
12        onClick={() => call("+2348000000000")}
13        disabled={!isConnected || callStatus !== "idle"}
14      >
15        {callStatus === "idle" ? "Call" : "Calling..."}
16      </button>
17    </div>
18  );
19}

Built-in UI Components

We provide production-ready components that fit perfectly into your application. Below is a complete overview of the core components and their props.

Dialpad

A flexible keypad for entering numbers and switching between Caller IDs.

initialNumber?: stringPre-fill the dialer input.
showKeys?: booleanShow numeric keypad by default (true).
className?: stringCustom CSS classes.
availableExtensions?: ArrayOverride auto-fetched caller IDs.
selectedExtension?: stringManually select the active caller ID.
onExtensionChange?: fnCallback when caller ID changes.
onCallInitiated?: fnCallback after a call starts.
metadata?: RecordMetadata passed through to sdk.call().

CallInterface

A slide-over interface that handles the audio and call lifecycle automatically.

isOpen?: booleanControls visibility.
onOpenChange?: fnCallback to request open/close.
onCallEnded?: fnCallback when a call ends.
maximizeIcon?: NodeCustom maximize icon.
minimizeIcon?: NodeCustom minimize icon.
ringtoneUrl?: stringReserved for custom ringtone audio.
ringbackUrl?: stringReserved for custom ringback audio.
1import { useState } from "react";
2import { CallInterface, Dialpad, CreditBalance } from "@dora-cell/sdk-react";
3 
4function App() {
5  const [dialerOpen, setDialerOpen] = useState(false);
6 
7  return (
8    <>
9      <header>
10        <CreditBalance />
11      </header>
12      
13      {/* Handles all incoming and outgoing call UI */}
14      <CallInterface 
15        isOpen={dialerOpen} 
16        onOpenChange={setDialerOpen} 
17        onCallEnded={() => console.log('Call Ended')}
18      />
19      
20      <main>
21        <Dialpad 
22          initialNumber="+2348000000000"
23          showKeys={true}
24          metadata={{ source: "docs" }}
25          onCallInitiated={(num) => console.log('Calling', num)}
26        />
27      </main>
28    </>
29  );
30}

Component Previews

Dialpad Component

A full-featured dialer with Caller ID selection and interactive keys.

Credit balance:₦1,250.00
Caller ID
+234 800 123 4567
Enter number

Call Interface Component

Responsive floating interface for active and incoming call management.

JD

John Doe

+234 701 555 0123 • Incoming...

Incoming call
JD

John Doe

+234 701 555 0123 • On Call

Ongoing
04:22