Push Notification App Setup

This guide covers the complete setup required in your React Native application to enable push notifications for incoming calls using the @telnyx/react-voice-commons-sdk.

The Telnyx React Voice Commons SDK provides comprehensive push notification support for both iOS and Android platforms:

• iOS: Uses Apple Push Notification Service (APNs) with VoIP certificates for instant call delivery
• Android: Uses Firebase Cloud Messaging (FCM) for background call notifications
• Background Handling: Automatic call processing when app is in background or terminated
• Native Call UI: Integration with CallKit (iOS) and ConnectionService (Android)

Before implementing push notifications, ensure you have:

1. Telnyx Portal Configuration: Push certificates and FCM keys configured in your Telnyx portal
2. Development Environment: React Native development environment set up for both platforms
3. Firebase Project (Android): Firebase project created with FCM enabled
4. Apple Developer Account (iOS): VoIP push certificates configured

Note

: For portal configuration instructions, see Portal Setup.

The SDK requires specific dependencies for push notification handling:

# iOS VoIP push notifications
npm install react-native-voip-push-notification

# Expo notifications for Android FCM token (if using Expo)
npx expo install expo-notifications

# Note: Firebase messaging is handled natively on Android
# No @react-native-firebase/messaging dependency required

1. Download the google-services.json file from your Firebase project console
2. Place it in your project root directory (same level as package.json)

your-project/
├── google-services.json  ← Place here
├── package.json
├── android/
└── ios/

Ensure your android/app/src/main/AndroidManifest.xml includes Firebase services:

<application>
    <!-- Your existing application configuration -->
    
    <!-- Firebase Messaging Service -->
    <service
        android:name=".AppFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
    
    <!-- Telnyx Notification Action Receiver -->
    <receiver
        android:name=".AppNotificationActionReceiver"
        android:exported="false">
        <intent-filter>
            <action android:name="com.telnyx.rn_voice_sdk_demo.ANSWER_CALL" />
            <action android:name="com.telnyx.rn_voice_sdk_demo.REJECT_CALL" />
        </intent-filter>
    </receiver>
</application>

Your app's MainActivity should extend TelnyxMainActivity for automatic push notification handling:

// android/app/src/main/java/com/yourpackage/MainActivity.kt
package com.yourpackage

import com.telnyx.react_voice_commons.TelnyxMainActivity
import android.content.Intent
import android.os.Bundle

class MainActivity : TelnyxMainActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Your app-specific initialization
    }

    override fun onHandleIntent(intent: Intent) {
        super.onHandleIntent(intent)
        // Handle any additional intent processing if needed
    }
}

Key Features Provided by TelnyxMainActivity:

• Automatic push notification intent handling
• Call action processing (Answer/Decline from notifications)
• Proper lifecycle management for VoIP functionality
• Integration with VoicePnManager for push notification state

Create a Firebase messaging service that extends TelnyxFirebaseMessagingService:

// android/app/src/main/java/com/yourpackage/AppFirebaseMessagingService.kt
package com.yourpackage

import com.telnyx.react_voice_commons.TelnyxFirebaseMessagingService

/**
 * App-specific FCM service that extends the Telnyx base service
 */
class AppFirebaseMessagingService : TelnyxFirebaseMessagingService() {
    // All Telnyx voice push notification handling is inherited from the base class
    // Add any app-specific FCM handling here if needed
}

Create a notification action receiver for handling notification actions:

// android/app/src/main/java/com/yourpackage/AppNotificationActionReceiver.kt
package com.yourpackage

import com.telnyx.react_voice_commons.TelnyxNotificationActionReceiver

/**
 * App-specific notification action receiver
 */
class AppNotificationActionReceiver : TelnyxNotificationActionReceiver() {
    // All notification action handling is inherited from the base class
    // Add any app-specific notification handling here if needed
}

Your AppDelegate should implement PKPushRegistryDelegate and delegate to TelnyxVoipPushHandler:

// ios/YourApp/AppDelegate.swift
import UIKit
import PushKit
import TelnyxVoiceCommons

@UIApplicationMain
public class AppDelegate: ExpoAppDelegate, PKPushRegistryDelegate {

  public override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // Your existing setup...

