@telnyx/react-voice-commons-sdk 0.4.3 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # CHANGELOG.md
 
+## Unreleased
+
+## [1.1.0] (2026-08-07)
+
+### Enhancement
+
+- Add and persist opt-in `pushWhenActive` support so push routing remains available when an active WebSocket connection would otherwise be prioritized.
+- Add Android `incomingCallRingtone` configuration. Apps can provide the name of an audio resource bundled in `android/app/src/main/res/raw`; the setting is retained for incoming FCM calls.
+- Add iOS call-waiting support, including UUID-targeted answer, end, hold, resume, and `swapCalls(targetCallId)` operations for two simultaneous CallKit calls.
+- Expose the explicitly selected active call through the public client API and re-emit call collections when a tracked call changes state.
+- Forward custom SIP headers supplied to `newCall()` in the React Native SDK's expected format.
+- Add Android push-notification fallbacks when call notifications are unavailable, and declare the required foreground-service type for active calls.
+- Add documentation for `pushWhenActive`, answered-elsewhere handling, Trickle ICE, and Android custom incoming ringtones.
+
+### Bug Fixing
+
+- Play and loop the Android incoming-call ringtone until the call is answered, rejected, ended, or dismissed. The SDK falls back to the device's selected phone ringtone when no valid app resource is configured.
+- Preserve iOS CallKit answers that occur before React Native listeners attach during a VoIP-push cold launch, including the case where the app omits a PushKit token while the native token is already available.
+- Prevent stale CallKit callbacks and subscription leaks after React re-renders or the active call changes.
+- Handle repeated holds, call swaps, rejected pushes, malformed PushKit payloads, Focus/DND-filtered CallKit registrations, and a second incoming call without leaving ghost calls or stuck foreground flags.
+- Harden session teardown and reconnection by serializing disposal, cancelling pending connection work, and waiting for socket cleanup before continuing.
+- Clear stale fallback push actions and keep incoming-call handling available when notifications are disabled.
+
 ## [0.4.3] (2026-04-30)
 
 ### Bug Fixing

package/README.md

