@capgo/capacitor-twilio-voice 7.3.2 → 7.4.2

package/README.md

@@ -8,6 +8,10 @@
 
 A Capacitor plugin for integrating Twilio Voice calling functionality into iOS and Android applications.
 
+## Documentation
+
+The most complete doc is available here: https://capgo.app/docs/plugins/twilio-voice/
+
 ## Installation
 
 ```bash

package/android/src/main/java/ee/forgr/capacitor_twilio_voice/CapacitorTwilioVoicePlugin.java

@@ -2,6 +2,9 @@ package ee.forgr.capacitor_twilio_voice;
 
 import android.Manifest;
 import android.app.Activity;
+import android.app.AlertDialog;
+import android.app.KeyguardManager;
+import android.app.KeyguardManager;
 import android.app.NotificationChannel;
 import android.app.NotificationManager;
 import android.app.PendingIntent;
@@ -21,13 +24,18 @@ import android.os.Build;
 import android.os.IBinder;
 import android.os.VibrationEffect;
 import android.os.Vibrator;
+import android.provider.Settings;
 import android.util.Base64;
 import android.util.Log;
+import android.widget.Toast;
+import androidx.activity.result.ActivityResultLauncher;
+import androidx.activity.result.contract.ActivityResultContracts;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.core.app.ActivityCompat;
 import androidx.core.app.NotificationCompat;
 import androidx.core.app.NotificationManagerCompat;
+import androidx.core.content.ContextCompat;
 import com.getcapacitor.JSArray;
 import com.getcapacitor.JSObject;
 import com.getcapacitor.Plugin;
@@ -67,11 +75,13 @@ import org.json.JSONObject;
 )
 public class CapacitorTwilioVoicePlugin extends Plugin {
 
-    private final String PLUGIN_VERSION = "7.3.2";
+    private final String PLUGIN_VERSION = "7.4.2";
 
     private static final String TAG = "CapacitorTwilioVoice";
     private static final String PREF_ACCESS_TOKEN = "twilio_access_token";
     private static final String PREF_FCM_TOKEN = "twilio_fcm_token";
+    private static final String PREFS_NAME = "capacitor_twilio_voice_prefs";
+    private static final String PREF_MIC_PERMISSION_REQUESTED = "mic_permission_requested";
 
     public static CapacitorTwilioVoicePlugin instance;
 
@@ -103,6 +113,21 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
     private static final int REQUEST_CODE_RECORD_AUDIO_FOR_ACCEPT = 2001;
     private String pendingCallSidForPermission;
 
+    private enum PendingPermissionAction {
+        NONE,
+        OUTGOING_CALL,
+        ACCEPT_CALL
+    }
+
+    private PendingPermissionAction pendingPermissionAction = PendingPermissionAction.NONE;
+    private PluginCall pendingOutgoingCall;
+    private String pendingOutgoingTo;
+    private PluginCall pendingPermissionCall;
+    private long permissionRequestTimestamp = 0L;
+    private int permissionAttemptCount = 0;
+    private boolean awaitingSettingsResult = false;
+    private ActivityResultLauncher<String[]> micPermissionLauncher;
+
     // Voice Call Service
     private VoiceCallService voiceCallService;
     private boolean isServiceBound = false;
@@ -150,6 +175,7 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
                 data.put("error", error.getMessage());
             }
             notifyListeners("callDisconnected", data);
+            moveAppToBackgroundIfLocked();
         }
 
         @Override
@@ -240,6 +266,11 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
         bindToVoiceCallService();
 
         Log.d(TAG, "CapacitorTwilioVoice plugin loaded");
+
+        micPermissionLauncher = getBridge().registerForActivityResult(
+            new ActivityResultContracts.RequestMultiplePermissions(),
+            (permissions) -> handleMicPermissionResult(permissions)
+        );
     }
 
     private void bindToVoiceCallService() {
@@ -356,6 +387,44 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
         Log.d(TAG, "CapacitorTwilioVoice plugin destroyed");
     }
 
+    @Override
+    protected void handleOnResume() {
+        super.handleOnResume();
+        Log.d(
+            TAG,
+            "handleOnResume: hasPermission=" +
+                hasMicrophonePermission() +
+                ", awaitingSettings=" +
+                awaitingSettingsResult +
+                ", pendingCall=" +
+                (pendingPermissionCall != null) +
+                ", pendingAction=" +
+                pendingPermissionAction
+        );
+        if (hasMicrophonePermission()) {
+            if (pendingPermissionAction != PendingPermissionAction.NONE || pendingPermissionCall != null) {
+                awaitingSettingsResult = false;
+                Log.d(TAG, "handleOnResume: permission granted, resuming pending flow");
+                handleMicrophonePermissionGranted();
+            }
+        } else if (awaitingSettingsResult && pendingPermissionCall != null) {
+            awaitingSettingsResult = false;
+            Log.d(TAG, "handleOnResume: permission still denied after returning from settings");
+            JSObject ret = new JSObject();
+            ret.put("granted", false);
+            pendingPermissionCall.setKeepAlive(false);
+            pendingPermissionCall.resolve(ret);
+            pendingPermissionCall = null;
+        } else if (awaitingSettingsResult && pendingPermissionAction == PendingPermissionAction.ACCEPT_CALL) {
+            awaitingSettingsResult = false;
+            Log.d(TAG, "handleOnResume: settings return without permission for accept flow");
+            handlePermissionFailure();
+        } else if (pendingPermissionCall != null) {
+            Log.d(TAG, "handleOnResume: permission denied from dialog, invoking fallback handling");
+            handleMicrophonePermissionDenied();
+        }
+    }
+
     public void setInjectedContext(Context injectedContext) {
         this.injectedContext = injectedContext;
     }
@@ -388,33 +457,19 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
     }
 
     private void ensureMicPermissionThenAccept(String callSid) {
-        Context context = getSafeContext();
-        boolean granted =
-            ActivityCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED;
-        if (granted) {
+        Log.d(TAG, "ensureMicPermissionThenAccept: callSid=" + callSid);
+        if (hasMicrophonePermission()) {
+            Log.d(TAG, "ensureMicPermissionThenAccept: permission granted, proceeding");
             proceedAcceptCall(callSid);
             return;
         }
 
-        // Remember callSid and request via Activity runtime permission API
         pendingCallSidForPermission = callSid;
-        Activity activity = getActivity();
-        if (activity != null) {
-            ActivityCompat.requestPermissions(
-                activity,
-                new String[] { Manifest.permission.RECORD_AUDIO },
-                REQUEST_CODE_RECORD_AUDIO_FOR_ACCEPT
-            );
-        } else if (mainActivityClass != null) {
-            // No current activity; bring app to foreground where permission can be requested
-            Intent launchIntent = new Intent(context, mainActivityClass);
-            launchIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP);
-            launchIntent.putExtra("AUTO_ACCEPT_CALL", true);
-            launchIntent.putExtra(EXTRA_CALL_SID, callSid);
-            context.startActivity(launchIntent);
-        } else {
-            Log.w(TAG, "No activity available to request RECORD_AUDIO permission");
-        }
+        pendingPermissionAction = PendingPermissionAction.ACCEPT_CALL;
+        permissionAttemptCount = 0;
+        awaitingSettingsResult = false;
+        Log.d(TAG, "ensureMicPermissionThenAccept: requesting permission before accepting call");
+        requestMicrophonePermission();
     }
 
     // Helper to actually start the service once permission is granted
@@ -435,6 +490,12 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
             Log.d(TAG, "Call acceptance started via service (permission granted)");
         } catch (Exception e) {
             Log.e(TAG, "Error accepting call via service", e);
+        } finally {
+            pendingCallSidForPermission = null;
+            if (pendingPermissionAction == PendingPermissionAction.ACCEPT_CALL) {
+                pendingPermissionAction = PendingPermissionAction.NONE;
+            }
+            permissionAttemptCount = 0;
         }
     }
 
@@ -683,11 +744,32 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
             return;
         }
 
+        if (pendingOutgoingCall != null) {
+            pendingOutgoingCall.setKeepAlive(false);
+            pendingOutgoingCall.reject("Another call is awaiting microphone permission.");
+            clearOutgoingPermissionState();
+        }
+
         String to = call.getString("to");
         if (to == null) {
             to = ""; // Empty string for echo test
         }
 
+        if (hasMicrophonePermission()) {
+            startOutgoingCall(call, to);
+            return;
+        }
+
+        pendingOutgoingCall = call;
+        pendingOutgoingTo = to;
+        pendingPermissionAction = PendingPermissionAction.OUTGOING_CALL;
+        permissionAttemptCount = 0;
+        call.setKeepAlive(true);
+        requestMicrophonePermission();
+    }
+
+    private void startOutgoingCall(PluginCall call, String to) {
+        Log.d(TAG, "startOutgoingCall: to=" + to);
         // Start call via the foreground service
         Intent serviceIntent = new Intent(getSafeContext(), VoiceCallService.class);
         serviceIntent.setAction(VoiceCallService.ACTION_START_CALL);
@@ -700,11 +782,366 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
             JSObject ret = new JSObject();
             ret.put("success", true);
             ret.put("callSid", "pending"); // Will be updated when service connects
+            call.setKeepAlive(false);
             call.resolve(ret);
         } catch (Exception e) {
+            call.setKeepAlive(false);
             Log.e(TAG, "Error starting call service", e);
             call.reject("Failed to start call: " + e.getMessage());
+        } finally {
+            clearOutgoingPermissionState();
+        }
+    }
+
+    private boolean hasMicrophonePermission() {
+        return ContextCompat.checkSelfPermission(getSafeContext(), Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED;
+    }
+
+    private SharedPreferences getPrefs() {
+        return getSafeContext().getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+    }
+
+    private void requestMicrophonePermission() {
+        Activity activity = getActivity();
+        permissionRequestTimestamp = System.currentTimeMillis();
+        permissionAttemptCount++;
+
+        if (activity != null) {
+            activity.runOnUiThread(() -> {
+                Log.d(TAG, "requestMicrophonePermission: requesting RECORD_AUDIO (attempt " + permissionAttemptCount + ")");
+                if (micPermissionLauncher != null) {
+                    micPermissionLauncher.launch(new String[] { Manifest.permission.RECORD_AUDIO });
+                } else {
+                    ActivityCompat.requestPermissions(
+                        activity,
+                        new String[] { Manifest.permission.RECORD_AUDIO },
+                        REQUEST_CODE_RECORD_AUDIO_FOR_ACCEPT
+                    );
+                }
+            });
+            return;
+        }
+
+        if (mainActivityClass != null) {
+            Context context = getSafeContext();
+            Intent launchIntent = new Intent(context, mainActivityClass);
+            launchIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP);
+            if (pendingPermissionAction == PendingPermissionAction.ACCEPT_CALL && pendingCallSidForPermission != null) {
+                launchIntent.putExtra("AUTO_ACCEPT_CALL", true);
+                launchIntent.putExtra(EXTRA_CALL_SID, pendingCallSidForPermission);
+            }
+            Log.d(TAG, "requestMicrophonePermission: launching activity to request permission");
+            context.startActivity(launchIntent);
+        } else {
+            Log.w(TAG, "Unable to request microphone permission - no activity available");
+            handlePermissionFailure();
+        }
+    }
+
+    private void handleMicPermissionResult(Map<String, Boolean> permissions) {
+        Boolean granted = permissions.get(Manifest.permission.RECORD_AUDIO);
+        Log.d(TAG, "handleMicPermissionResult: granted=" + granted + ", pendingAction=" + pendingPermissionAction);
+        if (granted != null && granted) {
+            handleMicrophonePermissionGranted();
+        } else {
+            handleMicrophonePermissionDenied();
+        }
+    }
+
+    private void handleMicrophonePermissionGranted() {
+        Log.d(
+            TAG,
+            "handleMicrophonePermissionGranted: pendingAction=" +
+                pendingPermissionAction +
+                ", pendingCall=" +
+                (pendingPermissionCall != null)
+        );
+        permissionAttemptCount = 0;
+
+        if (pendingPermissionAction == PendingPermissionAction.OUTGOING_CALL && pendingOutgoingCall != null) {
+            PluginCall call = pendingOutgoingCall;
+            String to = pendingOutgoingTo != null ? pendingOutgoingTo : "";
+            pendingOutgoingCall = null;
+            pendingOutgoingTo = null;
+            pendingPermissionAction = PendingPermissionAction.NONE;
+            startOutgoingCall(call, to);
+            return;
+        }
+
+        if (pendingPermissionAction == PendingPermissionAction.ACCEPT_CALL) {
+            if (pendingCallSidForPermission != null) {
+                String callSid = pendingCallSidForPermission;
+                pendingCallSidForPermission = null;
+                pendingPermissionAction = PendingPermissionAction.NONE;
+                proceedAcceptCall(callSid);
+                return;
+            }
+
+            pendingPermissionAction = PendingPermissionAction.NONE;
+            awaitingSettingsResult = false;
+            permissionAttemptCount = 0;
+            return;
+        }
+
+        if (pendingPermissionCall != null) {
+            JSObject ret = new JSObject();
+            ret.put("granted", true);
+            pendingPermissionCall.setKeepAlive(false);
+            pendingPermissionCall.resolve(ret);
+            pendingPermissionCall = null;
+            awaitingSettingsResult = false;
+        }
+
+        pendingPermissionAction = PendingPermissionAction.NONE;
+    }
+
+    private void handleMicrophonePermissionDenied() {
+        Log.d(TAG, "handleMicrophonePermissionDenied invoked");
+        Activity activity = getActivity();
+        if (activity == null) {
+            Log.w(TAG, "handleMicrophonePermissionDenied: no activity");
+            handlePermissionFailure();
+            return;
+        }
+
+        boolean canRequestAgain = ActivityCompat.shouldShowRequestPermissionRationale(activity, Manifest.permission.RECORD_AUDIO);
+        Log.d(
+            TAG,
+            "handleMicrophonePermissionDenied: canRequestAgain=" +
+                canRequestAgain +
+                ", attempt=" +
+                permissionAttemptCount +
+                ", pendingAction=" +
+                pendingPermissionAction +
+                ", standaloneCall=" +
+                (pendingPermissionCall != null)
+        );
+
+        if (pendingPermissionAction == PendingPermissionAction.NONE && pendingPermissionCall != null) {
+            if (canRequestAgain && permissionAttemptCount <= 1) {
+                showStandalonePermissionRationaleDialog(activity, pendingPermissionCall);
+            } else {
+                showStandalonePermissionSettingsDialog(activity, pendingPermissionCall);
+            }
+        } else if (canRequestAgain && permissionAttemptCount <= 1) {
+            showPermissionRationaleDialog(activity);
+        } else {
+            showPermissionSettingsDialog(activity);
+        }
+    }
+
+    private void showPermissionRationaleDialog(Activity activity) {
+        Log.d(TAG, "showPermissionRationaleDialog");
+        new AlertDialog.Builder(activity)
+            .setTitle("Microphone required")
+            .setMessage("Microphone access is required to place and receive calls.")
+            .setPositiveButton("Retry", (dialog, which) -> {
+                dialog.dismiss();
+                requestMicrophonePermission();
+            })
+            .setNegativeButton("Cancel", (dialog, which) -> {
+                dialog.dismiss();
+                handlePermissionFailure();
+            })
+            .setCancelable(false)
+            .show();
+    }
+
+    private void showStandalonePermissionRationaleDialog(Activity activity, PluginCall call) {
+        Log.d(TAG, "showStandalonePermissionRationaleDialog");
+        new AlertDialog.Builder(activity)
+            .setTitle("Microphone required")
+            .setMessage("Microphone access is required to place and receive calls.")
+            .setPositiveButton("Retry", (dialog, which) -> {
+                dialog.dismiss();
+                requestMicrophonePermission();
+            })
+            .setNegativeButton("Cancel", (dialog, which) -> {
+                dialog.dismiss();
+                JSObject ret = new JSObject();
+                ret.put("granted", false);
+                call.setKeepAlive(false);
+                call.resolve(ret);
+                pendingPermissionCall = null;
+                awaitingSettingsResult = false;
+                permissionAttemptCount = 0;
+            })
+            .setCancelable(false)
+            .show();
+    }
+
+    private void showPermissionSettingsDialog(Activity activity) {
+        Log.d(TAG, "showPermissionSettingsDialog");
+        new AlertDialog.Builder(activity)
+            .setTitle("Enable microphone")
+            .setMessage("You can enable the microphone in Settings to use calling features.")
+            .setPositiveButton("Open Settings", (dialog, which) -> {
+                dialog.dismiss();
+                ensureUnlockedThenOpenSettings();
+            })
+            .setNegativeButton("Cancel", (dialog, which) -> {
+                dialog.dismiss();
+                handlePermissionFailure();
+            })
+            .setCancelable(false)
+            .show();
+    }
+
+    private void showStandalonePermissionSettingsDialog(Activity activity, PluginCall call) {
+        Log.d(TAG, "showStandalonePermissionSettingsDialog");
+        new AlertDialog.Builder(activity)
+            .setTitle("Enable microphone")
+            .setMessage("Microphone access is required. Open Settings to enable the permission.")
+            .setPositiveButton("Open Settings", (dialog, which) -> {
+                dialog.dismiss();
+                pendingPermissionCall = call;
+                call.setKeepAlive(true);
+                awaitingSettingsResult = true;
+                ensureUnlockedThenOpenSettings();
+            })
+            .setNegativeButton("Cancel", (dialog, which) -> {
+                dialog.dismiss();
+                JSObject ret = new JSObject();
+                ret.put("granted", false);
+                call.setKeepAlive(false);
+                call.resolve(ret);
+                pendingPermissionCall = null;
+                awaitingSettingsResult = false;
+                permissionAttemptCount = 0;
+            })
+            .setCancelable(false)
+            .show();
+    }
+
+    private void openAppSettings() {
+        Context context = getSafeContext();
+        if (pendingPermissionCall != null || pendingPermissionAction != PendingPermissionAction.NONE) {
+            awaitingSettingsResult = true;
+        }
+        Log.d(
+            TAG,
+            "openAppSettings: awaitingSettingsResult=" +
+                awaitingSettingsResult +
+                ", pendingAction=" +
+                pendingPermissionAction +
+                ", pendingCall=" +
+                (pendingPermissionCall != null)
+        );
+        Intent intent = new Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
+        intent.setData(Uri.fromParts("package", context.getPackageName(), null));
+        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+        context.startActivity(intent);
+        Toast.makeText(context, "Enable microphone permission and return to the app", Toast.LENGTH_LONG).show();
+    }
+
+    private boolean isDeviceLocked() {
+        KeyguardManager km = (KeyguardManager) getSafeContext().getSystemService(Context.KEYGUARD_SERVICE);
+        return km != null && km.isKeyguardLocked();
+    }
+
+    private void ensureUnlockedThenOpenSettings() {
+        Activity activity = getActivity();
+        if (activity == null) {
+            Log.w(TAG, "ensureUnlockedThenOpenSettings: no activity available");
+            openAppSettings();
+            return;
+        }
+
+        KeyguardManager km = (KeyguardManager) getSafeContext().getSystemService(Context.KEYGUARD_SERVICE);
+        if (km == null || !km.isKeyguardLocked()) {
+            openAppSettings();
+            return;
+        }
+
+        km.requestDismissKeyguard(
+            activity,
+            new KeyguardManager.KeyguardDismissCallback() {
+                @Override
+                public void onDismissSucceeded() {
+                    Log.d(TAG, "Keyguard dismissed, opening settings");
+                    openAppSettings();
+                }
+
+                @Override
+                public void onDismissCancelled() {
+                    Log.d(TAG, "Keyguard dismissal cancelled");
+                }
+
+                @Override
+                public void onDismissError() {
+                    Log.w(TAG, "Keyguard dismissal error");
+                }
+            }
+        );
+    }
+
+    private void moveAppToBackgroundIfLocked() {
+        Activity activity = getActivity();
+        if (activity != null && isDeviceLocked()) {
+            Log.d(TAG, "moveAppToBackgroundIfLocked: moving task to back");
+            activity.moveTaskToBack(true);
+        }
+    }
+
+    private void handlePermissionFailure() {
+        Log.d(
+            TAG,
+            "handlePermissionFailure: pendingAction=" + pendingPermissionAction + ", pendingCall=" + (pendingPermissionCall != null)
+        );
+        if (pendingPermissionAction == PendingPermissionAction.OUTGOING_CALL) {
+            if (pendingOutgoingCall != null) {
+                pendingOutgoingCall.setKeepAlive(false);
+                pendingOutgoingCall.reject("Microphone permission is required to place a call.");
+            }
+            clearOutgoingPermissionState();
+        } else if (pendingPermissionAction == PendingPermissionAction.ACCEPT_CALL) {
+            if (pendingCallSidForPermission != null) {
+                CallInvite invite = activeCallInvites.get(pendingCallSidForPermission);
+                if (invite != null) {
+                    dismissIncomingCallNotification();
+                    activeCallInvites.remove(pendingCallSidForPermission);
+                    try {
+                        invite.reject(getSafeContext());
+                    } catch (Exception ex) {
+                        Log.w(TAG, "handlePermissionFailure: failed to reject invite", ex);
+                    }
+                }
+                JSObject data = new JSObject();
+                data.put("callSid", pendingCallSidForPermission);
+                data.put("reason", "microphone_permission_denied");
+                if (invite != null) {
+                    if (invite.getFrom() != null) {
+                        data.put("from", invite.getFrom().replace("client:", ""));
+                    }
+                    if (invite.getTo() != null) {
+                        data.put("to", invite.getTo());
+                    }
+                }
+                notifyListeners("callDisconnected", data);
+            }
+            pendingCallSidForPermission = null;
+            pendingPermissionAction = PendingPermissionAction.NONE;
+            awaitingSettingsResult = false;
+            pendingPermissionCall = null;
+            moveAppToBackgroundIfLocked();
+        } else if (pendingPermissionCall != null) {
+            JSObject ret = new JSObject();
+            ret.put("granted", false);
+            pendingPermissionCall.setKeepAlive(false);
+            pendingPermissionCall.resolve(ret);
+            pendingPermissionCall = null;
+            awaitingSettingsResult = false;
         }
+        permissionAttemptCount = 0;
+    }
+
+    private void clearOutgoingPermissionState() {
+        pendingOutgoingCall = null;
+        pendingOutgoingTo = null;
+        if (pendingPermissionAction == PendingPermissionAction.OUTGOING_CALL) {
+            pendingPermissionAction = PendingPermissionAction.NONE;
+        }
+        permissionAttemptCount = 0;
     }
 
     // Call parameter creation is now handled by VoiceCallService
@@ -754,6 +1191,7 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
         JSObject ret = new JSObject();
         ret.put("success", true);
         call.resolve(ret);
+        moveAppToBackgroundIfLocked();
     }
 
     @PluginMethod
@@ -847,25 +1285,82 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
 
     @PluginMethod
     public void requestMicrophonePermission(PluginCall call) {
-        requestPermissions(call);
+        Log.d(TAG, "requestMicrophonePermission invoked");
+        if (hasMicrophonePermission()) {
+            Log.d(TAG, "requestMicrophonePermission: already granted");
+            JSObject ret = new JSObject();
+            ret.put("granted", true);
+            call.resolve(ret);
+            return;
+        }
+
+        Activity activity = getActivity();
+        if (activity == null) {
+            Log.w(TAG, "requestMicrophonePermission: no activity available");
+            call.reject("Unable to request permission without an active activity");
+            return;
+        }
+
+        SharedPreferences prefs = getPrefs();
+        boolean requestedBefore = prefs.getBoolean(PREF_MIC_PERMISSION_REQUESTED, false);
+        boolean shouldShow = ActivityCompat.shouldShowRequestPermissionRationale(activity, Manifest.permission.RECORD_AUDIO);
+        Log.d(
+            TAG,
+            "requestMicrophonePermission: requestedBefore=" +
+                requestedBefore +
+                ", shouldShow=" +
+                shouldShow +
+                ", pendingAction=" +
+                pendingPermissionAction
+        );
+
+        if (pendingPermissionAction == PendingPermissionAction.NONE && !shouldShow && requestedBefore) {
+            showStandalonePermissionSettingsDialog(activity, call);
+            return;
+        }
+
+        prefs.edit().putBoolean(PREF_MIC_PERMISSION_REQUESTED, true).apply();
+
+        if (pendingPermissionAction == PendingPermissionAction.NONE) {
+            pendingPermissionCall = call;
+            call.setKeepAlive(true);
+        }
+        awaitingSettingsResult = false;
+        permissionAttemptCount++;
+        permissionRequestTimestamp = System.currentTimeMillis();
+        Log.d(TAG, "requestMicrophonePermission: invoking ActivityCompat.requestPermissions (attempt " + permissionAttemptCount + ")");
+
+        ActivityCompat.requestPermissions(
+            activity,
+            new String[] { Manifest.permission.RECORD_AUDIO },
+            REQUEST_CODE_RECORD_AUDIO_FOR_ACCEPT
+        );
     }
 
     @Override
     protected void handleRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
         super.handleRequestPermissionsResult(requestCode, permissions, grantResults);
 
-        // If we were waiting to accept a call after mic permission
-        if (pendingCallSidForPermission != null) {
-            boolean granted =
-                ActivityCompat.checkSelfPermission(getSafeContext(), Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED;
-            String callSid = pendingCallSidForPermission;
-            pendingCallSidForPermission = null;
-            if (granted) {
-                Log.d(TAG, "RECORD_AUDIO granted from permission flow; proceeding to accept call");
-                proceedAcceptCall(callSid);
-            } else {
-                Log.w(TAG, "RECORD_AUDIO denied; cannot accept call");
-            }
+        if (requestCode != REQUEST_CODE_RECORD_AUDIO_FOR_ACCEPT) {
+            return;
+        }
+
+        boolean granted = hasMicrophonePermission();
+        Log.d(
+            TAG,
+            "handleRequestPermissionsResult: granted=" +
+                granted +
+                ", attempt=" +
+                permissionAttemptCount +
+                ", pendingAction=" +
+                pendingPermissionAction +
+                ", standaloneCall=" +
+                (pendingPermissionCall != null)
+        );
+        if (granted) {
+            handleMicrophonePermissionGranted();
+        } else {
+            handleMicrophonePermissionDenied();
         }
     }
 
@@ -1085,13 +1580,8 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
         }
     };*/
 
-    private void showIncomingCallNotification(CallInvite callInvite, String callSid) {
+    private void showIncomingCallNotification(CallInvite callInvite, String callSid, String callerName) {
         try {
-            String callerName = callInvite.getFrom();
-            if (callerName != null && callerName.startsWith("client:")) {
-                callerName = callerName.substring(7); // Remove "client:" prefix
-            }
-
             // Create intent for accepting the call
             PendingIntent acceptPendingIntent;
             if (this.bridge == null) {
@@ -1208,16 +1698,22 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
         String callSid = UUID.randomUUID().toString(); // Generate a unique ID
         activeCallInvites.put(callSid, callInvite);
 
+        Map<String, String> params = callInvite.getCustomParameters();
+        String callerName = params.containsKey("CapacitorTwilioCallerName")
+            ? params.get("CapacitorTwilioCallerName")
+            : callInvite.getFrom();
+
         // Create and show notification
-        showIncomingCallNotification(callInvite, callSid);
+        showIncomingCallNotification(callInvite, callSid, callerName);
 
         // Start ringtone and vibration
         startRingtone();
 
         JSObject data = new JSObject();
         data.put("callSid", callSid);
-        data.put("from", callInvite.getFrom());
+        data.put("from", callerName);
         data.put("to", callInvite.getTo());
+        data.put("customParams", new JSONObject(params));
         notifyListeners("callInviteReceived", data);
     }
 
@@ -1278,6 +1774,7 @@ public class CapacitorTwilioVoicePlugin extends Plugin {
             notifyListeners("callDisconnected", data);
 
             Log.d(TAG, "Call rejected from notification");
+            moveAppToBackgroundIfLocked();
         } else {
             Log.e(TAG, "Call invite not found for SID: " + callSid);
         }

package/dist/docs.json

@@ -169,7 +169,7 @@
       },
       {
         "name": "addListener",
-        "signature": "(eventName: 'callInviteReceived', listenerFunc: (data: { callSid: string; from: string; to: string; }) => void) => Promise<PluginListenerHandle>",
+        "signature": "(eventName: 'callInviteReceived', listenerFunc: (data: { callSid: string; from: string; to: string; customParams: Record<string, string>; }) => void) => Promise<PluginListenerHandle>",
         "parameters": [
           {
             "name": "eventName",
@@ -179,14 +179,15 @@
           {
             "name": "listenerFunc",
             "docs": "",
-            "type": "(data: { callSid: string; from: string; to: string; }) => void"
+            "type": "(data: { callSid: string; from: string; to: string; customParams: Record<string, string>; }) => void"
           }
         ],
         "returns": "Promise<PluginListenerHandle>",
         "tags": [],
         "docs": "",
         "complexTypes": [
-          "PluginListenerHandle"
+          "PluginListenerHandle",
+          "Record"
         ],
         "slug": "addlistenercallinvitereceived-"
       },
@@ -213,6 +214,75 @@
         ],
         "slug": "addlistenercallconnected-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'callInviteCancelled', listenerFunc: (data: { callSid: string; reason: 'user_declined' | 'remote_cancelled'; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'callInviteCancelled'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(data: { callSid: string; reason: 'user_declined' | 'remote_cancelled'; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [
+          "PluginListenerHandle"
+        ],
+        "slug": "addlistenercallinvitecancelled-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'outgoingCallInitiated', listenerFunc: (data: { callSid: string; to: string; source: 'app' | 'system'; displayName?: string; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'outgoingCallInitiated'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(data: { callSid: string; to: string; source: 'app' | 'system'; displayName?: string | undefined; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [
+          "PluginListenerHandle"
+        ],
+        "slug": "addlisteneroutgoingcallinitiated-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'outgoingCallFailed', listenerFunc: (data: { callSid: string; to: string; reason: 'missing_access_token' | 'connection_failed' | 'no_call_details' | 'microphone_permission_denied' | 'invalid_contact' | 'callkit_request_failed' | 'unsupported_intent'; displayName?: string; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'outgoingCallFailed'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(data: { callSid: string; to: string; reason: 'missing_access_token' | 'connection_failed' | 'no_call_details' | 'microphone_permission_denied' | 'invalid_contact' | 'callkit_request_failed' | 'unsupported_intent'; displayName?: string | undefined; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [
+          "PluginListenerHandle"
+        ],
+        "slug": "addlisteneroutgoingcallfailed-"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'callDisconnected', listenerFunc: (data: { callSid: string; error?: string; }) => void) => Promise<PluginListenerHandle>",
@@ -425,6 +495,21 @@
     }
   ],
   "enums": [],
-  "typeAliases": [],
+  "typeAliases": [
+    {
+      "name": "Record",
+      "slug": "record",
+      "docs": "Construct a type with a set of properties K of type T",
+      "types": [
+        {
+          "text": "{\r\n    [P in K]: T;\r\n}",
+          "complexTypes": [
+            "K",
+            "T"
+          ]
+        }
+      ]
+    }
+  ],
   "pluginConfigs": []
 }

package/dist/esm/definitions.d.ts

@@ -61,10 +61,27 @@ export interface CapacitorTwilioVoicePlugin {
         callSid: string;
         from: string;
         to: string;
+        customParams: Record<string, string>;
     }) => void): Promise<PluginListenerHandle>;
     addListener(eventName: 'callConnected', listenerFunc: (data: {
         callSid: string;
     }) => void): Promise<PluginListenerHandle>;
+    addListener(eventName: 'callInviteCancelled', listenerFunc: (data: {
+        callSid: string;
+        reason: 'user_declined' | 'remote_cancelled';
+    }) => void): Promise<PluginListenerHandle>;
+    addListener(eventName: 'outgoingCallInitiated', listenerFunc: (data: {
+        callSid: string;
+        to: string;
+        source: 'app' | 'system';
+        displayName?: string;
+    }) => void): Promise<PluginListenerHandle>;
+    addListener(eventName: 'outgoingCallFailed', listenerFunc: (data: {
+        callSid: string;
+        to: string;
+        reason: 'missing_access_token' | 'connection_failed' | 'no_call_details' | 'microphone_permission_denied' | 'invalid_contact' | 'callkit_request_failed' | 'unsupported_intent';
+        displayName?: string;
+    }) => void): Promise<PluginListenerHandle>;
     addListener(eventName: 'callDisconnected', listenerFunc: (data: {
         callSid: string;
         error?: string;

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface CapacitorTwilioVoicePlugin {\n  // Authentication\n  login(options: { accessToken: string }): Promise<{ success: boolean }>;\n  logout(): Promise<{ success: boolean }>;\n  isLoggedIn(): Promise<{ isLoggedIn: boolean; hasValidToken: boolean; identity?: string }>;\n\n  // Call Management\n  makeCall(options: { to: string }): Promise<{ success: boolean; callSid?: string }>;\n  acceptCall(options: { callSid: string }): Promise<{ success: boolean }>;\n  rejectCall(options: { callSid: string }): Promise<{ success: boolean }>;\n  endCall(options: { callSid?: string }): Promise<{ success: boolean }>;\n\n  // Call Controls\n  muteCall(options: { muted: boolean; callSid?: string }): Promise<{ success: boolean }>;\n  setSpeaker(options: { enabled: boolean }): Promise<{ success: boolean }>;\n\n  // Call Status\n  getCallStatus(): Promise<{\n    hasActiveCall: boolean;\n    isOnHold: boolean;\n    isMuted: boolean;\n    callSid?: string;\n    callState?: string;\n  }>;\n\n  // Audio Permissions\n  checkMicrophonePermission(): Promise<{ granted: boolean }>;\n  requestMicrophonePermission(): Promise<{ granted: boolean }>;\n\n  // Listeners for events\n  addListener(\n    eventName: 'callInviteReceived',\n    listenerFunc: (data: { callSid: string; from: string; to: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callConnected',\n    listenerFunc: (data: { callSid: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callDisconnected',\n    listenerFunc: (data: { callSid: string; error?: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callRinging',\n    listenerFunc: (data: { callSid: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callReconnecting',\n    listenerFunc: (data: { callSid: string; error?: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callReconnected',\n    listenerFunc: (data: { callSid: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callQualityWarningsChanged',\n    listenerFunc: (data: { callSid: string; currentWarnings: string[]; previousWarnings: string[] }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(eventName: 'registrationSuccess', listenerFunc: () => void): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'registrationFailure',\n    listenerFunc: (data: { error: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ version: string }>} a Promise with version for this plugin\n   * @throws An error if something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n\nexport interface PluginListenerHandle {\n  remove(): Promise<void>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface CapacitorTwilioVoicePlugin {\n  // Authentication\n  login(options: { accessToken: string }): Promise<{ success: boolean }>;\n  logout(): Promise<{ success: boolean }>;\n  isLoggedIn(): Promise<{ isLoggedIn: boolean; hasValidToken: boolean; identity?: string }>;\n\n  // Call Management\n  makeCall(options: { to: string }): Promise<{ success: boolean; callSid?: string }>;\n  acceptCall(options: { callSid: string }): Promise<{ success: boolean }>;\n  rejectCall(options: { callSid: string }): Promise<{ success: boolean }>;\n  endCall(options: { callSid?: string }): Promise<{ success: boolean }>;\n\n  // Call Controls\n  muteCall(options: { muted: boolean; callSid?: string }): Promise<{ success: boolean }>;\n  setSpeaker(options: { enabled: boolean }): Promise<{ success: boolean }>;\n\n  // Call Status\n  getCallStatus(): Promise<{\n    hasActiveCall: boolean;\n    isOnHold: boolean;\n    isMuted: boolean;\n    callSid?: string;\n    callState?: string;\n  }>;\n\n  // Audio Permissions\n  checkMicrophonePermission(): Promise<{ granted: boolean }>;\n  requestMicrophonePermission(): Promise<{ granted: boolean }>;\n\n  // Listeners for events\n  addListener(\n    eventName: 'callInviteReceived',\n    listenerFunc: (data: { callSid: string; from: string; to: string; customParams: Record<string, string> }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callConnected',\n    listenerFunc: (data: { callSid: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callInviteCancelled',\n    listenerFunc: (data: { callSid: string; reason: 'user_declined' | 'remote_cancelled' }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'outgoingCallInitiated',\n    listenerFunc: (data: { callSid: string; to: string; source: 'app' | 'system'; displayName?: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'outgoingCallFailed',\n    listenerFunc: (data: {\n      callSid: string;\n      to: string;\n      reason:\n        | 'missing_access_token'\n        | 'connection_failed'\n        | 'no_call_details'\n        | 'microphone_permission_denied'\n        | 'invalid_contact'\n        | 'callkit_request_failed'\n        | 'unsupported_intent';\n      displayName?: string;\n    }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callDisconnected',\n    listenerFunc: (data: { callSid: string; error?: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callRinging',\n    listenerFunc: (data: { callSid: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callReconnecting',\n    listenerFunc: (data: { callSid: string; error?: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callReconnected',\n    listenerFunc: (data: { callSid: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'callQualityWarningsChanged',\n    listenerFunc: (data: { callSid: string; currentWarnings: string[]; previousWarnings: string[] }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  addListener(eventName: 'registrationSuccess', listenerFunc: () => void): Promise<PluginListenerHandle>;\n\n  addListener(\n    eventName: 'registrationFailure',\n    listenerFunc: (data: { error: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ version: string }>} a Promise with version for this plugin\n   * @throws An error if something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n\nexport interface PluginListenerHandle {\n  remove(): Promise<void>;\n}\n"]}

package/ios/Sources/CapacitorTwilioVoicePlugin/CapacitorTwilioVoicePlugin.swift

@@ -4,6 +4,7 @@ import PushKit
 import CallKit
 import TwilioVoice
 import AVFoundation
+import Intents
 
 let kRegistrationTTLInDays = 365
 let kCachedDeviceToken = "CachedDeviceToken"
@@ -26,7 +27,7 @@ public protocol PushKitEventDelegate: AnyObject {
  */
 @objc(CapacitorTwilioVoicePlugin)
 public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEventDelegate {
-    private let PLUGIN_VERSION: String = "7.3.2"
+    private let PLUGIN_VERSION: String = "7.4.2"
 
     public let identifier = "CapacitorTwilioVoicePlugin"
     public let jsName = "CapacitorTwilioVoice"
@@ -60,6 +61,13 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
     private var callKitCompletionCallback: ((Bool) -> Void)?
     private var playCustomRingback = false
     private var ringtonePlayer: AVAudioPlayer?
+    private struct PendingOutgoingCall {
+        let to: String
+        let completion: (Bool) -> Void
+        let isSystemInitiated: Bool
+        let displayName: String?
+    }
+    private var pendingOutgoingCalls: [UUID: PendingOutgoingCall] = [:]
 
     deinit {
         // Remove observers
@@ -93,6 +101,8 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
         let configuration = CXProviderConfiguration(localizedName: "Voice Call")
         configuration.maximumCallGroups = 2
         configuration.maximumCallsPerCallGroup = 1
+        configuration.supportedHandleTypes = [.generic, .phoneNumber]
+        configuration.includesCallsInRecents = true
         callKitProvider = CXProvider(configuration: configuration)
         if let provider = callKitProvider {
             provider.setDelegate(self, queue: nil)
@@ -374,13 +384,74 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
             }
 
             let uuid = UUID()
-            self?.performStartCallAction(uuid: uuid, handle: to, to: to) { success in
-                if success {
-                    call.resolve(["success": true, "callSid": uuid.uuidString])
-                } else {
-                    call.reject("Failed to start call")
-                }
+            self?.performStartCallAction(uuid: uuid,
+                                         handle: to,
+                                         to: to,
+                                         isSystemInitiated: false,
+                                         completion: { success in
+                                            if success {
+                                                call.resolve(["success": true, "callSid": uuid.uuidString])
+                                            } else {
+                                                call.reject("Failed to start call")
+                                            }
+                                         })
+        }
+    }
+
+    @available(iOS 10.0, *)
+    public func handleStartCallIntent(intent: INIntent) {
+        if #available(iOS 13.0, *), let callIntent = intent as? INStartCallIntent {
+            processStartCallIntent(contact: callIntent.contacts?.first,
+                                   intentType: "INStartCallIntent")
+            return
+        }
+
+        if let audioIntent = intent as? INStartAudioCallIntent {
+            processStartCallIntent(contact: audioIntent.contacts?.first,
+                                   intentType: "INStartAudioCallIntent")
+            return
+        }
+
+        NSLog("Unsupported call intent type: \(type(of: intent))")
+        emitOutgoingCallFailed(to: "", displayName: nil, reason: "unsupported_intent")
+    }
+
+    @available(iOS 10.0, *)
+    private func processStartCallIntent(contact: INPerson?, intentType: String) {
+        guard let contact = contact else {
+            NSLog("\(intentType) received without contact information")
+            emitOutgoingCallFailed(to: "", displayName: nil, reason: "invalid_contact")
+            return
+        }
+
+        guard let handleValue = contact.personHandle?.value, !handleValue.isEmpty else {
+            let displayName = resolveDisplayName(from: contact)
+            NSLog("\(intentType) contact missing handle value")
+            emitOutgoingCallFailed(to: displayName ?? "", displayName: displayName, reason: "invalid_contact")
+            return
+        }
+
+        let displayName = resolveDisplayName(from: contact)
+        NSLog("Processing \(intentType) for handle: \(handleValue)")
+
+        checkRecordPermission { [weak self] permissionGranted in
+            guard let self = self else { return }
+
+            guard permissionGranted else {
+                NSLog("Microphone permission denied while processing \(intentType)")
+                self.emitOutgoingCallFailed(to: handleValue,
+                                            displayName: displayName,
+                                            reason: "microphone_permission_denied")
+                return
             }
+
+            NSLog("Initiating CallKit start call action for intent target: \(handleValue)")
+            self.performStartCallAction(uuid: UUID(),
+                                        handle: handleValue,
+                                        to: handleValue,
+                                        isSystemInitiated: true,
+                                        displayName: displayName,
+                                        completion: { _ in })
         }
     }
 
@@ -572,6 +643,44 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
         }
     }
 
+    private func emitOutgoingCallFailed(uuid: UUID = UUID(),
+                                        to: String,
+                                        displayName: String?,
+                                        reason: String) {
+        var data: [String: Any] = [
+            "callSid": uuid.uuidString,
+            "to": to,
+            "reason": reason
+        ]
+
+        if let displayName = displayName {
+            data["displayName"] = displayName
+        }
+
+        DispatchQueue.main.async { [weak self] in
+            self?.notifyListeners("outgoingCallFailed", data: data)
+        }
+    }
+
+    @available(iOS 10.0, *)
+    private func resolveDisplayName(from contact: INPerson) -> String? {
+        if !contact.displayName.isEmpty {
+            return contact.displayName
+        }
+
+        let displayName = contact.displayName
+
+        if let nameComponents = contact.nameComponents {
+            let formatter = PersonNameComponentsFormatter()
+            let formattedName = formatter.string(from: nameComponents)
+            if !formattedName.isEmpty {
+                return formattedName
+            }
+        }
+
+        return contact.personHandle?.value
+    }
+
     private func toggleAudioRoute(toSpeaker: Bool) {
         audioDevice.block = {
             do {
@@ -700,12 +809,22 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
 
     // MARK: - CallKit Actions
 
-    private func performStartCallAction(uuid: UUID, handle: String, to: String, completion: @escaping (Bool) -> Void) {
+    private func performStartCallAction(uuid: UUID,
+                                        handle: String,
+                                        to: String,
+                                        isSystemInitiated: Bool,
+                                        displayName: String? = nil,
+                                        completion: @escaping (Bool) -> Void) {
         guard let provider = callKitProvider else {
             completion(false)
             return
         }
 
+        pendingOutgoingCalls[uuid] = PendingOutgoingCall(to: to,
+                                                         completion: completion,
+                                                         isSystemInitiated: isSystemInitiated,
+                                                         displayName: displayName)
+
         let callHandle = CXHandle(type: .generic, value: handle)
         let startCallAction = CXStartCallAction(call: uuid, handle: callHandle)
         let transaction = CXTransaction(action: startCallAction)
@@ -713,7 +832,13 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
         callKitCallController.request(transaction) { [weak self] error in
             if let error = error {
                 NSLog("StartCallAction transaction request failed: \(error.localizedDescription)")
+                self?.pendingOutgoingCalls.removeValue(forKey: uuid)
                 completion(false)
+
+                self?.emitOutgoingCallFailed(uuid: uuid,
+                                             to: to,
+                                             displayName: displayName,
+                                             reason: "callkit_request_failed")
                 return
             }
 
@@ -726,12 +851,10 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
             callUpdate.hasVideo = false
 
             provider.reportCall(with: uuid, updated: callUpdate)
-
-            self?.performVoiceCall(uuid: uuid, to: to, completionHandler: completion)
         }
     }
 
-    private func reportIncomingCall(from: String, uuid: UUID) {
+    private func reportIncomingCall(from: String, niceName: String, uuid: UUID) {
         guard let provider = callKitProvider else { return }
 
         let callHandle = CXHandle(type: .generic, value: from)
@@ -743,6 +866,7 @@ public class CapacitorTwilioVoicePlugin: CAPPlugin, CAPBridgedPlugin, PushKitEve
         callUpdate.supportsGrouping = false
         callUpdate.supportsUngrouping = false
         callUpdate.hasVideo = false
+        callUpdate.localizedCallerName = niceName
 
         provider.reportNewIncomingCall(with: uuid, update: callUpdate) { error in
             if let error = error {
@@ -838,13 +962,15 @@ extension CapacitorTwilioVoicePlugin: NotificationDelegate {
         UserDefaults.standard.set(Date(), forKey: kCachedBindingDate)
 
         let from = (callInvite.from ?? "Unknown").replacingOccurrences(of: "client:", with: "")
-        reportIncomingCall(from: from, uuid: callInvite.uuid)
+        let niceName = callInvite.customParameters?["CapacitorTwilioCallerName"] ?? from
+        reportIncomingCall(from: from, niceName: niceName, uuid: callInvite.uuid)
         activeCallInvites[callInvite.uuid.uuidString] = callInvite
 
         notifyListeners("callInviteReceived", data: [
             "callSid": callInvite.uuid.uuidString,
             "from": from,
-            "to": callInvite.to ?? ""
+            "to": callInvite.to,
+            "customParams": callInvite.customParameters ?? [:]
         ])
     }
 
@@ -858,6 +984,11 @@ extension CapacitorTwilioVoicePlugin: NotificationDelegate {
         if let callInvite = callInvite {
             performEndCallAction(uuid: callInvite.uuid)
             activeCallInvites.removeValue(forKey: callInvite.uuid.uuidString)
+
+            notifyListeners("callInviteCancelled", data: [
+                "callSid": callInvite.uuid.uuidString,
+                "reason": "remote_cancelled"
+            ])
         }
     }
 }
@@ -986,7 +1117,69 @@ extension CapacitorTwilioVoicePlugin: CXProviderDelegate {
     }
 
     public func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
-        provider.reportOutgoingCall(with: action.callUUID, startedConnectingAt: Date())
+        let uuid = action.callUUID
+        let handleValue = action.handle.value
+
+        var pendingCall = pendingOutgoingCalls[uuid]
+        if pendingCall == nil {
+            let fallback = PendingOutgoingCall(to: handleValue,
+                                               completion: { _ in },
+                                               isSystemInitiated: true,
+                                               displayName: nil)
+            pendingOutgoingCalls[uuid] = fallback
+            pendingCall = fallback
+        }
+
+        guard let callDetails = pendingCall else {
+            provider.reportCall(with: uuid, endedAt: Date(), reason: .failed)
+            emitOutgoingCallFailed(uuid: uuid,
+                                   to: handleValue,
+                                   displayName: nil,
+                                   reason: "no_call_details")
+            action.fail()
+            return
+        }
+
+        let to = callDetails.to
+        let source = callDetails.isSystemInitiated ? "system" : "app"
+
+        var initiatedData: [String: Any] = [
+            "callSid": uuid.uuidString,
+            "to": to,
+            "source": source
+        ]
+
+        if let displayName = callDetails.displayName {
+            initiatedData["displayName"] = displayName
+        }
+
+        notifyListeners("outgoingCallInitiated", data: initiatedData)
+
+        guard let accessToken = accessToken, isTokenValid(accessToken) else {
+            pendingOutgoingCalls.removeValue(forKey: uuid)
+            provider.reportCall(with: uuid, endedAt: Date(), reason: .failed)
+            callDetails.completion(false)
+            emitOutgoingCallFailed(uuid: uuid,
+                                   to: to,
+                                   displayName: callDetails.displayName,
+                                   reason: "missing_access_token")
+            action.fail()
+            return
+        }
+
+        provider.reportOutgoingCall(with: uuid, startedConnectingAt: Date())
+
+        performVoiceCall(uuid: uuid, to: to) { [weak self] success in
+            callDetails.completion(success)
+            if !success {
+                self?.emitOutgoingCallFailed(uuid: uuid,
+                                             to: to,
+                                             displayName: callDetails.displayName,
+                                             reason: "connection_failed")
+            }
+        }
+
+        pendingOutgoingCalls.removeValue(forKey: uuid)
         action.fulfill()
     }
 
@@ -1001,6 +1194,11 @@ extension CapacitorTwilioVoicePlugin: CXProviderDelegate {
         if let invite = activeCallInvites[action.callUUID.uuidString] {
             invite.reject()
             activeCallInvites.removeValue(forKey: action.callUUID.uuidString)
+
+            notifyListeners("callInviteCancelled", data: [
+                "callSid": action.callUUID.uuidString,
+                "reason": "user_declined"
+            ])
         } else if let call = activeCalls[action.callUUID.uuidString] {
             call.disconnect()
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-twilio-voice",
-  "version": "7.3.2",
+  "version": "7.4.2",
   "description": "Integrates the Twilio Voice SDK into Capacitor",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",