@telnyx/react-voice-commons-sdk 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG.md
 
+## [0.4.0] (2026-04-19)
+
+### Enhancement
+
+- **DTMF support.** Added `Call.dtmf(digits: string): Promise<void>` — sends DTMF tones on the current call as Verto `INFO` messages. Accepts a single digit (e.g. `"5"`) or a whole string (e.g. `"1234#"`). Valid characters are `0-9`, `A-D`, `*`, and `#`; anything else is silently dropped by the underlying SDK. Call state must be `ACTIVE` — will throw otherwise.
+
+### Bug Fixing
+
+- **Fixed `IllegalArgumentException: Could not find @ReactModule annotation in VoicePnBridgeModule` crash** on Android when the app is cold-started by a push notification action (Answer/Decline). React Native 0.79+ requires `@ReactModule(name = …)` on native modules that are looked up by class via `ReactContext.getNativeModule(Class)`. The annotation has been added to `VoicePnBridgeModule`, and the module name is now sourced from a single `NAME` constant.
+
+### Dependencies
+
+- Now requires `@telnyx/react-native-voice-sdk >= 0.4.2`, which fixes a bug where every `Call.dtmf()` invocation threw `Invalid DTMF response received` even though the tone was delivered. See the [voice-sdk 0.4.2 changelog](../package/CHANGELOG.md#042-2026-04-19) for details.
+
 ## [0.3.1] (2026-04-16)
 
 ### Bug Fixing

package/README.md

@@ -118,9 +118,18 @@ call.callState$.subscribe((state) => {
 
 ### Navigation
 
-As of **v0.3.0**, the SDK no longer navigates the host app. Routing on state transitions (e.g. redirecting to a login screen on disconnect, surfacing a dialer screen after answering a call via CallKit) is entirely the host app's responsibility. Subscribe to `connectionState$` and `activeCall$` and invoke your own navigator.
+As of **v0.3.0**, the SDK no longer navigates the host app. Routing on state transitions (e.g. redirecting to a login screen on disconnect, surfacing an in-call screen when a call arrives via push) is entirely the host app's responsibility. Subscribe to the observables below and invoke your own navigator.
 
-Example using `expo-router`:
+**What to observe:**
+
+| Observable                    | Emits                                                                                        | Use it for                                                                                                                                                                        |
+| ----------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `voipClient.connectionState$` | `TelnyxConnectionState` (`CONNECTING`, `CONNECTED`, `RECONNECTING`, `DISCONNECTED`, `ERROR`) | Redirect to login on `DISCONNECTED`; gate outbound-call UI on `CONNECTED`. There is no separate `loginState$` — `CONNECTED` means the socket is up **and** authenticated.         |
+| `voipClient.activeCall$`      | `Call \| null`                                                                               | Navigate to your in-call screen when a call appears. Primary signal for push-launched cold starts — when the SDK finishes the push-driven login and the call arrives, this emits. |
+| `voipClient.calls$`           | `Call[]`                                                                                     | Multi-call UIs (call waiting, conference).                                                                                                                                        |
+| `call.callState$`             | `TelnyxCallState`                                                                            | Per-call transitions (ringing / active / held / ended).                                                                                                                           |
+
+#### Redirect to login on disconnect
 
 ```tsx
 import { router } from 'expo-router';
@@ -137,6 +146,43 @@ useEffect(() => {
 }, []);
 ```
 
+#### Navigate to in-call screen when a call arrives (push-launched or otherwise)
+
+This is the piece that pairs with the push flow: after `isLaunchedFromPushNotification()` tells you to skip manual login, the SDK drives login internally and the call shows up on `activeCall$`. The same subscription handles foreground pushes and outbound calls, so you only need one:
+
+```tsx
+import { router } from 'expo-router';
+import { useEffect } from 'react';
+
+useEffect(() => {
+  // Handle the cold-start race: if the call was already delivered before this
+  // component mounted (common on push-launched cold starts), read it synchronously.
+  if (voipClient.currentActiveCall) {
+    router.replace('/call');
+  }
+
+  const sub = voipClient.activeCall$.subscribe((call) => {
+    if (call) router.replace('/call');
+    else router.replace('/dialer');
+  });
+  return () => sub.unsubscribe();
+}, []);
+```
+
+**Note on CallKit / ConnectionService:** the native call UI (ringtone, answer/decline) is shown by the OS regardless — your RN screen is only visible once the user taps into the app. If you only need native UI, you can skip the navigation step entirely.
+
+#### Optional: gate outbound-call UI on CONNECTED
+
+```tsx
+import { canMakeCalls } from '@telnyx/react-voice-commons-sdk';
+
+const [canCall, setCanCall] = useState(false);
+useEffect(() => {
+  const sub = voipClient.connectionState$.subscribe((s) => setCanCall(canMakeCalls(s)));
+  return () => sub.unsubscribe();
+}, []);
+```
+
 The same pattern works with `react-navigation`, React Router, or any other navigator — the SDK is agnostic.
 
 ### 4. Call Management
@@ -152,8 +198,64 @@ await call.answer();
 await call.mute();
 await call.hold();
 await call.hangup();
+
+// Send DTMF tones (for IVRs, conference pins, etc.)
+await call.dtmf('1'); // single digit
+await call.dtmf('1234#'); // whole string
+```
+
+**DTMF:** `call.dtmf(digits)` sends each character as a Verto `INFO` message to the Telnyx platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other characters are silently dropped by the underlying SDK. The call must be in the `ACTIVE` state — calling `dtmf()` in any other state throws. Safe to call with a single digit for dialpad presses or with a whole string for pre-recorded sequences.
+
+### Push Notification Flow
+
+You do not wire push handlers in JS. The native layer does the work:
+
+- **Android**: `TelnyxFirebaseMessagingService` receives the FCM message, posts the call notification, and launches `TelnyxMainActivity` with the intent on Answer/Decline.
+- **iOS**: `TelnyxVoipPushHandler` receives the PushKit payload and reports the call to CallKit.
+
+The SDK then connects the socket and restores the call internally. You observe `voipClient.calls$` to render UI.
+
+#### Detecting a Push-Launched Cold Start
+
+When the OS wakes the app from a terminated state to deliver a call, the SDK is already handling login via the push flow. If your app _also_ triggers a login on mount, you get two competing sessions (double-login), which causes the call to fail or the socket to churn.
+
+Use the static `TelnyxVoipClient.isLaunchedFromPushNotification()` to guard your login:
+
+```tsx
+import { TelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
+
+React.useEffect(() => {
+  TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
+    if (isFromPush) return; // SDK is handling login via the push flow
+    voipClient.loginFromStoredConfig(); // Normal cold start
+  });
+}, []);
+```
+
+Returns `true` when a pending FCM intent (Android) or PushKit payload (iOS) has not yet been consumed.
+
+#### Common Mistake: Manual or Automatic Login on Push
+
+The single most common integration bug is re-logging in while the SDK is already handling a push:
+
+```tsx
+// WRONG — runs on every mount, including push-launched cold starts
+React.useEffect(() => {
+  voipClient.login(config); // or loginFromStoredConfig(), or loginWithToken()
+}, []);
+```
+
+```tsx
+// Right — guard the login on push-launched cold starts
+React.useEffect(() => {
+  TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
+    if (!isFromPush) voipClient.loginFromStoredConfig();
+  });
+}, []);
 ```
 
+Symptoms of getting this wrong: the incoming call rings briefly then disappears, the socket disconnects mid-call, or CallKit shows a call that immediately ends.
+
 ### Authentication & Persistent Storage
 
 The library supports both credential-based and token-based authentication with automatic persistence for seamless reconnection.
@@ -273,17 +375,12 @@ The `TelnyxMainActivity` provides:
 
 ### 2. Push Notification Setup
 
-1. Place `google-services.json` in the project root
-2. Register background message handler:
+1. Place `google-services.json` in the project root.
+2. Create an FCM service that extends `TelnyxFirebaseMessagingService` and a notification action receiver that extends `TelnyxNotificationActionReceiver`, then register both in `AndroidManifest.xml`. See the [push notification app setup guide](../docs-markdown/push-notification/app-setup.md) for the full boilerplate.
 
-```tsx
-import messaging from '@react-native-firebase/messaging';
-import { TelnyxVoiceApp } from '@telnyx/react-voice-commons-sdk';
+> **Do not** register `messaging().setBackgroundMessageHandler(...)` from JS. Android push is handled entirely by the native `TelnyxFirebaseMessagingService` — adding a JS handler will fight the native layer and can double-process calls. There is no `TelnyxVoiceApp.handleBackgroundPush` step required on Android.
 
