Overview

Incoming Calls

Build apps with ringing call support. Recipients receive incoming call notifications when a call is initiated.

For implementation details, see the ringing guide.

Best Practices

• Configure push providers - Set up Firebase (Android) and APNs/VoIP (iOS) for background notifications
• Handle all app states - Support foreground, background, and terminated states
• Use unique call IDs - Avoid reusing call IDs to prevent unexpected behavior
• Request permissions early - Request notification permissions at an appropriate point in your app flow
• Test on real devices - Push notifications require physical devices for testing

Ringing Options

Incoming call presentation depends on app configuration and state (foreground, background, or terminated).

In-app Incoming Calls

Display custom incoming call screens when the app is in the foreground. Triggered by ringing WebSocket events with full control over design and behavior. See RingingCallContent for customization.

CallKit Integration (iOS)

For iOS apps Apple's CallKit framework can be integrated. CallKit enables the app to handle system-level incoming call screens by sending a VoIP push notification from the server, which wakes up the app. While CallKit provides limited UI customization, it ensures consistent behavior across iOS devices. To learn more about integrating Stream Video with CallKit, refer to the guide for your app below:

• Vanilla React Native Guide
• Expo Guide

Firebase & Telecom Integration (Android)

For Android apps running in the background or terminated, Firebase push notifications can be used to handle ringing. These notifications let users join or decline the call and can also launch the app if needed. Android Telecom framework allows to register a call on a system level providing additional capabilities for managing call state across several devices (Android Auto/Wear OS).
For step-by-step integration instructions, refer to the guide according to your app below:

• Vanilla React Native Guide
• Expo Guide

Non-Ringing Push Notifications

In addition to ringing calls, Stream Video can send push notifications for non-ringing events:

Unlike ringing calls (which the SDK handles via CallKit/Telecom), non-ringing notifications are entirely the app's responsibility. The Stream backend sends the push notification directly to the device via Firebase (Android) or APNs (iOS). The SDK does not process or display these notifications — your app needs to receive the push, display a notification, and handle user interaction.

What you need to do

1. Obtain and register the device token — You need to obtain the push token for your platform and register it with the Stream backend via client.addDevice(). On Android this is the Firebase token; on iOS this is the APN device token. Use any library or custom native code to obtain the token (e.g. @react-native-firebase/messaging, expo-notifications, @react-native-community/push-notification-ios). If you already have the ringing call setup configured, the SDK registers the Firebase token (Android) and VoIP token (iOS) automatically — but on iOS you still need to register a separate APN token for non-ringing notifications. If ringing is not set up, you need to register the device token on both platforms yourself.
2. Handle the incoming push when it arrives and display a local notification with appropriate content
3. Handle notification taps to navigate the user to the relevant screen