Call Control SDK

A powerful, lightweight SDK for real-time call management

🔑AUTHORIZED ACCESS REQUIRED - API Key & Tenant ID🔑

⭐ License Features

• API Key Authentication - Secure access through authorized API keys
• Tenant ID Management - Multi-tenant support with isolated access
• Cross-Platform Support - Use across web, mobile, desktop, and server platforms
• Usage Monitoring - Real-time tracking and compliance monitoring
• Flexible Deployment - Deploy on authorized platforms with proper credentials

🚫 Prohibited Activities

• No Unauthorized Access - Cannot use without valid credentials
• No Credential Sharing - API keys and tenant IDs are confidential
• No Reverse Engineering - Cannot decompile or reverse engineer
• No Platform Violations - Must use only on authorized platforms
• No Usage Abuse - Cannot exceed subscription limits

📑 Table of Contents

• ✨ Key Features
• 📦 Installation
• 🚀 Quick Start
  • 1️⃣ Initialize the SDK
  • 2️⃣ Add Call Control Panel
  • 3️⃣ Use Call Management Hooks
• 🔧 Configuration Options
• 📚 API Reference
  • 🔧 Core Functions
  • 🪝 React Hooks
• 📦 Data Types
• 🎛 Control Features
• 🌍 Browser Support
• 📄 License

✨ Key Features

🎯 Complete Call Control

• Hold/Resume calls
• Mute/Unmute functionality
• Agent status management
• End call with disposition

💾 Smart State Management

• Real-time call timer
• Persistent state storage
• Singleton state pattern
• Cross-component sync
• TypeScript support

📦 Installation

npm install call-control-sdk

🔑 Required Dependencies

Make sure you have these peer dependencies installed:

npm install react react-dom axios @mui/material @mui/icons-material @emotion/react @emotion/styled

🚀 Quick Start

1️⃣ Initialize the SDK

First, initialize the SDK at the root of your application:

import { useEffect } from "react";
import { initSDK } from "call-control-sdk";

function App() {
	useEffect(() => {
		try {
			initSDK({
				apiKey: "your-api-key",
				tenantId: "your-tenant-id",
				agentId: "your-agent-id",
			});
			console.log("✅ SDK initialized successfully");
		} catch (error) {
			console.error("❌ SDK initialization failed:", error);
		}
	}, []);

	return <YourAppContent />;
}

2️⃣ Add Call Control Panel

Drop in the draggable call control panel anywhere in your app:

import { CallControlPanel } from "call-control-sdk";

export default function AgentDashboard() {
	const handleCallDataChange = (data) => {
		console.log("📞 Call data updated:", data);
		// Handle call data changes (mobileNumber, callReferenceId, agentLoginId)
	};

	return (
		<div>
			<h1>Agent Dashboard</h1>
			<CallControlPanel onDataChange={handleCallDataChange} />
		</div>
	);
}

📞 Get Caller Data (Alternative to onDataChange)

The useGetCallerData hook is an independent alternative to the CallControlPanel's onDataChange prop. It provides the same call data but can be used anywhere in your application without depending on the CallControlPanel component.

Key Differences:

• 🔄 onDataChange: Requires CallControlPanel component, callback-based
• 🎯 useGetCallerData: Independent hook, reactive, can be used anywhere

When to use each:

• Use onDataChange when you need the call control UI and want to handle data changes
• Use useGetCallerData when you only need call data without the control panel UI

The useGetCallerData hook provides reactive access to current call data. It automatically updates when call status changes, new calls arrive, or call information is modified.

import { useGetCallerData } from "call-control-sdk";