-messaging().setBackgroundMessageHandler(async (remoteMessage) => {
-  await TelnyxVoiceApp.handleBackgroundPush(remoteMessage.data);
-});
-```
+See [Push Notification Flow](#push-notification-flow) below for how to detect push-launched cold starts and avoid double-login.
 
 ### iOS Integration
 

package/android/src/main/java/com/telnyx/react_voice_commons/VoicePnBridgeModule.kt

@@ -9,17 +9,18 @@ import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.bridge.Arguments
+import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.modules.core.DeviceEventManagerModule
 
+@ReactModule(name = VoicePnBridgeModule.NAME)
 class VoicePnBridgeModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
     
     companion object {
+        const val NAME = "VoicePnBridge"
         private const val TAG = "VoicePnBridgeModule"
     }
-    
-    override fun getName(): String {
-        return "VoicePnBridge"
-    }
+
+    override fun getName(): String = NAME
     
     @ReactMethod
     fun getPendingPushAction(promise: Promise) {

package/lib/models/call.d.ts

@@ -171,6 +171,18 @@ export declare class Call {
    * Toggle mute state
    */
   toggleMute(): Promise<void>;
+  /**
+   * Send DTMF tones on this call.
+   *
+   * Each character in `digits` is sent as a Verto INFO message to the Telnyx
+   * platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other
+   * characters are silently dropped by the underlying SDK.
+   *
+   * Only valid while the call is `ACTIVE` — will throw otherwise. Safe to call
+   * with a single digit (e.g. for IVR dialpad presses) or a whole string
+   * (e.g. `"123#"`).
+   */
+  dtmf(digits: string): Promise<void>;
   /**
    * Set the call to connecting state (used for push notification calls when answered via CallKit)
    * @internal

package/lib/models/call.js

@@ -374,6 +374,28 @@ class Call {
       await this.mute();
     }
   }
+  /**
+   * Send DTMF tones on this call.
+   *
+   * Each character in `digits` is sent as a Verto INFO message to the Telnyx
+   * platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other
+   * characters are silently dropped by the underlying SDK.
+   *
+   * Only valid while the call is `ACTIVE` — will throw otherwise. Safe to call
+   * with a single digit (e.g. for IVR dialpad presses) or a whole string
+   * (e.g. `"123#"`).
+   */
+  async dtmf(digits) {
+    if (this.currentState !== call_state_1.TelnyxCallState.ACTIVE) {
+      throw new Error(`Cannot send DTMF in state: ${this.currentState}`);
+    }
+    try {
+      await this._telnyxCall.dtmf(digits);
+    } catch (error) {
+      console.error('Failed to send DTMF:', error);
+      throw error;
+    }
+  }
   /**
    * Set the call to connecting state (used for push notification calls when answered via CallKit)
    * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/react-voice-commons-sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A high-level, state-agnostic, drop-in module for the Telnyx React Native SDK that simplifies WebRTC voice calling integration",
   "main": "lib/index.js",
   "module": "lib/index.js",
@@ -39,7 +39,7 @@
     "android": "expo run:android",
     "ios": "expo run:ios",
     "dev:local": "npm pkg set dependencies.@telnyx/react-native-voice-sdk=file:../package",
-    "dev:published": "npm pkg set \"dependencies.@telnyx/react-native-voice-sdk\"=\">=0.4.1\"",
+    "dev:published": "npm pkg set \"dependencies.@telnyx/react-native-voice-sdk\"=\">=0.4.2\"",
     "prepublishOnly": "npm run dev:published && npm install --legacy-peer-deps",
     "postpublish": "npm run dev:local && npm install --legacy-peer-deps"
   },
@@ -86,7 +86,7 @@
   },
   "dependencies": {
     "@react-native-community/eslint-config": "^3.2.0",
-    "@telnyx/react-native-voice-sdk": ">=0.4.1",
+    "@telnyx/react-native-voice-sdk": ">=0.4.2",
     "eventemitter3": "^5.0.1",
     "expo": "~53.0.22",
     "react-native-url-polyfill": "^3.0.0",

package/src/models/call.ts

@@ -353,6 +353,30 @@ export class Call {
     }
   }
 
+  /**
+   * Send DTMF tones on this call.
+   *
+   * Each character in `digits` is sent as a Verto INFO message to the Telnyx
+   * platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other
+   * characters are silently dropped by the underlying SDK.
+   *
+   * Only valid while the call is `ACTIVE` — will throw otherwise. Safe to call
+   * with a single digit (e.g. for IVR dialpad presses) or a whole string
+   * (e.g. `"123#"`).
+   */
+  async dtmf(digits: string): Promise<void> {
+    if (this.currentState !== TelnyxCallState.ACTIVE) {
+      throw new Error(`Cannot send DTMF in state: ${this.currentState}`);
+    }
+
+    try {
+      await this._telnyxCall.dtmf(digits);
+    } catch (error) {
+      console.error('Failed to send DTMF:', error);
+      throw error;
+    }
+  }
+
   /**
    * Set the call to connecting state (used for push notification calls when answered via CallKit)
    * @internal