@@ -79,7 +79,7 @@ const voipClient = createTelnyxVoipClient({
 
 // If you need to tear down and recreate the client (e.g., on logout):
 import { destroyTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
-destroyTelnyxVoipClient(); // Disposes the singleton; next createTelnyxVoipClient() call creates a fresh instance
+await destroyTelnyxVoipClient(); // Disposes the singleton; next createTelnyxVoipClient() call creates a fresh instance
 ```
 
 **Configuration Options Explained:**
@@ -120,14 +120,16 @@ call.callState$.subscribe((state) => {
 
 As of **v0.3.0**, the SDK no longer navigates the host app. Routing on state transitions (e.g. redirecting to a login screen on disconnect, surfacing an in-call screen when a call arrives via push) is entirely the host app's responsibility. Subscribe to the observables below and invoke your own navigator.
 
+> In the snippets below, `voipClient` is the instance returned by `createTelnyxVoipClient()` (see [Basic Setup](#basic-setup)). It is a singleton, so it's safe to reference the same module-level value from any component, or to read it from context.
+
 **What to observe:**
 
-| Observable                    | Emits                                                                                        | Use it for                                                                                                                                                                        |
-| ----------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `voipClient.connectionState$` | `TelnyxConnectionState` (`CONNECTING`, `CONNECTED`, `RECONNECTING`, `DISCONNECTED`, `ERROR`) | Redirect to login on `DISCONNECTED`; gate outbound-call UI on `CONNECTED`. There is no separate `loginState$` — `CONNECTED` means the socket is up **and** authenticated.         |
-| `voipClient.activeCall$`      | `Call \| null`                                                                               | Navigate to your in-call screen when a call appears. Primary signal for push-launched cold starts — when the SDK finishes the push-driven login and the call arrives, this emits. |
-| `voipClient.calls$`           | `Call[]`                                                                                     | Multi-call UIs (call waiting, conference).                                                                                                                                        |
-| `call.callState$`             | `TelnyxCallState`                                                                            | Per-call transitions (ringing / active / held / ended).                                                                                                                           |
+| Observable                    | Emits                                                                                        | Use it for                                                                                                                                                                |
+| ----------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `voipClient.connectionState$` | `TelnyxConnectionState` (`CONNECTING`, `CONNECTED`, `RECONNECTING`, `DISCONNECTED`, `ERROR`) | Redirect to login on `DISCONNECTED`; gate outbound-call UI on `CONNECTED`. There is no separate `loginState$` — `CONNECTED` means the socket is up **and** authenticated. |
+| `voipClient.activeCall$`      | `Call \| null`                                                                               | Emits the `Call` once the SDK has processed the push and the call has arrived. Navigate to your in-call screen here. Fires for push-launched, foreground, and outbound.   |
+| `voipClient.calls$`           | `Call[]`                                                                                     | Multi-call UIs (call waiting, conference).                                                                                                                                |
+| `call.callState$`             | `TelnyxCallState`                                                                            | Per-call transitions (ringing / active / held / ended).                                                                                                                   |
 
 #### Redirect to login on disconnect
 
@@ -173,6 +175,8 @@ useEffect(() => {
 
 #### Optional: gate outbound-call UI on CONNECTED
 
+`canMakeCalls(state)` is a small helper that returns `true` only when `state === TelnyxConnectionState.CONNECTED`. It exists purely to keep the check readable — you can inline the comparison if you prefer.
+
 ```tsx
 import { canMakeCalls } from '@telnyx/react-voice-commons-sdk';
 
@@ -270,6 +274,7 @@ import { createCredentialConfig } from '@telnyx/react-voice-commons-sdk';
 const config = createCredentialConfig('your_sip_username', 'your_sip_password', {
   debug: true,
   pushNotificationDeviceToken: 'your_device_token',
+  pushWhenActive: true,
 });
 
 await voipClient.login(config);
@@ -283,11 +288,26 @@ import { createTokenConfig } from '@telnyx/react-voice-commons-sdk';
 const config = createTokenConfig('your_jwt_token', {
   debug: true,
   pushNotificationDeviceToken: 'your_device_token',
+  pushWhenActive: true,
 });
 
 await voipClient.loginWithToken(config);
 ```
 
+`pushWhenActive` is opt-in and defaults to `false`. Enable it on iOS when the device must receive a second PushKit call while another call is active or held.
+
+### Android Incoming Ringtone
+
+Android uses the device's selected phone ringtone by default. To use an app-bundled sound instead, add a supported audio file such as `my_ringtone.wav` to `android/app/src/main/res/raw/` and pass its resource name without the extension when logging in:
+
+```tsx
+const config = createCredentialConfig('your_sip_username', 'your_sip_password', {
+  incomingCallRingtone: 'my_ringtone',
+});
+```
+
+The SDK persists this setting for incoming FCM pushes. If the resource is missing or the option is omitted, it falls back to the device ringtone.
+
 ### Automatic Storage & Reconnection
 
 The library automatically stores authentication data securely for seamless reconnection. **You don't need to manually manage these storage keys** - the library handles everything internally.
@@ -300,6 +320,7 @@ The library uses these AsyncStorage keys internally:
 - `@telnyx_password` - SIP password (credential auth)
 - `@credential_token` - JWT authentication token (token auth)
 - `@push_token` - Push notification device token
+- `@push_when_active` - Whether the device remains eligible for PushKit calls while connected
 
 **Note**: These are managed automatically by the library. You only need to call `login()` once, and the library will handle storage and future reconnections.
 

package/android/src/main/java/com/telnyx/react_voice_commons/CallForegroundService.kt

@@ -2,6 +2,8 @@ package com.telnyx.react_voice_commons
 
 import android.app.Service
 import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.os.Build
 import android.os.IBinder
 import android.util.Log
 
@@ -18,6 +20,10 @@ class CallForegroundService : Service() {
         const val EXTRA_CALLER_NAME = "caller_name"
         const val EXTRA_CALLER_NUMBER = "caller_number"
         const val EXTRA_CALL_ID = "call_id"
+
+        private val callForegroundServiceType =
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL or
+                ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
     }
 
     override fun onBind(intent: Intent?): IBinder? {
@@ -51,7 +57,15 @@ class CallForegroundService : Service() {
             val notification = notificationHelper.createOngoingCallNotification(callerName, callerNumber, callId)
             
             // Start foreground service with the notification
-            startForeground(TelnyxNotificationHelper.ONGOING_CALL_NOTIFICATION_ID, notification)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                startForeground(
+                    TelnyxNotificationHelper.ONGOING_CALL_NOTIFICATION_ID,
+                    notification,
+                    callForegroundServiceType
+                )
+            } else {
+                startForeground(TelnyxNotificationHelper.ONGOING_CALL_NOTIFICATION_ID, notification)
+            }
             
             Log.d(TAG, "Foreground service started with ongoing call notification")
         } catch (e: Exception) {
@@ -80,4 +94,4 @@ class CallForegroundService : Service() {
         super.onDestroy()
         Log.d(TAG, "CallForegroundService destroyed")
     }
-}
+}

package/android/src/main/java/com/telnyx/react_voice_commons/TelnyxFirebaseMessagingService.kt

@@ -1,5 +1,6 @@
 package com.telnyx.react_voice_commons
 
+import android.content.Intent
 import android.util.Log
 import com.google.firebase.messaging.FirebaseMessagingService
 import com.google.firebase.messaging.RemoteMessage
@@ -86,7 +87,20 @@ open class TelnyxFirebaseMessagingService : FirebaseMessagingService() {
             
             // Show missed call notification (this will hide any existing incoming call notification)
             val notificationHelper = TelnyxNotificationHelper(this)
-            notificationHelper.showMissedCallNotification(callerName, callerNumber, callId)
+            notificationHelper.hideIncomingCallNotification()
+            notificationHelper.hideOngoingCallNotification()
+
+            try {
+                stopService(Intent(this, CallForegroundService::class.java))
+            } catch (e: Exception) {
+                Log.e(tag, "Failed to stop CallForegroundService for missed call", e)
+            }
+
+            if (VoicePnManager.getMissedCallNotificationsEnabled(this)) {
+                notificationHelper.showMissedCallNotification(callerName, callerNumber, callId)
+            } else {
+                Log.d(tag, "Missed call notification display disabled")
+            }
             
             Log.d(tag, "Telnyx missed call notification processed successfully")
         } catch (e: Exception) {
@@ -176,4 +190,4 @@ open class TelnyxFirebaseMessagingService : FirebaseMessagingService() {
     protected open fun handleTokenRefresh(token: String) {
         Log.d(tag, "Default token refresh handler - override this method if needed")
     }
-}
+}

package/android/src/main/java/com/telnyx/react_voice_commons/TelnyxNotificationHelper.kt

@@ -1,26 +1,190 @@
 package com.telnyx.react_voice_commons
 
+import android.Manifest
+import android.annotation.SuppressLint
+import android.app.ActivityOptions
 import android.app.Notification
 import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.app.PendingIntent
 import android.content.Context
 import android.content.Intent
-import android.os.Build
-import androidx.core.app.NotificationCompat
+import android.content.pm.PackageManager
 import android.graphics.Color
+import android.media.AudioAttributes
+import android.media.AudioManager
+import android.media.MediaPlayer
+import android.media.Ringtone
+import android.media.RingtoneManager
+import android.net.Uri
+import android.os.Build
 import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
 
 /**
  * Helper class for managing Telnyx voice call notifications
  */
 class TelnyxNotificationHelper(private val context: Context) {
     companion object {
-        const val CHANNEL_ID = "telnyx_voice_calls"
-        const val CHANNEL_NAME = "Telnyx Voice Calls"
+        private const val INCOMING_CALL_CHANNEL_PREFIX = "telnyx_voice_incoming_calls_v3"
+        const val ONGOING_CALL_CHANNEL_ID = "telnyx_voice_ongoing_calls"
+        const val MISSED_CALL_CHANNEL_ID = "telnyx_voice_missed_calls"
+        const val INCOMING_CALL_CHANNEL_NAME = "Incoming Telnyx Voice Calls"
+        const val ONGOING_CALL_CHANNEL_NAME = "Ongoing Telnyx Voice Calls"
+        const val MISSED_CALL_CHANNEL_NAME = "Missed Telnyx Voice Calls"
         const val NOTIFICATION_ID = 1001
         const val ONGOING_CALL_NOTIFICATION_ID = 1002
         private const val TAG = "TelnyxNotifications"
+        private val ringtoneLock = Any()
+        private var incomingCallRingtone: Ringtone? = null
+        private var incomingCallMediaPlayer: MediaPlayer? = null
+
+        /**
+         * Notifications can produce only a short alert (and some OEMs suppress it when
+         * a full-screen call notification immediately launches the app). Keep the
+         * configured app ringtone, or the device's selected phone ringtone, playing
+         * until the incoming call is handled.
+         */
+        private fun startIncomingCallRingtone(context: Context) {
+            synchronized(ringtoneLock) {
+                if (
+                    incomingCallRingtone?.isPlaying == true ||
+                    incomingCallMediaPlayer?.isPlaying == true
+                ) {
+                    return
+                }
+
+                val ringtoneUri = getIncomingCallRingtoneUriForPlayback(context) ?: return
+                if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) {
+                    startLegacyIncomingCallRingtone(context, ringtoneUri)
+                    return
+                }
+
+                val ringtone = RingtoneManager.getRingtone(context.applicationContext, ringtoneUri)
+                if (ringtone == null) {
+                    Log.w(TAG, "No incoming call ringtone is configured")
+                    return
+                }
+
+                try {
+                    ringtone.audioAttributes = AudioAttributes.Builder()
+                        .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
+                        .setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
+                        .build()
+                    ringtone.isLooping = true
+                    ringtone.play()
+                    incomingCallRingtone = ringtone
+                    Log.d(TAG, "Started incoming call ringtone")
+                } catch (e: RuntimeException) {
+                    Log.e(TAG, "Failed to start incoming call ringtone", e)
+                    ringtone.stop()
+                }
+            }
+        }
+
+        private fun startLegacyIncomingCallRingtone(context: Context, ringtoneUri: Uri) {
+            try {
+                val mediaPlayer = MediaPlayer().apply {
+                    setAudioAttributes(
+                        AudioAttributes.Builder()
+                            .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
+                            .setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
+                            .build()
+                    )
+                    setDataSource(context.applicationContext, ringtoneUri)
+                    isLooping = true
+                    setOnPreparedListener { player ->
+                        synchronized(ringtoneLock) {
+                            if (incomingCallMediaPlayer === player) {
+                                player.start()
+                            } else {
+                                player.release()
+                            }
+                        }
+                    }
+                    setOnErrorListener { player, _, _ ->
+                        Log.e(TAG, "Failed to play incoming call ringtone")
+                        if (incomingCallMediaPlayer === player) {
+                            incomingCallMediaPlayer = null
+                        }
+                        player.release()
+                        true
+                    }
+                }
+                incomingCallMediaPlayer = mediaPlayer
+                mediaPlayer.prepareAsync()
+                Log.d(TAG, "Preparing incoming call ringtone")
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed to start incoming call ringtone", e)
+            }
+        }
+
+        private fun getConfiguredIncomingCallRingtoneUri(context: Context): Uri {
+            val resourceName = VoicePnManager.getIncomingCallRingtoneResource(context)
+            if (!resourceName.isNullOrBlank()) {
+                val resourceId = context.resources.getIdentifier(
+                    resourceName,
+                    "raw",
+                    context.packageName
+                )
+                if (resourceId != 0) {
+                    return Uri.parse("android.resource://${context.packageName}/$resourceId")
+                }
+                Log.w(TAG, "Incoming ringtone resource '$resourceName' was not found; using the device ringtone")
+            }
+
+            return RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE)
+        }
+
+        private fun getIncomingCallChannelId(context: Context): String {
+            val resourceName = VoicePnManager.getIncomingCallRingtoneResource(context)
+            if (resourceName.isNullOrBlank()) return "${INCOMING_CALL_CHANNEL_PREFIX}_default"
+
+            val resourceId = context.resources.getIdentifier(resourceName, "raw", context.packageName)
+            return if (resourceId == 0) {
+                "${INCOMING_CALL_CHANNEL_PREFIX}_default"
+            } else {
+                "${INCOMING_CALL_CHANNEL_PREFIX}_${Integer.toUnsignedString(resourceName.hashCode(), 16)}"
+            }
+        }
+
+        private fun getIncomingCallRingtoneUriForPlayback(context: Context): Uri? {
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+                return getConfiguredIncomingCallRingtoneUri(context)
+            }
+
+            val channel = (context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager)
+                .getNotificationChannel(getIncomingCallChannelId(context))
+            if (channel?.sound == null) {
+                Log.d(TAG, "Incoming call ringtone is disabled in notification settings")
+                return null
+            }
+            return channel.sound
+        }
+
+        private fun stopIncomingCallRingtone() {
+            synchronized(ringtoneLock) {
+                incomingCallRingtone?.let { ringtone ->
+                    try {
+                        ringtone.stop()
+                    } catch (e: RuntimeException) {
+                        Log.w(TAG, "Failed to stop incoming call ringtone", e)
+                    }
+                }
+                incomingCallRingtone = null
+                incomingCallMediaPlayer?.let { mediaPlayer ->
+                    try {
+                        mediaPlayer.stop()
+                    } catch (_: IllegalStateException) {
+                        // The player may still be preparing.
+                    }
+                    mediaPlayer.release()
+                }
+                incomingCallMediaPlayer = null
+            }
+        }
         
         /**
          * Static method to hide notifications from anywhere in the app
@@ -29,6 +193,7 @@ class TelnyxNotificationHelper(private val context: Context) {
         fun hideNotificationFromContext(context: Context) {
             val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
             notificationManager.cancel(NOTIFICATION_ID)
+            stopIncomingCallRingtone()
             Log.d(TAG, "Dismissed Telnyx notification from static context")
         }
         
@@ -44,26 +209,146 @@ class TelnyxNotificationHelper(private val context: Context) {
     }
 
     private val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
-
     init {
-        createNotificationChannel()
+        createNotificationChannels()
+    }
+
+    private fun getNotificationBlockReason(channelId: String): String? {
+        if (
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
+            ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED
+        ) {
+            return "POST_NOTIFICATIONS permission is denied"
+        }
+
+        if (!NotificationManagerCompat.from(context).areNotificationsEnabled()) {
+            return "app notifications are disabled"
+        }
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = notificationManager.getNotificationChannel(channelId)
+            if (channel?.importance == NotificationManager.IMPORTANCE_NONE) {
+                return "incoming-call notification channel is blocked"
+            }
+
+            val channelGroupId = channel?.group
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P && channelGroupId != null) {
+                val channelGroup = notificationManager.getNotificationChannelGroup(channelGroupId)
+                if (channelGroup?.isBlocked == true) {
+                    return "incoming-call notification channel group is blocked"
+                }
+            }
+        }
+
+        return null
+    }
+
+    @SuppressLint("MissingPermission")
+    private fun notifyIfPermitted(
+        notificationId: Int,
+        notification: Notification,
+        channelId: String,
+    ): String? {
+        val blockReason = getNotificationBlockReason(channelId)
+        if (blockReason != null) {
+            Log.w(TAG, "Skipping notification $notificationId because $blockReason")
+            return blockReason
+        }
+
+        notificationManager.notify(notificationId, notification)
+        return null
+    }
+
+    private fun launchFullScreenIntentFallback(
+        notification: Notification,
+        callId: String,
+        metadata: String,
+        blockReason: String,
+    ) {
+        val fullScreenIntent = notification.fullScreenIntent
+        if (fullScreenIntent == null) {
+            Log.w(TAG, "Notifications unavailable ($blockReason); no full-screen fallback available for call: $callId")
+            return
+        }
+
+        try {
+            VoicePnManager.setPendingPushAction(context, "incoming_call", metadata)
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to preserve incoming-call metadata before fallback launch for call: $callId", e)
+        }
+
+        try {
+            sendFullScreenIntent(fullScreenIntent)
+            Log.w(TAG, "Notifications unavailable ($blockReason); launched full-screen incoming call fallback for call: $callId")
+        } catch (e: PendingIntent.CanceledException) {
+            Log.e(TAG, "Notifications unavailable ($blockReason); failed to launch full-screen incoming call fallback for call: $callId", e)
+            clearFallbackPushAction(callId)
+        } catch (e: RuntimeException) {
+            Log.e(TAG, "Notifications unavailable ($blockReason); background fallback launch failed for call: $callId", e)
+            clearFallbackPushAction(callId)
+        }
+    }
+
+    private fun clearFallbackPushAction(callId: String) {
+        try {
+            VoicePnManager.clearPendingPushAction(context)
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to clear preserved incoming-call metadata after fallback launch failure for call: $callId", e)
+        }
     }
 
-    private fun createNotificationChannel() {
+    private fun sendFullScreenIntent(fullScreenIntent: PendingIntent) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            val options = ActivityOptions.makeBasic().apply {
+                setPendingIntentBackgroundActivityStartMode(ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED)
+            }.toBundle()
+
+            fullScreenIntent.send(context, 0, null, null, null, null, options)
+        } else {
+            fullScreenIntent.send()
+        }
+    }
+
+    private fun createNotificationChannels() {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            val channel = NotificationChannel(
-                CHANNEL_ID,
-                CHANNEL_NAME,
+            // New ID: Android preserves a channel's sound after it is created, so the
+            // prior silent channel cannot be updated for existing installations.
+            val incomingCallChannel = NotificationChannel(
+                getIncomingCallChannelId(context),
+                INCOMING_CALL_CHANNEL_NAME,
                 NotificationManager.IMPORTANCE_HIGH
             ).apply {
                 description = "Notifications for incoming Telnyx voice calls"
                 enableLights(true)
                 lightColor = Color.GREEN
                 enableVibration(true)
-                setSound(null, null) // Disable sound, CallKit will handle audio
+                setSound(
+                    getConfiguredIncomingCallRingtoneUri(context),
+                    AudioAttributes.Builder()
+                        .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
+                        .setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
+                        .build()
+                )
+            }
+            val ongoingCallChannel = NotificationChannel(
+                ONGOING_CALL_CHANNEL_ID,
+                ONGOING_CALL_CHANNEL_NAME,
+                NotificationManager.IMPORTANCE_LOW
+            ).apply {
+                description = "Notifications for ongoing Telnyx voice calls"
+            }
+            val missedCallChannel = NotificationChannel(
+                MISSED_CALL_CHANNEL_ID,
+                MISSED_CALL_CHANNEL_NAME,
+                NotificationManager.IMPORTANCE_DEFAULT
+            ).apply {
+                description = "Notifications for missed Telnyx voice calls"
             }
-            notificationManager.createNotificationChannel(channel)
-            Log.d(TAG, "Created notification channel: $CHANNEL_ID")
+
+            notificationManager.createNotificationChannels(
+                listOf(incomingCallChannel, ongoingCallChannel, missedCallChannel)
+            )
+            Log.d(TAG, "Created Telnyx voice notification channels")
         }
     }
 
@@ -95,14 +380,17 @@ class TelnyxNotificationHelper(private val context: Context) {
         val appIntent = Intent(context, activityClass).apply {
             flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
             putExtra("call_id", callId)
-            putExtra("action", "open_call")
+            putExtra("action", "incoming_call")
+            putExtra("meta_data", metadata)
+            putExtra("caller_name", callerName)
+            putExtra("caller_number", callerNumber)
         }
         val appPendingIntent = PendingIntent.getActivity(
             context, 0, appIntent,
             PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
         )
 
-        val builder = NotificationCompat.Builder(context, CHANNEL_ID)
+        val builder = NotificationCompat.Builder(context, getIncomingCallChannelId(context))
             .setContentTitle("Incoming Call")
             .setContentText("$displayName")
             .setSmallIcon(android.R.drawable.ic_menu_call)
@@ -114,6 +402,13 @@ class TelnyxNotificationHelper(private val context: Context) {
             .setContentIntent(appPendingIntent)
             .setColor(Color.GREEN)
 
+        // Android 21-25 has no notification channels, so configure the
+        // ringtone directly on the incoming-call notification.
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+            @Suppress("DEPRECATION")
+            builder.setSound(getConfiguredIncomingCallRingtoneUri(context), AudioManager.STREAM_RING)
+        }
+
         // Add action buttons - use direct activity PendingIntents to avoid trampoline restrictions
         // Answer action - direct activity launch to avoid BAL restrictions
         val answerActivityIntent = Intent(context, activityClass).apply {
@@ -160,8 +455,17 @@ class TelnyxNotificationHelper(private val context: Context) {
         hideIncomingCallNotification()
         
         val notification = createIncomingCallNotification(callerName, callerNumber, callId,metadata, mainActivityClass)
-        notificationManager.notify(NOTIFICATION_ID, notification)
-        Log.d(TAG, "Showed incoming call notification for: $callerName ($callerNumber)")
+        val blockReason = notifyIfPermitted(
+            NOTIFICATION_ID,
+            notification,
+            getIncomingCallChannelId(context),
+        )
+        if (blockReason == null) {
+            startIncomingCallRingtone(context)
+            Log.d(TAG, "Showed incoming call notification for: $callerName ($callerNumber)")
+        } else {
+            launchFullScreenIntentFallback(notification, callId, metadata, blockReason)
+        }
     }
 
     fun showMissedCallNotification(
@@ -175,7 +479,7 @@ class TelnyxNotificationHelper(private val context: Context) {
         val displayName = callerName ?: callerNumber ?: "Unknown Caller"
         val displayNumber = if (callerName != null && callerNumber != null) callerNumber else ""
         
-        val notification = NotificationCompat.Builder(context, CHANNEL_ID)
+        val notification = NotificationCompat.Builder(context, MISSED_CALL_CHANNEL_ID)
             .setContentTitle("Missed Call")
             .setContentText("$displayName${if (displayNumber.isNotEmpty()) "\n$displayNumber" else ""}")
             .setSmallIcon(android.R.drawable.ic_menu_call)
@@ -186,8 +490,16 @@ class TelnyxNotificationHelper(private val context: Context) {
             .setColor(Color.RED)
             .build()
             
-        notificationManager.notify(NOTIFICATION_ID, notification)
-        Log.d(TAG, "Showed missed call notification for: $callerName ($callerNumber)")
+        val blockReason = notifyIfPermitted(
+            NOTIFICATION_ID,
+            notification,
+            MISSED_CALL_CHANNEL_ID,
+        )
+        if (blockReason == null) {
+            Log.d(TAG, "Showed missed call notification for: $callerName ($callerNumber)")
+        } else {
+            Log.w(TAG, "Skipped missed call notification because $blockReason")
+        }
     }
 
     fun showOngoingCallNotification(
@@ -197,8 +509,16 @@ class TelnyxNotificationHelper(private val context: Context) {
         mainActivityClass: Class<*>? = null
     ) {
         val notification = createOngoingCallNotification(callerName, callerNumber, callId, mainActivityClass)
-        notificationManager.notify(ONGOING_CALL_NOTIFICATION_ID, notification)
-        Log.d(TAG, "Showed ongoing call notification for: $callerName ($callerNumber)")
+        val blockReason = notifyIfPermitted(
+            ONGOING_CALL_NOTIFICATION_ID,
+            notification,
+            ONGOING_CALL_CHANNEL_ID,
+        )
+        if (blockReason == null) {
+            Log.d(TAG, "Showed ongoing call notification for: $callerName ($callerNumber)")
+        } else {
+            Log.w(TAG, "Skipped ongoing call notification because $blockReason")
+        }
     }
 
     /**
@@ -251,7 +571,7 @@ class TelnyxNotificationHelper(private val context: Context) {
             PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
         )
 
-        return NotificationCompat.Builder(context, CHANNEL_ID)
+        return NotificationCompat.Builder(context, ONGOING_CALL_CHANNEL_ID)
             .setContentTitle("Ongoing Call")
             .setContentText("$displayName${if (displayNumber.isNotEmpty()) " ($displayNumber)" else ""}")
             .setSmallIcon(android.R.drawable.ic_menu_call)
@@ -267,6 +587,7 @@ class TelnyxNotificationHelper(private val context: Context) {
 
     fun hideIncomingCallNotification() {
         notificationManager.cancel(NOTIFICATION_ID)
+        stopIncomingCallRingtone()
         Log.d(TAG, "Hid incoming call notification")
     }
 
@@ -274,4 +595,4 @@ class TelnyxNotificationHelper(private val context: Context) {
         notificationManager.cancel(ONGOING_CALL_NOTIFICATION_ID)
         Log.d(TAG, "Hid ongoing call notification")
     }
-}
+}