Notification Quickstart for Android

Push Notification Quickstart with telnyx_common

The telnyx_common module provides a comprehensive SDK implementation, including push notification handling for your Android application. This guide will help you quickly integrate Telnyx's push notification system using the ready-made components available in the telnyx_common module.

The telnyx_common module offers a complete solution for handling push notifications for incoming calls, including:

• Receiving and parsing Firebase Cloud Messaging (FCM) notifications
• Displaying appropriate notifications for incoming calls
• Handling user interactions with notifications (answer, reject, end call)
• Managing notification channels and importance levels
• Supporting both modern CallStyle notifications and legacy notifications for backward compatibility

Instead of implementing these features from scratch, you can leverage the notification components in the telnyx_common module as a drop-in solution for your application.

MyFirebaseMessagingService is responsible for receiving and processing incoming Firebase Cloud Messaging (FCM) push notifications for calls.

Key Features:

• Parses incoming push notifications and extracts call metadata
• Handles different types of notifications (incoming calls, missed calls)
• Routes notifications to the appropriate handlers
• Supports both modern CallStyle notifications and legacy notifications

Implementation:

1. Register the service in your AndroidManifest.xml:

<service
    android:name="com.telnyx.webrtc.common.notification.MyFirebaseMessagingService"
    android:priority="10000"
    android:exported="true">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

CallNotificationService handles the creation and management of call notifications using Android's modern CallStyle API.

Key Features:

• Creates and manages notification channels with appropriate importance levels
• Displays incoming call notifications with answer/reject actions
• Shows ongoing call notifications with end call action
• Supports full-screen incoming call UI
• Configures appropriate sounds, vibration patterns, and priority levels

Implementation: The service is automatically used by MyFirebaseMessagingService when an incoming call is received. No additional setup is required if you're using the telnyx_common module.

CallNotificationReceiver is a BroadcastReceiver that handles user interactions with call notifications.

Key Features:

• Processes answer, reject, and end call actions from notifications
• Routes actions to the appropriate handlers in your application
• Cancels notifications when actions are taken
• New: Uses BackgroundCallDeclineService for simplified call rejection without app launch

Implementation:

1. Register the receiver in your AndroidManifest.xml:

<receiver
    android:name="com.telnyx.webrtc.common.notification.CallNotificationReceiver"
    android:enabled="true"
    android:exported="false" />

BackgroundCallDeclineService is a new service that handles call decline operations without launching the main application.

Key Features:

• Declines incoming calls in the background without app launch
• Connects to socket with decline_push parameter for simplified decline flow
• Automatically disconnects after decline operation is complete
• Includes timeout handling to prevent service from running indefinitely
• Improves user experience by avoiding unnecessary app launches

How it works:

1. User taps decline on push notification
2. CallNotificationReceiver starts BackgroundCallDeclineService
3. Service connects to socket using connectWithDeclinePush()
4. Service sends login with decline_push: true parameter
5. Service automatically disconnects and stops after decline is processed

Implementation: The service is automatically used by CallNotificationReceiver when using the telnyx_common module. No additional setup is required.

LegacyCallNotificationService is a legacy notification service maintained for backward compatibility.

Key Features:

• Provides fallback notification handling for devices that don't support CallStyle
• Creates and manages notification channels
• Displays incoming call notifications with answer/reject actions
• Handles ringtone playback for incoming calls

Implementation:

1. Register the service in your AndroidManifest.xml and specify your main activity:

<service
    android:name="com.telnyx.webrtc.common.notification.LegacyCallNotificationService">
    <meta-data
        android:name="activity_class_name"
        android:value="your.package.MainActivity" />
</service>

To integrate push notifications using the telnyx_common module:

1. Set up Firebase Cloud Messaging (FCM) in your project:

   • Follow the Firebase setup guide
   • Add the necessary dependencies to your app's build.gradle file
   • Configure your Firebase project and download the google-services.json file

2. Register the notification components in your AndroidManifest.xml:

<service
    android:name="com.telnyx.webrtc.common.notification.MyFirebaseMessagingService"
    android:priority="10000"
    android:exported="true">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

