How to Show the Native Incoming Call Screen for VoIP Calls in Flutter Apps (iOS CallKit + Android ConnectionService)

# pubspec.yaml — add to dependencies
dependencies:
  flutter:
    sdk: flutter

  flutter_callkit_incoming: ^2.0.1    # latest stable

  firebase_core: ^3.0.0               # for FCM on Android

  firebase_messaging: ^15.0.0          # FCM data messages

  uuid: ^4.0.0                         # for generating call UUIDs

<!— Add inside the root <dict> —>

<key>UIBackgroundModes</key>
<array>
  <string>voip</string>
  <string>remote-notification</string>
  <string>processing</string>
</array>

import UIKit
import Flutter
import PushKit
import CallKit
import flutter_callkit_incoming

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate, PKPushRegistryDelegate,
                            CallkitIncomingAppDelegate {

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) → Bool {
    GeneratedPluginRegistrant.register(with: self)

    // Register for VoIP push notifications via PushKit
    let mainQueue = DispatchQueue.main
    let voipRegistry = PKPushRegistry(queue: mainQueue)
    voipRegistry.delegate = self
    voipRegistry.desiredPushTypes = [PKPushType.voIP]

    return super.application(application,
                didFinishLaunchingWithOptions: launchOptions)
  }

  // Called when PushKit delivers a new VoIP token
  func pushRegistry(_ registry: PKPushRegistry,
                  didUpdate credentials: PKPushCredentials,
                  for type: PKPushType) {
    let deviceToken = credentials.token
                      .map { String(format: "%02x", $0) }
                      .joined()
    // Send this token to your server — it's what you push to
    SwiftFlutterCallkitIncomingPlugin.sharedInstance?
      .setDevicePushTokenVoIP(deviceToken)
  }

  // ⚠️ iOS 13+ CRITICAL: Called when VoIP push arrives — app may be killed
  func pushRegistry(_ registry: PKPushRegistry,
                  didReceiveIncomingPushWith payload: PKPushPayload,
                  for type: PKPushType,
                  withCompletionHandler completion: @escaping () → Void) {
    let dict = payload.dictionaryPayload

    // Extract call data from push payload
    var data = flutter_callkit_incoming.Data(
      id: dict["uuid"] as? String ?? UUID().uuidString,
      nameCaller: dict["caller_name"] as? String ?? "Unknown",
      handle: dict["caller_number"] as? String ?? "",
      type: 0  // 0 = audio, 1 = video
    )
    data.appName = "WasaaChat"
    data.avatar = dict["caller_avatar"] as? String

    // MUST call this BEFORE completion() — iOS 13+ requirement
    SwiftFlutterCallkitIncomingPlugin.sharedInstance?
      .showCallkitIncoming(data, fromPushKit: true)

    // Completion can be called after (small delay is acceptable)
    DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) {
      completion()
    }
  }
}

// After creating the Data object, set the ringtone name (without .caf)
data.ringtoneSound = "custom_ring"  // looks for custom_ring.caf in bundle

// If ringtoneSound is nil or not found, iOS uses the system default ring

<!— Permissions required for VoIP call screen —>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL"/>
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>

<!— Inside <application> tag — register the plugin service —>
<service
  android:name="com.hiennv.flutter_callkit_incoming.CallkitIncomingService"
  android:exported="false"
  android:foregroundServiceType="phoneCall"/>

import 'package:permission_handler/permission_handler.dart';

// Android 14+ requires explicit permission for full-screen intents
Future<void> requestCallPermissions() async {
  if (Platform.isAndroid) {
    await [
      Permission.phone,
      Permission.microphone,
      Permission.notification,
    ].request();
  }
}

import 'dart:io';
import 'package:flutter_callkit_incoming/flutter_callkit_incoming.dart';
import 'package:uuid/uuid.dart';

class VoIPService {
  static final Uuid _uuid = const Uuid();

  /// Call this from main() or your FCM background message handler
  static Future<void> showIncomingCall({
    required String callerName,
    required String callerNumber,
    String? callerAvatar,
    String? callUuid,
    bool isVideo = false,
  }) async {
    final uuid = callUuid ?? _uuid.v4();

    final params = CallKitParams(
      id: uuid,
      nameCaller: callerName,
      handle: callerNumber,
      avatar: callerAvatar,
      type: isVideo ? 1 : 0,    // 0 = audio, 1 = video
      textAccept: 'Accept',
      textDecline: 'Decline',
      duration: 30000,           // 30 seconds ring timeout

      // Missed call notification (shown if user doesn't answer)
      missedCallNotification: const NotificationParams(
        showNotification: true,
        isShowCallback: true,
        subtitle: 'Missed call',
        callbackText: 'Call back',
      ),

      // Android-specific params
      android: const AndroidParams(
        isCustomNotification: true,
        isShowLogo: false,
        ringtonePath: 'system_ringtone_default', // or 'custom_ring' from res/raw/
        backgroundColor: '#0a0e1e',
        actionColor: '#6d28d9',
        textColor: '#ffffff',
        incomingCallNotificationChannelName: 'Incoming Call',
      ),

      // iOS-specific params
      ios: const IOSParams(
        iconTemplateImageAssetName: 'CallKitLogo',  // 40x40 asset catalog
        handleType: 'generic',
        supportsVideo: true,
        maximumCallGroups: 2,
        maximumCallsPerCallGroup: 1,
        ringtonePath: 'custom_ring',   // .caf file without extension
      ),
    );

    await FlutterCallkitIncoming.showCallkitIncoming(params);
  }

