Telnyx React Voice Commons SDK

A high-level, state-agnostic, drop-in module for the Telnyx React Native SDK that simplifies WebRTC voice calling integration. This library provides a comprehensive solution for building VoIP applications with native call UI support, push notifications, and seamless background handling.

• TelnyxVoiceApp Integration: Automatic lifecycle management and push notification handling
• Native Call UI: CallKit (iOS) and ConnectionService (Android) integration
• Background Handling: Seamless app state transitions and background call processing
• Push Notifications: Firebase (Android) and APNs (iOS) integration
• Reactive State Management: RxJS-based state streams for real-time UI updates
• TypeScript Support: Full TypeScript definitions for better developer experience
• Cross-Platform: Built for both iOS and Android with React Native

The @telnyx/react-voice-commons-sdk library provides:

• Headless Operation: Core library that can establish and manage call state programmatically
• Reactive Streams: All state exposed via RxJS observables for easy integration
• Simplified API: Single facade class (TelnyxVoipClient) that hides underlying complexity
• Automatic Lifecycle Management: Background/foreground handling with TelnyxVoiceApp component
• Call State Management: Central state machine for managing multiple calls
• Session Management: Automatic connection lifecycle with reconnection logic
• Push Notification Support: Built-in handling for background push notifications
• TypeScript Support: Full TypeScript definitions for better developer experience

Integrate the library using the TelnyxVoiceApp component for automatic lifecycle management:

import { TelnyxVoiceApp, createTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';

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

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

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

Configuration Options Explained:

• enableAppStateManagement: true - Optional (default: 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. Set to false if you want to handle app lifecycle manually.
• debug: true - Optional: Enables detailed logging for connection states, call transitions, and push notification processing. Useful for development and troubleshooting.

The TelnyxVoiceApp component handles:

• Automatic background/foreground lifecycle management
• Push notification processing from terminated state
• Login state management with automatic reconnection
• Background client management for push notifications

// Listen to connection state
voipClient.connectionState$.subscribe((state) => {
  console.log('Connection state:', state);
});

// Listen to active calls
voipClient.calls$.subscribe((calls) => {
  console.log('Active calls:', calls);
});

// Handle individual call state
call.callState$.subscribe((state) => {
  console.log('Call state:', state);
});

// Make a call
const call = await voipClient.newCall('1234567890');

// Answer incoming call
await call.answer();

// Control call
await call.mute();
await call.hold();
await call.hangup();

The library supports both credential-based and token-based authentication with automatic persistence for seamless reconnection.

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

const config = createCredentialConfig('your_sip_username', 'your_sip_password', {
  debug: true,
  pushNotificationDeviceToken: 'your_device_token',
});

await voipClient.login(config);

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

const config = createTokenConfig('your_jwt_token', {
  debug: true,
  pushNotificationDeviceToken: 'your_device_token',
});

await voipClient.loginWithToken(config);

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.

The library uses these AsyncStorage keys internally:

• @telnyx_username - SIP username (credential auth)
• @telnyx_password - SIP password (credential auth)
• @credential_token - JWT authentication token (token auth)
• @push_token - Push notification device token

Note: These are managed automatically by the library. You only need to call login() once, and the library will handle storage and future reconnections.

// Automatically reconnects using internally stored credentials or token
const success = await voipClient.loginFromStoredConfig();

if (!success) {
  // No stored authentication data found, show login UI
  console.log('Please log in again');
}

When Auto-Reconnection Happens:

• App launches from background/terminated state
• Push notification received while disconnected
• Network reconnection after connectivity loss
• App state changes (foreground/background transitions)

Demo App Note: When using the library in a demo application, the TelnyxLoginForm component may do additional storage for UI convenience (pre-filling login forms). This is separate from the library's internal authentication storage and is not required for production apps.

If you need to clear stored authentication data manually:

import AsyncStorage from '@react-native-async-storage/async-storage';

// Clear all Telnyx authentication data
await AsyncStorage.multiRemove([
  '@telnyx_username',
  '@telnyx_password',
  '@credential_token',
  '@push_token',
]);

Important: This is typically not needed. The library manages authentication storage automatically. Only use this for advanced scenarios like implementing a "logout" feature that clears all stored data.

The library provides complete native integration for both platforms. These integrations are required for production apps using the library.

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

// In your app's MainActivity.kt
import com.telnyx.react_voice_commons.TelnyxMainActivity

class MainActivity : TelnyxMainActivity() {
    // Your app-specific code

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

The TelnyxMainActivity provides:

• 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

1. Place google-services.json in the project root
2. Register background message handler:

import messaging from '@react-native-firebase/messaging';
import { TelnyxVoiceApp } from '@telnyx/react-voice-commons-sdk';

messaging().setBackgroundMessageHandler(async (remoteMessage) => {
  await TelnyxVoiceApp.handleBackgroundPush(remoteMessage.data);
});

Your AppDelegate only needs to implement PKPushRegistryDelegate for VoIP push notifications. CallKit integration is automatically handled by CallBridge:

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

Note: CallKit integration (CXProvider, CXProviderDelegate, audio session management) is automatically handled by the internal CallBridge component. You don't need to implement any CallKit delegate methods manually.

• Configure VoIP push certificates in your Apple Developer account
• The TelnyxVoipPushHandler automatically handles token registration and push processing
• CallKit integration is automatically managed by CallBridge - no manual setup required

1. Push Notification Handling: Both platforms handle background push notifications properly
2. Native Call UI: CallKit (iOS, managed by CallBridge) and ConnectionService (Android) integration
3. Audio Session Management: Automatic audio session handling for VoIP calls via CallBridge
4. Background Processing: Seamless app state transitions and background call handling
5. Intent Processing: Android intent handling for notification actions (Answer/Decline)
6. Token Management: Automatic push token registration and updates

• Node.js and npm
• Expo CLI
• iOS development: Xcode
• Android development: Android Studio

1. Remove global Expo CLI (if previously installed):

   npm uninstall -g expo

2. Install dependencies (including local Expo):

   npm install

3. Run Expo install to ensure all dependencies are properly configured:

   npx expo install

4. Configure Firebase for Android:

   • Download the google-services.json file from your Firebase project
   • Place it in the root directory of the project

5. Prebuild the project:

   npx expo prebuild

6. Install iOS dependencies (required for iOS):

   cd ios && pod install && cd ..

1. Start Metro bundler (in a separate terminal):

   npx expo start --clear --reset-cache

2. Run on iOS:

   npx expo run:ios

3. Run on Android:

   npx expo run:android

Note

: Make sure you have the necessary development environment set up for iOS (Xcode) or Android (Android Studio) before running the respective commands.

Once running, the demo app provides:

• Login Form: Enter your Telnyx SIP credentials or token
• Dialer Interface: Make outgoing calls with a native dialer UI
• Call Management: Answer, decline, hold, mute, and transfer calls
• Native Call UI: Integrated CallKit (iOS) and ConnectionService (Android)
• Push Notifications: Receive calls when app is in background or terminated
• Multiple Call Support: Handle multiple simultaneous calls
• Background Handling: Seamless app state transitions

The demo app includes debug logging enabled by default:

// Enable debug logging for the Telnyx SDK
if (__DEV__) {
  log.setLevel('debug');
  (global as any).__TELNYX_DEBUG__ = true;
}

This provides detailed logging for:

• Connection state changes
• Call state transitions
• Push notification processing
• Background lifecycle events

If you encounter network connection errors on iOS:

# Try clearing cache and resetting
npx expo start --clear --reset-cache

# Or use tunnel mode
npx expo start --tunnel

# Or specify host explicitly
npx expo start --host lan

If you see VoIP-related crashes on iOS, ensure your AppDelegate.swift includes the VoIP push notification delegate methods. The project includes these by default, but if you encounter issues, rebuild the iOS project:

npx expo prebuild --platform ios --clean
npx expo run:ios

Ensure you're not calling login methods manually when using TelnyxVoiceApp with auto-reconnection enabled.

Check if enableAutoReconnect is set appropriately for your use case in the TelnyxVoiceApp configuration.

• Android:
  • Verify google-services.json is in the correct location and Firebase is properly configured
  • Ensure your MainActivity extends TelnyxMainActivity
  • Check that VoicePnManager is properly handling push actions
• iOS:
  • Ensure VoIP push certificates are configured in your Apple Developer account
  • Verify AppDelegate implements PKPushRegistryDelegate and delegates to TelnyxVoipPushHandler
  • Check that TelnyxVoipPushHandler.initializeVoipRegistration() is called in didFinishLaunchingWithOptions
• Both: Check that background message handlers are properly registered

• Android: Ensure MainActivity extends TelnyxMainActivity for proper intent handling
• iOS: Verify AppDelegate implements PKPushRegistryDelegate and delegates to TelnyxVoipPushHandler
• CallKit: On iOS, CallKit integration is automatically handled by CallBridge - no manual setup required

• iOS: Audio session management is automatically handled by CallBridge
• Android: Verify ConnectionService is properly configured for audio routing
• Both: Ensure proper audio permissions are granted

Ensure you're unsubscribing from RxJS observables in your React components:

useEffect(() => {
  const subscription = voipClient.connectionState$.subscribe(handleStateChange);
  return () => subscription.unsubscribe();
}, []);
}, []);

For complete API documentation and advanced usage patterns, see the TelnyxVoiceApp Documentation.

When contributing to this demo or the underlying library:

1. Maintain compatibility with both iOS and Android platforms
2. Add comprehensive tests for new features
3. Update documentation for any API changes
4. Follow the existing code style and patterns
5. Test with both foreground and background scenarios

MIT License - see LICENSE file for details.