<service
    android:name="com.telnyx.webrtc.common.notification.LegacyCallNotificationService">
    <meta-data
        android:name="activity_class_name"
        android:value="your.package.MainActivity" />
</service>

<receiver
    android:name="com.telnyx.webrtc.common.notification.CallNotificationReceiver"
    android:enabled="true"
    android:exported="false" />

3. Handle push notification actions in your main activity:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...
    
    // Check if the activity was launched from a push notification
    intent?.let { handlePushNotificationIntent(it) }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    // Handle push notification intents when the activity is already running
    intent?.let { handlePushNotificationIntent(it) }
}

private fun handlePushNotificationIntent(intent: Intent) {
    val action = intent.getStringExtra(MyFirebaseMessagingService.EXT_KEY_DO_ACTION)
    val metadataJson = intent.getStringExtra(MyFirebaseMessagingService.TX_PUSH_METADATA)
    
    if (action != null && metadataJson != null) {
        val pushMetadata = Gson().fromJson(metadataJson, PushMetaData::class.java)
        
        when (action) {
            MyFirebaseMessagingService.ACT_ANSWER_CALL -> {
                // Answer the call using TelnyxViewModel
                viewModel.answerIncomingPushCall(this, pushMetadata)
            }
            MyFirebaseMessagingService.ACT_REJECT_CALL -> {
                // Reject the call using TelnyxViewModel
                viewModel.rejectIncomingPushCall(this, pushMetadata)
            }
            MyFirebaseMessagingService.ACT_OPEN_TO_REPLY -> {
                // Show UI for incoming call
                // This is called when the user taps the notification itself
            }
        }
    }
}

4. Configure the CallForegroundService for ongoing calls:

<service 
    android:name="com.telnyx.webrtc.common.service.CallForegroundService"
    android:enabled="true"
    android:exported="true"
    android:foregroundServiceType="phoneCall|microphone"
    android:permission="android.permission.FOREGROUND_SERVICE_PHONE_CALL"
    android:process=":call_service" />

You can refer to our sample apps for complete implementations:

The Compose sample app demonstrates how to integrate push notifications in a Jetpack Compose application:

• AndroidManifest.xml - Shows how to register the notification components
• MainActivity.kt - Demonstrates handling push notification intents

The XML sample app shows the integration in a traditional XML-based Android application:

• AndroidManifest.xml - Shows how to register the notification components
• MainActivity.kt - Demonstrates handling push notification intents

If you're using the telnyx_common module, the new BackgroundCallDeclineService is automatically used for call rejections. This provides:

• Improved User Experience: No app launch interruption when declining calls
• Better Performance: Reduced battery usage and faster response times
• Simplified Implementation: No need to handle complex invite/bye message flows

If you have a custom implementation that manually handles call decline, you may want to migrate to the new approach:

Old Flow:

// User taps decline → Launch app → Connect → Wait for invite → Send bye
intent.putExtra("action", "decline_call")
startActivity(intent) // Launches main app

New Flow:

// User taps decline → Background service handles everything
BackgroundCallDeclineService.startService(context, txPushMetadata)

1. Permissions: Ensure your app has the necessary permissions for notifications and foreground services:

   <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL" />

2. Notification Channels: The telnyx_common module automatically creates appropriate notification channels, but you may want to customize them for your app's branding.

3. Testing: Test push notifications on different Android versions to ensure compatibility with both modern CallStyle notifications and legacy notifications.

4. Background Processing: Use the CallForegroundService to maintain calls when your app is in the background.

5. Error Handling: Implement proper error handling for push notification processing to ensure a smooth user experience.

6. Call Decline: Use the new BackgroundCallDeclineService for optimal user experience when declining calls from push notifications.

• If notifications are not appearing, check that notification permissions are granted and channels are properly configured.
• For issues with Firebase Cloud Messaging, verify that your FCM setup is correct and that you have the latest version of the Firebase SDK.
• If call notifications are not working correctly, ensure that the activity_class_name metadata in your AndroidManifest.xml points to the correct activity.
• For notification sound issues, check the audio settings on the device and verify that the notification channel is configured with the correct sound settings.
• Double-check the Telnyx portal to make sure push credentials are assigned properly.