Ringing

Ringing

To create a ringing call, follow the same steps as in the basic call flow, with the addition of the ringing and memberIds parameters in the getOrCreateCall() method.

final call = StreamVideo.instance.makeCall(callType: StreamCallType.defaultType(), id: 'Your-call-ID');
await call.getOrCreate(memberIds: ['user1_id', 'user2_id'], ringing: true, video: true);

• Setting ringing to true prompts Stream to send a notification to the call members, triggering the platform’s call screen on iOS and Android.
• The notification specifies whether the call is a video call or audio-only, based on the video parameter (true for video, false for audio-only).
• memberIds is a list of user IDs to be added to the call. When combined with the ringing parameter, it triggers ringing on the devices of these members.

If the call already exists, the method will just get it and sends the notifications.

Notifying users

In some scenarios, you may prefer to notify users about joining a call without triggering ringing. To achieve this, use the notify option:

final call = StreamVideo.instance.makeCall(callType: StreamCallType.defaultType(), id: 'Your-call-ID');
await call.getOrCreate(memberIds: ['user1_id', 'user2_id'], notify: true);

When notify is set to true, Stream sends a regular push notification to all members. This is particularly useful for use cases like livestreams or huddles.

Listening to Ringing Events

When the app is active, a WebSocket event (CoordinatorCallRingingEvent) is sent if someone rings the currently logged-in user. You can listen to this event to display an in-app call screen:

final subscription = StreamVideo.instance.events.listen((event) {
    if (event is CoordinatorCallRingingEvent) {
        print(event);
    }
});

// Remember to cancel the subscription when no longer needed.
subscription.cancel();

The CoordinatorCallRingingEvent includes a video boolean property (provided in getOrCreate() method), indicating whether the call includes video or is audio-only. You can use this information to customize the in-app call screen.

Additionally, you can listen for incomingCall events from the StreamVideo object’s state. This provides a Call object for the incoming call:

final subscription = StreamVideo.instance.state.incomingCall.listen((call) {
    // Replace with navigation flow of your choice
    Navigator.push(
        context,
        MaterialPageRoute(builder: (context) => CallScreen(call)),
    );
});

// Remember to cancel the subscription when no longer needed.
subscription.cancel();

UI Components

By navigating to a screen containing our StreamCallContainer and passing the incoming call, an incoming call screen is displayed automatically. For outgoing calls, use StreamCallContainer with the call used to initiate ringing to show an outgoing call screen.

Find more details in our UI docs: Incoming Call and Outgoing Call.

Auto-ending the call

By default, a call initiated with the ringing flow ends automatically when only one participant remains. To disable this behavior, set the dropIfAloneInRingingFlow flag to false in CallPreferences:

final call = streamVideo.makeCall(
    callType: StreamCallType.defaultType(),
    id: 'CALL_ID',
    preferences: DefaultCallPreferences(dropIfAloneInRingingFlow: false),
);