Expo

Add push notifications for ringing calls to your Expo project. Covers both Android and iOS setup.

Users receive push notifications for incoming calls and can accept or reject directly from the notification.

Android preview	iOS preview

Add push provider credentials to Stream

Follow these guides to add push providers:

• Android - Firebase Cloud Messaging
• iOS - Apple Push Notification Service (APNs)

Install Dependencies

npx expo install \
  @react-native-firebase/app \
  @react-native-firebase/messaging \
  @stream-io/react-native-callingx

Package purposes:

• @react-native-firebase/app and @react-native-firebase/messaging for handling incoming Firebase Cloud Messaging notifications on Android.
• @stream-io/react-native-callingx for registering calls in iOS CallKit and Android Telecom.

Add Firebase credentials

1. Create a Firebase project at Firebase console
2. Add your Android app in Project settings > Your apps. Use the same package name as android.package in app.json
3. Download google-services.json to your project root
4. Add to app.json:

{
  "android": {
    "googleServicesFile": "./google-services.json"
  }
}

5. For iOS, add your Apple app in Project settings > Your apps. Use the same bundle ID as ios.bundleIdentifier in app.json
6. Download GoogleService-Info.plist to your project root
7. Add to app.json:

{
  "ios": {
    "googleServicesFile": "./GoogleService-Info.plist"
  }
}

iOS - Notifications entitlement

For Expo SDK 51+, add the notifications entitlement to app.json:

{
  "expo": {
    "ios": {
      "entitlements": {
        "aps-environment": "production"
      }
    }
  }
}

Add the config plugin properties

In app.json, in the plugins field, add the ringing property to the @stream-io/video-react-native-sdk plugin.

{
  "plugins": [
    [
      "@stream-io/video-react-native-sdk",
      {
        "ringing": true
      }
    ],
    [
      "@config-plugins/react-native-webrtc",
      {
        "cameraPermission": "$(PRODUCT_NAME) requires camera access in order to capture and transmit video",
        "microphonePermission": "$(PRODUCT_NAME) requires microphone access in order to capture and transmit audio"
      }
    ],
    "@react-native-firebase/app",
    "@react-native-firebase/messaging",
    [
      "expo-build-properties",
      {
        "ios": {
          "useFrameworks": "static",
          "forceStaticLinking": [
            "RNFBApp",
            "RNFBMessaging",
            "stream-react-native-webrtc"
          ]
        }
      }
    ]
    // your other plugins
  ]
}

Optional: Disable Firebase integration on iOS

Disable Firebase APNs registration since iOS uses VoIP push. Create firebase.json:

{
  "react-native": {
    "messaging_ios_auto_register_for_remote_messages": false
  }
}

Add Firebase message handlers

Add SDK utility functions to Firebase notification listeners:

import messaging from "@react-native-firebase/messaging";
import {
  isFirebaseStreamVideoMessage,
  firebaseDataHandler,
} from "@stream-io/video-react-native-sdk";

export const setFirebaseListeners = () => {
  // Set up the background message handler
  messaging().setBackgroundMessageHandler(async (msg) => {
    if (isFirebaseStreamVideoMessage(msg)) {
      await firebaseDataHandler(msg.data);
    } else {
      // your other background notifications (if any)
    }
  });

  // Optionally: set up the foreground message handler
  messaging().onMessage((msg) => {
    if (isFirebaseStreamVideoMessage(msg)) {
      firebaseDataHandler(msg.data);
    } else {
      // your other foreground notifications (if any)
    }
  });
};

Firebase message handlers:

• The onMessage handler should not be added if you do not want notifications to show up when the app is in the foreground. When the app is in foreground, you would automatically see the incoming call screen.
• The isFirebaseStreamVideoMessage method is used to check if this push message is a video related message. And only this needs to be processed by the SDK.
• The firebaseDataHandler method is the callback to be invoked to process the message. This callback reads the message and display push notifications.

setFirebaseListeners.android.ts
setFirebaseListeners.ts

export const setFirebaseListeners = () => {
  // do nothing
};

Setup the push notifications configuration for the SDK

The SDK automatically processes the incoming push notifications once the setup above is done if the push notifications configuration has been set using StreamVideoRN.setPushConfig. Also you can override the default notification texts and adjust ringtone for both iOS CallKit and Android Telecom.

Below is an example of how these methods can be called:

import {
  StreamVideoClient,
  StreamVideoRN,
  User,
} from "@stream-io/video-react-native-sdk";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { STREAM_API_KEY } from "../../constants";

