This page explains the key functions of group call consisting of how to create a room and how a user can participate in a group call by entering and exiting a room from your app.
Note: Tutorial is also available on how to build a Kotlin video group chat app.
Create a room
You can choose to create a room that supports up to 6 participants with video or a room that supports up to 100 participants with audio. When a user creates a room in your app, the room’s status becomes
OPEN and a
ROOM_ID is generated.
You can create a room through the Calls API as shown below by using the
List of properties
Retrieve a list of rooms
You can retrieve a list of rooms by using the
RoomListQuery and the following table shows all supported filters for the
RoomListQuery to search for specific rooms you want to retrieve.
List of filters
Query results to include rooms that match the specified room IDs.
Query results to include rooms with the specified room type.
Query results to include room with the specified room state.
Query results to include rooms that were created between the specified range of time.
Query results to include rooms with the specified range of numbers for current participants.
Query results to include rooms that were created by specified user IDs.
You can specify the above filters as shown below:
To retrieve a list of rooms, call the
When a list of rooms is retrieved, you can show the list to a user and allow the user to select a room they want to enter.
Note: The room data returned from the query is not updated unless the user has entered the room. To update the details about a room, call the
Enter a room
A user can search a room with a specific room ID to participate in a group call at any time. When a user enters a room, a participant is created with a unique participant ID to represent the user in the room.
To enter a room, you must first acquire the room instance from Sendbird server with the room ID. To fetch the most up-to-date room instance from Sendbird server, use the
SendBirdCall.fetchRoomById() method. Also, you can use the
SendBirdCall.getCachedRoomById() method that returns the most recently cached room instance from Sendbird Calls SDK.
Note: A user can enter the room using multiple devices or browser tabs. Entering from each device or browser tab will create a new participant.
Once the room is retrieved, call the
enter() method to enter the room.
Kick out siblings of the user
In a room, a single user can enter the same room multiple times as a different participant. However, if you want to prevent the user from entering the room simultaneously using different mobile devices and web browsers, you can kick out siblings of the user by calling
room.enter(). It will result the user to be the unique participant remaining in the room.
Note: Share the room ID with other users for them to enter the room from the client app.
Exit a room
To leave a room, call
room.exit(). On the room handlers of the remaining participants, the
RoomListener.onRemoteParticipantExited() method will be called.
Delete a room
If you would like to delete a room, you can call the
delete() method. When this method is called successfully, the room will be permanently deleted, all participants in the room will be exited automatically, and the media connection will be stopped. Any participants in the room can delete the room.
Handle events in a room
A user can receive events of a room that they are currently participating. Users will be notified when other participants enter or leave the room, change their media settings or when the room is deleted.
Add event listener
Add event listener for the user to receive events that occur in a room that the user joins as a participant.
Receive events on enter and exit
When a participant joins or leaves the room, other participants in the room will receive the following events.
Receive events on media settings
A local participant can change the media settings such as muting their microphone or turning off their camera by using
stopVideo(). Other participants will receive events that notify them of the corresponding media setting changes.
Receive events on local participant's connection status
A local participant may lose their media stream in the room if their network connection is unstable. The
onLocalParticipantDisconnected event listener will be sent to the local participant when they are disconnected. Once the media stream is reconnected, the
onLocalParticipantReconnected event listener will be sent.
You can use these events to alert the local participants to switch to a more stable network or take other appropriate actions to stay connected to the room. Implement the code below to receive events on local participant's connection status.
Receive events on deleted room
To delete a room through Calls Platform API, see Delete a room in the Calls API documentation. When a room is deleted, participants in the room will receive the following event.
Remove event listener
To stop receiving events about a room, remove the registered listeners as shown below:
Invite users with notifications
You can let users into a room by sharing the room ID or by sending invitation to certain users as a notification. Invitees can accept or decline your invitations and you can also cancel them.
Invite a user
First, you need to be in the room to which you would like to invite other users. Follow the steps in Create a room and Enter the room to invite other users.
Send an invitation with the invitee's user ID and the room ID to the user you want to invite. When the invitation is sent successfully, the invited user will receive a notification on their device notifying them that you've invited them to join a room.
In order to send push notifications, you must configure the push notification certificates on Sendbird Dashboard and upload the device's push tokens after you authenticate. Refer to our notifications guide for more information.
Show the invitation to the invitee
When a user is invited, they will receive a notification that shows information about who invited them to which room. To show such information, you must pass the push notification to Sendbird Calls SDK as shown below.
When the push notification is passed to the Calls SDK, the
onInvitationReceived handler will be called and the option will automatically be shown to the invitee to accept or decline the invitation.
When the notification pops on the invitee's device, a
RoomInvitation class is created in the class that you added event handlers for the room. If you would like to provide information in the
RoomInvitation class on other screens, you need to retrieve the class by using
SendbirdCall.getRoomInvitation(roomInvitationId: String) as shown below.
Cancel an invitation
If you would like to cancel an invitation that you sent, follow the code below. When you cancel the invitation, the invited user won't be able to enter the room when they open the notification.
Accept or decline the invitation
When the invited user accepts or declines the invitation, the user who invited them will be notified. You can add UI updates to let the inviter know whether the user they invited accepted or declined the invitation.
room.enter() to let the invitee enter the room once the invitee accepts the invitation. After the invitee enters and gets connected to the room, the inviter and invitee will be able to view each other's media stream.
List of event handlers
Invoked when the invitee accepts the invitation to enter the room.
Invoked when the invitee declines the invitation to enter the room.
Manage custom items
With custom items for group calls, you can store additional information as key-value pairs to a room in the
Room object. Custom key-value items are saved as a
Map<String, String> and can be updated or deleted as long as the room status is
OPEN. Information related to customer service, refund, or inquiry can be added as custom items for better user experience.
When a room is created, users can add custom items in
RoomParams as a
Map<String, String>. By default, the
customItems is an empty
Update and delete
Custom items can be updated or deleted as long as the room status is
OPEN. If a new custom item has the same key as the existing custom item, the new item will update the value of the existing item. A new item with a new key will be added to the list of custom items. You can update existing custom items by calling the
room.updateCustomItems(Map<String, String>, CustomItemsHandler).
You can delete custom items by calling the
room.deleteCustomItems(Map<String, String>, CustomItemsHandler) with the list of keys that you want to delete from the existing custom items.
A participant in a room can receive events from Sendbird server when other participants update or delete custom items in the room. Implement the
RoomListener.onCustomItemsUpdated(List<String>) and the
RoomListener.onCustomItemsDeleted(List<String>) from the
RoomListener to receive events from other participants. Each event contains the list of keys of the changed custom items, such as
Custom items can be modified and the events are delivered to the
RoomListener only when the room's status is
OPEN and there are participants in the room. To check the custom items that had been changed for ended or ongoing calls in a room, you can use the Calls API or the
Interact within a room
Participant’s actions, such as turning on or off their microphone or camera, in a room are handled by the participant objects.
To control the media of a local user, you can use the following methods from the
Display video view
When there is a participant in the room, a media stream is established between a participant and Sendbird server to support group calls.You can configure the user interface for participants in a room by using the properties in
Receive media stream
The following is the process of how participants can send and receive media streams in a room:
Step 1: To send a media stream, a participant who would like to send its media stream has to be connected to Sendbird server.
Step 2: To receive a media stream, a participant who would like to receive a media stream from another participant has to be connected to the media server. Once connected,
onRemoteParticipantStreamStarted() will be invoked which notifies that the receiving media stream has started.
Step 3: Add a view to show the received media stream.
To receive a video stream from a local participant, configure
videoView property as shown below:
To receive a video stream from a remote participant, configure the
videoView property as shown below:
Manage video layout
You can show participants in gallery view as they enter or exit the room by using
GridLayoutManager which dynamically change views. You can set the number of items to be the count of
room.participants and the custom
ViewHolder to represent each participant.
When the below methods in
RoomListener are called, information for
room.participants gets updated and the number of items are changed accordingly. To have the custom
ViewHolder added or removed, you need to call
adapter.notifyDataSetChanged() for the methods.
List of methods
Invoked when a remote participant has entered a room.
Invoked when a remote participant has exited a room.
Invoked when a remote participant has started media streaming.
Invoked when a remote participant's audio settings have changed.
Invoked when a remote participant's video settings have changed.
Show default image for user
If a participant is not connected to the call or has turned off their video, you can set a default image to show on the screen for that participant. Otherwise, it will be shown as black to other participants. To check whether a participant has turned on their video or is connected to the room for a video call, refer to the
isVideoEnabled and the
state properties of a
It is recommended to show an image such as the user’s profile image as the default image when the
onRemoteParticipantEntered() method is invoked.
onRemoteParticipantStreamStarted() method is invoked, create a new
SendBirdVideoView and set it to the participant by using
participant.videoView and remove the default image.
Reconnect to media stream
When a participant loses media stream in a room due to connection issues, Sendbird Calls SDK automatically tries to reconnect the participant’s media streaming in the room. If the Calls SDK fails to reconnect for about 40 seconds, an error will be returned.
Note: See the Error codes page for more information.
Cloud recording is a feature that allows you to record participants' audio and video in rooms and download the recorded files from Sendbird Dashboard. When the feature is turned on in a Sendbird application, audio of
LARGE_ROOM_FOR_AUDIO_ONLY and audio and video of
SMALL_ROOM_FOR_VIDEO are recorded.
To use the cloud recording feature, contact our support team. You can go to Settings > Calls > General on the dashboard to see if the feature is available for your Sendbird application.
Recording starts in
Open rooms when there are more than two participants in the room, and ends when there are no participants. Recorded files will be numbered in the file name and listed in the order of creation.
Download the recorded file
Once the file has been uploaded successfully, you can download it from the dashboard. To download the file, click the room of the recording you would like to download on Group calls. You can download the file immediately or later by using the link, which stays valid for 24 hours and can be reissued.
File spec and retention
Audio recordings from
LARGE_ROOM_FOR_AUDIO_ONLY are processed to
.aac files and audio and video recordings from
SMALL_ROOM_FOR_VIDEO are processed to
.mp4 files in default resolution of 1280 x 720. Each file can be downloaded for two weeks from the date the recorded file's upload has completed.