  /// Dismiss the call screen (e.g., when remote hangs up)
  static Future<void> endCall(String uuid) async {
    await FlutterCallkitIncoming.endCall(uuid);
  }

  static void listenForEvents({
    required Function(String uuid) onAccept,
    required Function(String uuid) onDecline,
    required Function(String uuid) onEnded,
  }) {
    FlutterCallkitIncoming.onEvent.listen((event) {
      final uuid = event?.body['id'] as String? ?? '';
      switch (event!.event) {
        case Event.actionCallAccept:
          onAccept(uuid);         // User tapped green button
          break;
        case Event.actionCallDecline:
          onDecline(uuid);        // User tapped red button
          break;
        case Event.actionCallEnded:
          onEnded(uuid);          // Call ended or timed out
          break;
        default:
          break;
      }
    });
  }
}

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter_callkit_incoming/flutter_callkit_incoming.dart';

// ⚠️ Must be a TOP-LEVEL function (not inside a class)
// This runs in a SEPARATE ISOLATE when the app is killed
@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  // data message from server triggers this even when app is killed
  if (message.data['type'] == 'incoming_call') {
    await VoIPService.showIncomingCall(
      callerName: message.data['caller_name'] ?? 'Unknown',
      callerNumber: message.data['caller_number'] ?? '',
      callerAvatar: message.data['caller_avatar'],
      callUuid: message.data['uuid'],
      isVideo: message.data['is_video'] == 'true',
    );
  }
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // Register background handler BEFORE runApp
  FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);

  // Also listen for foreground messages
  FirebaseMessaging.onMessage.listen((message) {
    if (message.data['type'] == 'incoming_call') {
      VoIPService.showIncomingCall(
        callerName: message.data['caller_name'] ?? 'Unknown',
        callerNumber: message.data['caller_number'] ?? '',
        callUuid: message.data['uuid'],
      );
    }
  });

  runApp(const MyApp());
}

{
  "to": "<FCM_DEVICE_TOKEN>",
  // ⚠️ No "notification" key — data-only wakes killed app
  "data": {
    "type": "incoming_call",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "caller_name": "Alex Morgan",
    "caller_number": "+1234567890",
    "caller_avatar": "https://example.com/avatar.jpg",
    "is_video": "false"
  },
  "priority": "high",           // CRITICAL — must be high for background
  "android": {
    "priority": "high"
  }
}

// Using @parse/node-apn or similar library
const notification = new apn.Notification();
notification.topic = `com.yourapp.voip`;   // .voip suffix for PushKit
notification.pushType = "voip";              // PushKit push type
notification.priority = 10;                 // Immediate delivery
notification.expiry = Math.floor(Date.now() / 1000) + 30;
notification.payload = {
  uuid: "550e8400-e29b-41d4-a716-446655440000",
  caller_name: "Alex Morgan",
  caller_number: "+1234567890",
  caller_avatar: "https://example.com/avatar.jpg",
};
// Must use VoIP certificate, NOT standard APNs push cert

class HomeScreen extends StatefulWidget {
  @override
  void initState() {
    super.initState();

    // Listen for call events from both platforms
    VoIPService.listenForEvents(
      onAccept: (uuid) {
        // User tapped Accept — connect your WebRTC session
        context.read<CallBloc>().add(AcceptCall(uuid: uuid));
        Navigator.pushNamed(context, '/call-screen',
          arguments: {'uuid': uuid});
      },
      onDecline: (uuid) {
        // User tapped Decline — send reject signal to server
        context.read<CallBloc>().add(RejectCall(uuid: uuid));
      },
      onEnded: (uuid) {
        // Call timed out or was dismissed — clean up
        context.read<CallBloc>().add(EndCall(uuid: uuid));
      },
    );

    // Check if app was launched from a call notification (killed state)
    _checkForActiveCallOnLaunch();
  }
}

Future<void> _checkForActiveCallOnLaunch() async {
  // Get any call that was waiting when app was killed
  final calls = await FlutterCallkitIncoming.activeCalls();
  if (calls.isNotEmpty) {
    final activeCall = calls.first;
    // Navigate to in-call screen or re-show incoming screen
  }
}