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.

Overview

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)
Multidevice Support: Up to 5 devices can receive push notifications for the same user

Multidevice Push Notifications

Telnyx WebRTC supports multidevice push notifications. A single user can have up to 5 device tokens (either iOS - APNs or Android - FCM). When a user logs into the socket and provides a push token, our services will register this token to that user - allowing it to receive push notifications for incoming calls. If a 6th registration is made, the least recently used token will be removed. This effectively means that you can have up to 5 devices that can receive push notifications for the same incoming call.

Prerequisites

Before implementing push notifications, ensure you have:

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

Note: For portal configuration instructions, see Portal Setup.

Application Setup

1. Install Dependencies

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

2. Firebase Configuration (Android)

Step 1: Download Configuration File

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

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

Step 2: Configure Firebase in Android Manifest

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>

3. Native Implementation

Android Implementation

Step 1: Extend TelnyxMainActivity

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

Step 2: Create Firebase Messaging Service

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
}

Step 3: Create Notification Action Receiver

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
}

iOS Implementation

Step 1: Configure AppDelegate

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

Step 2: Configure Info.plist

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

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

4. JavaScript/TypeScript Integration

Step 1: Configure TelnyxVoiceApp

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>
  );
}

Step 2: No Background Handler Required

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. Do not call messaging().setBackgroundMessageHandler(...) from @react-native-firebase/messaging. There is no JS-side TelnyxVoiceApp.handleBackgroundPush step to wire up — a JS handler will fight the native service and can double-process or drop incoming calls. When the OS wakes your app from a terminated state to deliver an incoming call, the SDK is already handling the login internally as part of the push flow. If your app also triggers its own login* call on mount, you end up with two competing sessions — this is the single most common integration bug. Use the static method TelnyxVoipClient.isLaunchedFromPushNotification() to guard your own auto-login:

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

export default function App() {
  React.useEffect(() => {
    TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
      if (isFromPush) {
        // SDK is handling login via the push flow. Do nothing here —
        // do not call login(), loginWithToken(), or loginFromStoredConfig().
        return;
      }
      // Normal cold start: safe to auto-login.
      voipClient.loginFromStoredConfig();
    });
  }, []);

  return (
    <TelnyxVoiceApp voipClient={voipClient} enableAutoReconnect={true}>
      <YourAppContent />
    </TelnyxVoiceApp>
  );
}

How it works: the method is static (callable before the client is constructed) and returns true when there is a pending FCM intent (Android) or PushKit payload (iOS) that has not yet been consumed by the SDK. It works on both platforms. Common mistake — manual or automatic login on push:

// WRONG — runs on every mount, including push-launched cold starts
React.useEffect(() => {
  voipClient.login(config); // or loginWithToken(), or loginFromStoredConfig()
}, []);

// Right — guard the login on push-launched cold starts
React.useEffect(() => {
  TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
    if (!isFromPush) voipClient.loginFromStoredConfig();
  });
}, []);

Symptoms of double-login: the incoming call rings briefly then disappears, the socket disconnects mid-call, CallKit shows a call that immediately ends, or you see rapid CONNECTED → DISCONNECTED → CONNECTED cycles in the logs right after a push is delivered. If you hit these, audit every useEffect in your app for an unguarded login* call on mount. Applies to any login entry point — including login forms that re-submit stored credentials, splash screens that eagerly log in, and background tasks that refresh tokens. What to observe after the SDK finishes the push login:

voipClient.connectionState$ → emits CONNECTED (there is no separate loginState$ — CONNECTED means socket up and authenticated).
voipClient.activeCall$ → emits the Call once the SDK has processed the push.
voipClient.currentActiveCall → synchronous accessor; on push-launched mounts the call may already be present by the time you subscribe, so check this first.

React.useEffect(() => {
  if (voipClient.currentActiveCall) router.replace('/call');
  const sub = voipClient.activeCall$.subscribe((call) => {
    if (call) router.replace('/call');
  });
  return () => sub.unsubscribe();
}, []);

CallKit (iOS) and ConnectionService (Android) already render the native incoming-call UI; this RN-side navigation only matters once the user taps into the app.

Step 4: Token Registration (Optional)

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

Step 5: Authentication

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);
};

Configuration Options

TelnyxVoiceApp Configuration

<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>

VoIP Client Configuration

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.

Authentication with Push Tokens

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

Credential-Based Authentication

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);

Token-Based Authentication

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);

What Happens Automatically

The SDK handles push notifications automatically once you:

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

Android Automatic Features

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

iOS Automatic Features

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

Advanced Configuration

Custom FCM Message Handling (Android)

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
        }
    }
}

Push Notification Debugging

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
});

Troubleshooting

Common Issues

Push Notifications Not Received

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

App Not Launching from Push

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

Call Connection Issues

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

Debug Logging

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();
  };
}, []);

Security Considerations

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

Next Steps

After completing the app setup:

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

For additional configuration and troubleshooting, see:

​Push Notification App Setup

​Overview

​Multidevice Push Notifications

​Prerequisites

​Application Setup

​1. Install Dependencies

​2. Firebase Configuration (Android)

​Step 1: Download Configuration File

​Step 2: Configure Firebase in Android Manifest

​3. Native Implementation

​Android Implementation

​Step 1: Extend TelnyxMainActivity

​Step 2: Create Firebase Messaging Service

​Step 3: Create Notification Action Receiver

​iOS Implementation

​Step 1: Configure AppDelegate

​Step 2: Configure Info.plist

​4. JavaScript/TypeScript Integration

​Step 1: Configure TelnyxVoiceApp

​Step 2: No Background Handler Required

​Step 3: Detect Push-Launched Cold Starts (Avoid Double-Login)

​Step 4: Token Registration (Optional)

​Step 5: Authentication

​Configuration Options

​TelnyxVoiceApp Configuration

​VoIP Client Configuration

​Authentication with Push Tokens

​Credential-Based Authentication

​Token-Based Authentication

​What Happens Automatically

​Android Automatic Features

​iOS Automatic Features

​Advanced Configuration

​Custom FCM Message Handling (Android)

​Push Notification Debugging

​Troubleshooting

​Common Issues

​Push Notifications Not Received

​App Not Launching from Push

​Call Connection Issues

​Debug Logging

​Security Considerations

​Next Steps