export default function AgentDashboard() {
	const callerData = useGetCallerData();

	// Sample data structure returned:
	// {
	//   "phone_number": "1234567890",
	//   "status": "ONCALL",
	//   "callReferenceId": "convox_call_id_123",
	//   "agent_id": "agent001",
	//   "process_id": "proc001",
	//   "process_name": "Sales Process"
	// }

	return (
		<div>
			<h1>Current Call Information</h1>
			<p>Phone Number: {callerData.phone_number}</p>
			<p>Call Status: {callerData.status}</p>
			<p>Call Reference ID: {callerData.callReferenceId}</p>
			<p>Agent ID: {callerData.agent_id}</p>
			<p>Process: {callerData.process_name}</p>
		</div>
	);
}

Example: Using useGetCallerData independently (without CallControlPanel)

import { useGetCallerData } from "call-control-sdk";

// This component can be used anywhere, even without CallControlPanel
export default function CallStatusWidget() {
	const callerData = useGetCallerData();

	return (
		<div className="call-status-widget">
			<h3>Current Call Status</h3>
			{callerData.status === "ONCALL" ?
				<div>
					<p>📞 Active Call: {callerData.phone_number}</p>
					<p>Agent: {callerData.agent_id}</p>
					<p>Process: {callerData.process_name}</p>
				</div>
			:	<p>No active call</p>}
		</div>
	);
}

// You can use this widget anywhere in your app
export default function MainApp() {
	return (
		<div>
			<h1>My Application</h1>
			<CallStatusWidget /> {/* Independent component */}
			{/* No CallControlPanel needed here */}
		</div>
	);
}

Key Features:

• ✅ Reactive Updates: Automatically re-renders when call data changes
• ✅ Real-time Data: Reflects current call state from WebSocket updates
• ✅ Type Safety: Fully typed with TypeScript interfaces
• ✅ Complete Data: Returns all available call information
• ✅ Independent: Works without CallControlPanel component

Returned Data Fields:

• phone_number: The phone number involved in the call
• status: Current call status (ONCALL, RINGING, WRAPUP, etc.)
• callReferenceId: Unique identifier for the call
• agent_id: ID of the agent handling the call
• process_id: Process identifier for the call
• process_name: Name of the process handling the call

3️⃣ Use Call Management Hooks

🔴 Start a Call

import { useClickToCall } from "call-control-sdk";

export default function CallButton() {
	const { handleStartCall, isLoading, isSuccess, isError, error } = useClickToCall();

	const startCall = () => {
		handleStartCall({
			mobileNumber: "1234567890",
		});
	};

	return (
		<button
			onClick={startCall}
			disabled={isLoading}
		>
			{isLoading ? "🔄 Calling..." : "📞 Start Call"}
		</button>
	);
}

🔚 End a Call

import { useEndCall } from "call-control-sdk";

export default function EndCallButton() {
	const { handleEndCall, isLoading, isSuccess, isError, error } = useEndCall();

	const endCall = () => {
		handleEndCall({
			disposition: "RES", // Call disposition
		});
	};

	return (
		<button
			onClick={endCall}
			disabled={isLoading}
		>
			{isLoading ? "🔄 Ending..." : "🔚 End Call"}
		</button>
	);
}

🚪 Agent Logout

import { useLogout } from "call-control-sdk";

export default function LogoutButton() {
	const { logout, isLoading, isSuccess, isError, error } = useLogout();

	return (
		<button
			onClick={logout}
			disabled={isLoading}
		>
			{isLoading ? "🔄 Logging out..." : "🚪 Logout"}
		</button>
	);
}

🔐 Authorization Token

get Authorization token for external API call

import { useGetAuthorizationToken } from "call-control-sdk";

export default function axios() {
	const token = useGetAuthorizationToken();

	console.log(token);
}

🔧 Configuration Options

Customize the SDK behavior to fit your needs:

initSDK({
	// Required configuration
	apiKey: "your-api-key",
	tenantId: "your-tenant-id",
	agentId: "your-agent-id",

	// Optional customization
	disableEndCallButton: false, // Hide end call button
	disabledDialButton: false, // Hide dial button
	disableCallTransferButton: false, // Hide transfer button
	disableConferenceButton: false, // Hide conference button
	disableSoftPhone: false, // Hide soft phone iframe
	isDraggable: true, // Enable/disable dragging

	// Custom styling (Material-UI SxProps)
	disabled: { opacity: 0.5 }, // Disabled button styles
	enabled: { color: "primary" }, // Enabled button styles
	outlined: { border: "1px solid" }, // Outlined button styles
});

🎨 Styling Options

| Option | Type | Default | Description | | --------------------------- | --------- | ------- | --------------------------------- | | disableEndCallButton | boolean | false | Hide the "End Call" button | | disabledDialButton | boolean | false | Hide the "Dial" button | | disableCallTransferButton | boolean | false | Hide the "Call Transfer" button | | disableConferenceButton | boolean | false | Hide the "Conference" button | | disableSoftPhone | boolean | false | Hide the embedded soft phone | | isDraggable | boolean | true | Enable/disable panel dragging | | disabled | SxProps | - | Custom styles for disabled states | | enabled | SxProps | - | Custom styles for enabled states | | outlined | SxProps | - | Custom styles for outlined states |

📚 API Reference

🔧 Core Functions

initSDK(config)

Initialize the SDK with your configuration. Must be called before using any components or hooks.

initSDK({
	apiKey: string, // ✅ Required - API key for authentication
	tenantId: string, // ✅ Required - Tenant ID for events/authentication
	agentId: string, // ✅ Required - Agent ID for call controls
	// ... plus optional configuration options
});

CallControlPanel

Draggable control panel component for call management.

<CallControlPanel
	onDataChange={(data) => {
		console.log("Call data updated:", data);
	}}
/>

🪝 React Hooks

useLogout()

Hook for agent logout functionality.

const { logout, isLoading, isSuccess, isError, error } = useLogout();

// Usage:
logout();

// Returns:
// - logout: () => void - Function to trigger logout
// - isLoading: boolean - Loading state
// - isSuccess: boolean - Success state
// - isError: boolean - Error state
// - error: any - Error object if failed

useClickToCall()

Hook for initiating calls to mobile numbers.

const { handleStartCall, isLoading, isSuccess, isError, error, data } = useClickToCall();

// Usage:
handleStartCall({ mobileNumber: "1234567890" });

// Returns:
// - handleStartCall: (payload: StartCallPayload) => void
// - isLoading: boolean - Loading state
// - isSuccess: boolean - Success state
// - isError: boolean - Error state
// - error: any - Error object if failed
// - data: any - API response on success

useEndCall()

Hook for ending active calls.

const { handleEndCall, isLoading, isSuccess, isError, error, data } = useEndCall();

// Usage:
handleEndCall({ disposition: "RES" });

// Returns:
// - handleEndCall: (payload: EndCallPayload) => void
// - isLoading: boolean - Loading state
// - isSuccess: boolean - Success state
// - isError: boolean - Error state
// - error: any - Error object if failed
// - data: any - API response on success

📦 Data Types

StartCallPayload

interface StartCallPayload {
	mobileNumber?: string; // Mobile number to call
}

EndCallPayload

interface EndCallPayload {
	disposition?: string; // Call disposition (default: "RES")
}

🎛 Control Features

📞 Call Management

• Hold/Resume - Pause and resume active calls
• Mute/Unmute - Control audio during calls
• End Call - Terminate calls with disposition tracking
• Agent Status - Switch between Idle/Break states

💾 State Persistence

• Call Timer - Real-time duration tracking
• Panel Position - Remembers draggable panel location
• Agent Status - Maintains current status across sessions
• Call State - Preserves hold/mute states

🌍 Browser Support

| Browser | Version | Status | | ----------------------------------------------------------------------------- | ------- | ------------ | | | 60+ | ✅ Supported | | | 60+ | ✅ Supported | | | 12+ | ✅ Supported | | | 79+ | ✅ Supported |

📄 License