    // Initialize VoIP push registry via react-voice-commons
    TelnyxVoipPushHandler.initializeVoipRegistration()

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

  // MARK: - VoIP Push Notifications
  public func pushRegistry(
    _ registry: PKPushRegistry, 
    didUpdate pushCredentials: PKPushCredentials, 
    for type: PKPushType
  ) {
    TelnyxVoipPushHandler.shared.handleVoipTokenUpdate(pushCredentials, type: type)
  }

  public func pushRegistry(
    _ registry: PKPushRegistry, 
    didReceiveIncomingPushWith payload: PKPushPayload, 
    for type: PKPushType, 
    completion: @escaping () -> Void
  ) {
    TelnyxVoipPushHandler.shared.handleVoipPush(payload, type: type, completion: completion)
  }
}

Important Notes:

• CallKit integration is automatically handled by the internal CallBridge component
• You don't need to implement any CallKit delegate methods manually
• Audio session management is automatically handled
• The TelnyxVoipPushHandler manages all VoIP push notification processing

Add the required background modes to your ios/YourApp/Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>voip</string>
    <string>background-processing</string>
</array>

Wrap your app with TelnyxVoiceApp for automatic lifecycle management:

// App.tsx
import React from 'react';
import { TelnyxVoiceApp, createTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
import YourAppContent from './YourAppContent';

// Create the VoIP client instance
const voipClient = createTelnyxVoipClient({
  enableAppStateManagement: true, // Enable automatic app state management
  debug: true, // Enable debug logging
});

export default function App() {
  return (
    <TelnyxVoiceApp 
      voipClient={voipClient} 
      enableAutoReconnect={true} 
      debug={true}
    >
      <YourAppContent />
    </TelnyxVoiceApp>
  );
}

Android push notifications are handled automatically by the SDK's native components. You don't need to register any background message handlers in your JavaScript code.

The SDK handles everything natively through:

• TelnyxMainActivity (extends your MainActivity)
• TelnyxFirebaseMessagingService (extends your FCM service)

Simply extend these classes as shown in the native implementation steps above, and push notifications will work automatically.

Push tokens are handled automatically by the SDK during authentication. For most apps, you don't need to do anything additional.

If you want to handle push tokens manually (for logging or custom logic), you can use the VoipTokenFetcher component:

import { VoipTokenFetcher } from './VoipTokenFetcher';

export function YourLoginComponent() {
  const handleTokenReceived = (token: string) => {
    console.log('Push token received:', token);
    // Store or use the token as needed
  };

  return (
    <View>
      <VoipTokenFetcher onTokenReceived={handleTokenReceived} debug={true} />
      {/* Your login form here */}
    </View>
  );
}

The VoipTokenFetcher component automatically:

• Requests notification permissions
• Retrieves FCM tokens (Android) and VoIP tokens (iOS)
• Handles platform-specific token registration

Include push tokens in your login configuration:

// Login with automatic push token handling
import { createCredentialConfig } from '@telnyx/react-voice-commons-sdk';

const handleLogin = async (username: string, password: string) => {
  const config = createCredentialConfig(username, password, {
    debug: true,
    // Push tokens are automatically retrieved and registered by the SDK
  });

  await voipClient.login(config);
};

<TelnyxVoiceApp
  voipClient={voipClient}
  enableAutoReconnect={true}        // Enable automatic reconnection
  debug={true}                      // Enable debug logging
  skipWebBackgroundDetection={true} // Skip web-specific background detection
  onPushNotificationProcessingStarted={() => {
    console.log('Push notification processing started');
  }}
  onPushNotificationProcessingCompleted={() => {
    console.log('Push notification processing completed');
  }}
  onAppStateChanged={(state) => {
    console.log('App state changed:', state);
  }}
>
  {children}
</TelnyxVoiceApp>

const voipClient = createTelnyxVoipClient({
  enableAppStateManagement: true, // Enable automatic app state management
  debug: true,                    // Enable debug logging
});

Configuration Options Explained:

• enableAppStateManagement: true: Enables automatic background/foreground app state management. When enabled, the library automatically disconnects when the app goes to background (unless there's an active call) and handles reconnection logic.
• debug: true: Enables detailed logging for connection states, call transitions, and push notification processing.

Push tokens are automatically handled by the SDK. You only need to include the SDK and authenticate normally:

import { createCredentialConfig } from '@telnyx/react-voice-commons-sdk';

const config = createCredentialConfig('your_sip_username', 'your_sip_password', {
  debug: true,
  // Push tokens are automatically managed by the SDK
});

await voipClient.login(config);

import { createTokenConfig } from '@telnyx/react-voice-commons-sdk';

const config = createTokenConfig('your_jwt_token', {
  debug: true,
  // Push tokens are automatically managed by the SDK
});

await voipClient.loginWithToken(config);

The SDK handles push notifications automatically once you:

1. Android: Extend TelnyxMainActivity and TelnyxFirebaseMessagingService
2. iOS: Implement PKPushRegistryDelegate and delegate to TelnyxVoipPushHandler
3. Both: Wrap your app with TelnyxVoiceApp and authenticate with the SDK

• FCM token registration with Telnyx servers
• Background push notification processing
• Incoming call notifications with Answer/Decline buttons
• App launching from terminated state
• Call connection and audio setup

• VoIP token registration with Telnyx servers
• CallKit integration for native call UI
• Background call processing
• App launching from terminated state
• Audio session management

If you need to handle additional FCM messages beyond Telnyx voice calls, extend the service:

// android/app/src/main/java/com/yourpackage/AppFirebaseMessagingService.kt
class AppFirebaseMessagingService : TelnyxFirebaseMessagingService() {
    
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        // Let Telnyx handle voice notifications first
        super.onMessageReceived(remoteMessage)
        
        // Handle your app's other notifications
        if (remoteMessage.data.containsKey("your_app_notification_type")) {
            // Handle your custom notifications
        }
    }
}

Enable comprehensive debugging for push notification issues:

// Enable global debug logging
if (__DEV__) {
  (global as any).__TELNYX_DEBUG__ = true;
}

const voipClient = createTelnyxVoipClient({
  debug: true, // Enable SDK debug logging
});

Android:

• Verify google-services.json is in the correct location
• Check Firebase project configuration and FCM keys in Telnyx portal
• Ensure AppFirebaseMessagingService is properly registered in AndroidManifest.xml
• Verify app is not in battery optimization/doze mode

iOS:

• Ensure VoIP push certificates are configured in Apple Developer account
• Verify certificates are uploaded to Telnyx portal
• Check that TelnyxVoipPushHandler.initializeVoipRegistration() is called
• Ensure app has proper VoIP background modes configured

Android:

• Verify MainActivity extends TelnyxMainActivity
• Check intent filters in AndroidManifest.xml
• Ensure onHandleIntent is properly implemented

iOS:

• Verify AppDelegate implements PKPushRegistryDelegate
• Ensure proper delegation to TelnyxVoipPushHandler
• Check VoIP background modes in Info.plist

• Verify authentication is successful before push notification
• Check network connectivity and Telnyx service availability
• Ensure proper error handling in push notification flow
• Verify call state management in TelnyxVoiceApp

Enable detailed logging to troubleshoot issues:

// In your main component
useEffect(() => {
  // Listen to connection states
  const connectionSub = voipClient.connectionState$.subscribe((state) => {
    console.log('Connection state:', state);
  });

  // Listen to call states
  const callsSub = voipClient.calls$.subscribe((calls) => {
    console.log('Active calls:', calls.length);
    calls.forEach((call, index) => {
      console.log(`Call ${index}:`, call.currentState);
    });
  });

  return () => {
    connectionSub.unsubscribe();
    callsSub.unsubscribe();
  };
}, []);

1. Token Storage: Push tokens are automatically stored securely by the SDK
2. Certificate Management: Keep VoIP certificates and FCM keys secure
3. Authentication: Ensure proper authentication before accepting calls
4. Network Security: Use secure connections for all Telnyx communications

After completing the app setup:

1. Test Push Notifications: Test with both foreground and background scenarios
2. Call Flow Testing: Verify complete call flow from push to termination
3. Production Deployment: Configure production certificates and keys
4. Monitoring: Implement logging and monitoring for production use

For additional configuration and troubleshooting, see:

• Portal Setup Guide
• API Documentation
• Telnyx Developer Portal