export function setPushConfig() {
  StreamVideoRN.setPushConfig({
    ios: {
      // add your push_provider_name for iOS that you have setup in Stream dashboard
      pushProviderName: __DEV__ ? "apn-video-staging" : "apn-video-production",
      supportsVideo: true,
      callsHistory: true,
      displayCallTimeout: 60000,
    },

    android: {
      // add your push_provider_name for Android that you have setup in Stream dashboard
      pushProviderName: __DEV__
        ? "firebase-video-staging"
        : "firebase-video-production",
      incomingChannel: {
        id: "incoming_call_channel",
        name: "Call notifications",
        vibration: true,
      },
      notificationTexts: {
        accepting: "Connecting...",
        rejecting: "Declining...",
      },
    },

    shouldRejectCallWhenBusy: true,
    enableOngoingCalls: true,

    // add the async callback to create a video client
    // for incoming calls in the background on a push notification
    createStreamVideoClient: async () => {
      const userId = await AsyncStorage.getItem("@userId");
      const userName = await AsyncStorage.getItem("@userName");
      if (!userId) return undefined;

      // an example promise to fetch token from your server
      const tokenProvider = async (): Promise<string> =>
        yourServerAPI.getTokenForUser(userId).then((auth) => auth.token);

      const user: User = { id: userId, name: userName };
      return StreamVideoClient.getOrCreateInstance({
        apiKey: STREAM_API_KEY, // pass your stream api key
        user,
        tokenProvider,
        options: { rejectCallWhenBusy: true },
      });
    },
  });
}

iOS calling experience options:

• supportsVideo - tells CallKit that video calls should be supported. Affects system UI and routing. Default value is true.
• callsHistory - enables calls history. When enabled, all registered calls will be displayed in recent calls section in default dial app. Default value is false.
• displayCallTimeout – timeout value in ms which will be used to hide system UI if JS is not loaded during that time. Default value is 60000.
• sound - ringtone resource name that will be used by CallKit. Detailed instructions are provided on CallKit options page.
• imageName - image resource name that will be used on CallKit dialer UI. Detailed instructions are provided on CallKit options page.

Android calling experience options:

• incomingChannel.id - notification channel id for incoming calls
• incomingChannel.name - notification channel name
• incomingChannel.sound - ringtone resource name that will be used for ringing notification. Detailed instructions are provided on Android custom ringtone page.
• incomingChannel.vibration - enables vibration for notification channel
• notificationTexts – allows to override default texts displayed in notifications for accepting/declining intermediate state. By default, Connecting... and Declining... will be displayed for corresponding state.
• titleTransformer - allows you to modify displayed notification title. Receives member name and incoming boolean flag as parameters. By default, just returns the member name value.

General calling experience options:

• shouldRejectCallWhenBusy – blocks new incoming calls in cases when there is an active ongoing call. Default value is false. For setting up call interruption behavior on a client level, please check Reject call when busy. Note: for consistent behavior, this flag should be defined both in the client constructor and in setPushConfig call.
• enableOngoingCalls – enables CallKit/Telecom support for outgoing calls. Default value is false.

Initialize SDK push notification methods

Call the methods we have created outside your application cycle. That is, alongside your AppRegistry.registerComponent() method call at the entry point of your application code. A root file index.js is a good place do this as the app can be opened from a dead state through a push notification, and in that case, we need to use the configuration and notification callbacks as soon as the JS bridge is initialized.

import { setPushConfig } from "./utils/setPushConfig";
import { setFirebaseListeners } from "./utils/setFirebaseListeners";

setPushConfig();
setFirebaseListeners();

// always import expo-router/entry at the end of the file
import "expo-router/entry";

The index.js file must be made as the entry point file to your app. This can be done via editing the main property in the package.json file:

{
  ...
  "main": "index.js",
  ...
}

Disabling push notifications

Disable push on user logout or user switch:

import { StreamVideoRN } from "@stream-io/video-react-native-sdk";

await StreamVideoRN.onPushLogout();

Android full-screen incoming call view on locked phone

Incoming and Outgoing call UI in foreground

Show call UIs during ringing calls. See watching for calls for implementation.

Testing Ringing calls

To test properly:

• Use a real physical device (APNs do not work in simulators).
• Ensure your Firebase/APNs credentials are correctly configured in the Stream Dashboard.
• Ensure your iOS provisioning profile includes Push Notifications capability and the aps-environment entitlement.

For the best experience, run the Android and iOS app without the metro bundler to the respective physical devices using the following command:

To generate native code directories:

npx expo prebuild --clean

For iOS:

npx expo run:ios --no-bundler --device --configuration Release

For Android:

npx expo run:android --no-bundler --device --variant release

Troubleshooting

See the Troubleshooting guide for common issues.