rns-nativecall

A professional VoIP incoming call handler for React Native. Features a "Single Call Gate" on Android to manage busy states and full CallKit integration for iOS.

🚀 Highlights

• Expo Support: Built-in config plugin handles all native setup.
• Single Call Gate: Automatically detects if the user is in a call and flags secondary calls as "BUSY".
• Headless Mode: Works even when the app is killed or the screen is locked.

📦 Installation

npx expo install rns-nativecall expo-build-properties

or

npm install rns-nativecall expo-build-properties

Add the plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "enableProguardInReleaseBuilds": true,
            "extraProguardRules": "-keep class com.rnsnativecall.** { *; }\n-keep class com.facebook.react.HeadlessJsTaskService { *; }"
          }
        },
        "rns-nativecall"
      ]
    ]
  }
}

🛠 Usage

1. Initialize Headless Task (index.js) Register the task at the very top of your entry file. This handles background calls and "Busy" signals for secondary callers.

import { AppRegistry } from 'react-native';
import App from './App';
import { CallHandler } from 'rns-nativecall';

CallHandler.registerHeadlessTask(async (data, eventType) => {
    if (eventType === 'BUSY') {
        // User is already on a call. Notify the second caller via WebSocket/API.
        console.log("System Busy for UUID:", data.callUuid);
        return;
    }

    if (eventType === 'INCOMING_CALL') {
        // App is waking up for a new call. 
        // Trigger your custom UI or logic here.
    }
});

AppRegistry.registerComponent('main', () => App);

Handling Events (Index.js)

// Index.js Setup Foreground Listeners
CallHandler.subscribe(

    async (data) => {
        try {
            console.log("APP IS OPEN", data)
           // navigate here
        } catch (error) {
            console.log("pending_call_uuid", error)
        }
    },

    async (data) => {
        try {
            console.log("CALL DECLINE", data)
           // update the caller here call decline
        } catch (error) {
            console.log("Onreject/ cancel call error", error)
        }
    },

    (data) => { console.log("failded", data) }
);

Handling Events (App.js)

import React, { useEffect } from 'react';
import { CallHandler } from 'rns-nativecall';

export default function App() {
  useEffect(() => {
    const unsubscribe = CallHandler.subscribe(
      (data) => {
        console.log("Call Accepted:", data.callUuid);
        // Navigate to your call screen
      },
      (data) => {
        console.log("Call Rejected:", data.callUuid);
        // Send 'Hangup' signal to your server
      }
    );

    return () => unsubscribe();
  }, []);

  // To manually trigger the UI (e.g., from an FCM data message)
  const showCall = () => {
    CallHandler.displayCall("unique-uuid", "Caller Name", "video");
  };

  return <YourUI />;
}

📖 API Reference

rns-nativecall API Reference

| Method | Platform | Description | | :--- | :--- | :--- | | registerHeadlessTask(callback) | Android | Registers background logic. eventType is INCOMING_CALL or BUSY. | | checkOverlayPermission() | Android | Returns true if the app can draw over other apps (Required for Android Lockscreen). | | requestOverlayPermission() | Android | Opens System Settings to let the user enable "Draw over other apps". | | displayCall(uuid, name, type) | All | Shows the native call UI (Standard Notification on Android / CallKit on iOS). | | checkCallValidity(uuid) | All | Returns boolean values for isValid and isCanceled. | | stopForegroundService() | Android | Stops the ongoing service and clears the persistent notification/pill. | | destroyNativeCallUI(uuid) | All | Dismisses the native call interface and stops the ringtone. | | getInitialCallData() | All | Returns call data if the app was launched by clicking Answer from a killed state. | | subscribe(onAccept, onReject) | All | Listens for native button presses (Answer/End). |

Implementation Notes

1. Android Persistence: Because this library uses a Foreground Service on Android, the notification will persist and show a "Call Pill" in the status bar. To remove this after the call ends or connects, you MUST call 'CallHandler.stopForegroundService()'.

2. Android Overlay: For your React Native call screen to show up when the phone is locked, the user must grant the "Overlay Permission". Use 'checkOverlayPermission()' and 'requestOverlayPermission()' during your app's onboarding or call initiation.

3. iOS CallKit: On iOS, 'displayCall' uses the native system CallKit UI. This works automatically in the background and on the lockscreen without extra overlay permissions.

4. Single Call Gate: The library automatically prevents multiple overlapping native UIs. If a call is already active, subsequent calls will trigger the 'BUSY' event in your Headless Task.

FULL Example Use Case

import React, { useEffect, useState } from 'react';
import { StyleSheet, Text, View, TouchableOpacity, Alert } from 'react-native';
import { CallHandler } from 'rns-nativecall';

export default function App() {
  const [activeCall, setActiveCall] = useState(null);

  useEffect(() => {
    // 1. Handle app launched from a notification "Answer" click
    CallHandler.getInitialCallData().then((data) => {
      if (data && data.default) {
        console.log("App launched from call:", data.default);
        setActiveCall(data.default);
      }
    });

    // 2. Subscribe to foreground events
    const unsubscribe = CallHandler.subscribe(
      (data) => {
        console.log("Call Accepted:", data.callUuid);
        setActiveCall(data);
        // Logic: Open your Video/Audio Call UI here
      },
      (data) => {
        console.log("Call Rejected/Ended:", data.callUuid);
        setActiveCall(null);
      }
    );

    return () => unsubscribe();
  }, []);

  const startTestCall = async () => {
    // Android Only: Check for overlay permission to show UI over lockscreen
    const hasPermission = await CallHandler.checkOverlayPermission();
    if (!hasPermission) {
      Alert.alert(
        "Permission Required",
        "Please enable 'Draw over other apps' to see calls while the phone is locked.",
        [
          { text: "Cancel" },
          { text: "Settings", onPress: () => CallHandler.requestOverlayPermission() }
        ]
      );
      return;
    }

    // Trigger the native UI
    CallHandler.displayCall(
      "test-uuid-" + Date.now(),
      "John Doe",
      "video"
    );
  };

  const endCallManually = () => {
    if (activeCall) {
      CallHandler.stopForegroundService();
      setActiveCall(null);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>RNS Native Call Pro</Text>
      
      {activeCall ? (
        <View style={styles.callBox}>
          <Text>Active Call with: {activeCall.name}</Text>
          <TouchableOpacity style={styles.btnEnd} onPress={endCallManually}>
            <Text style={styles.btnText}>End Call</Text>
          </TouchableOpacity>
        </View>
      ) : (
        <TouchableOpacity style={styles.btnStart} onPress={startTestCall}>
          <Text style={styles.btnText}>Simulate Incoming Call</Text>
        </TouchableOpacity>
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#F5FCFF' },
  title: { fontSize: 20, fontWeight: 'bold', marginBottom: 20 },
  callBox: { padding: 20, backgroundColor: '#e1f5fe', borderRadius: 10, alignItems: 'center' },
  btnStart: { backgroundColor: '#4CAF50', padding: 15, borderRadius: 5 },
  btnEnd: { backgroundColor: '#F44336', padding: 15, borderRadius: 5, marginTop: 10 },
  btnText: { color: 'white', fontWeight: 'bold' }
});

🛡 License