team-telnyx/telnyx-webrtc-client-react-native

Telnyx WebRTC - React Native SDK

Build real-time voice communication into React Native apps (Android & iOS) using the @telnyx/react-voice-commons-sdk library.

Prerequisites: Create WebRTC credentials and generate a login token using the Telnyx server-side SDK. See the telnyx-webrtc-* skill in your server language plugin (e.g., telnyx-python, telnyx-javascript).

Features

• Reactive Streams: RxJS-based state management
• Automatic Lifecycle: Background/foreground handling
• Native Call UI: CallKit (iOS) and ConnectionService (Android)
• Push Notifications: FCM (Android) and APNs/PushKit (iOS)
• TypeScript Support: Full type definitions

Installation

npm install @telnyx/react-voice-commons-sdk

---

Basic Setup

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

// Create VoIP client instance
const voipClient = createTelnyxVoipClient({
  enableAppStateManagement: true,  // Auto background/foreground handling
  debug: true,                     // Enable logging
});

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

---

Authentication

Credential-Based Login

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

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

await voipClient.login(config);

Token-Based Login (JWT)

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

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

await voipClient.loginWithToken(config);

Auto-Reconnection

The library automatically stores credentials for seamless reconnection:

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

if (!success) {
  // No stored auth, show login UI
}

---

Reactive State Management

import { useEffect, useState } from 'react';

function CallScreen() {
  const [connectionState, setConnectionState] = useState(null);
  const [calls, setCalls] = useState([]);
  
  useEffect(() => {
    // Subscribe to connection state
    const connSub = voipClient.connectionState$.subscribe((state) => {
      setConnectionState(state);
    });
    
    // Subscribe to active calls
    const callsSub = voipClient.calls$.subscribe((activeCalls) => {
      setCalls(activeCalls);
    });
    
    return () => {
      connSub.unsubscribe();
      callsSub.unsubscribe();
    };
  }, []);
  
  return (/* UI */);
}

Individual Call State

useEffect(() => {
  if (call) {
    const sub = call.callState$.subscribe((state) => {
      console.log('Call state:', state);
    });
    return () => sub.unsubscribe();
  }
}, [call]);

---

Making Calls

const call = await voipClient.newCall('+18004377950');

---

Receiving Calls

Incoming calls are handled automatically via push notifications and the TelnyxVoiceApp wrapper. The native call UI (CallKit/ConnectionService) is displayed automatically.

---

Call Controls

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

// Mute/Unmute
await call.mute();
await call.unmute();

// Hold/Unhold
await call.hold();
await call.unhold();

// End call
await call.hangup();

// Send DTMF
await call.dtmf('1');

---

Push Notifications - Android (FCM)

1. Place google-services.json in project root

2. MainActivity Setup

// MainActivity.kt
import com.telnyx.react_voice_commons.TelnyxMainActivity

class MainActivity : TelnyxMainActivity() {
    override fun onHandleIntent(intent: Intent) {
        super.onHandleIntent(intent)
        // Additional intent processing
    }
}

3. Background Message Handler

// index.js or App.tsx
import messaging from '@react-native-firebase/messaging';
import { TelnyxVoiceApp } from '@telnyx/react-voice-commons-sdk';

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

---

Push Notifications - iOS (PushKit)

AppDelegate Setup

// AppDelegate.swift
import PushKit
import TelnyxVoiceCommons

@UIApplicationMain
public class AppDelegate: ExpoAppDelegate, PKPushRegistryDelegate {
  
  public override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // Initialize VoIP push registration
    TelnyxVoipPushHandler.initializeVoipRegistration()
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
  
  // VoIP Push Token Update
  public func pushRegistry(_ registry: PKPushRegistry, 
                           didUpdate pushCredentials: PKPushCredentials, 
                           for type: PKPushType) {
    TelnyxVoipPushHandler.shared.handleVoipTokenUpdate(pushCredentials, type: type)
  }
  
  // VoIP Push Received
  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 is automatically handled by the internal CallBridge component.

---

Configuration Options

createTelnyxVoipClient Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enableAppStateManagement | boolean | true | Auto background/foreground handling | | debug | boolean | false | Enable debug logging |

TelnyxVoiceApp Props

| Prop | Type | Description | |------|------|-------------| | voipClient | TelnyxVoipClient | The VoIP client instance | | enableAutoReconnect | boolean | Auto-reconnect on disconnect | | debug | boolean | Enable debug logging |

---

Storage Keys (Managed Automatically)

The library manages these AsyncStorage keys internally:

• @telnyx_username - SIP username
• @telnyx_password - SIP password
• @credential_token - JWT token
• @push_token - Push notification token

You don't need to manage these manually.

---

Troubleshooting

| Issue | Solution | |-------|----------| | Double login | Don't call login() manually when using TelnyxVoiceApp with auto-reconnect | | Background disconnect | Check enableAutoReconnect setting | | Android push not working | Verify google-services.json and MainActivity extends TelnyxMainActivity | | iOS push not working | Ensure AppDelegate implements PKPushRegistryDelegate and calls TelnyxVoipPushHandler | | Memory leaks | Unsubscribe from RxJS observables in useEffect cleanup | | Audio issues | iOS audio handled by CallBridge; Android check ConnectionService |

Clear Stored Auth (Advanced)

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

await AsyncStorage.multiRemove([
  '@telnyx_username',
  '@telnyx_password', 
  '@credential_token',
  '@push_token',
]);

---

Resources

• Official Documentation
• GitHub Repository
• npm Package