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.
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 using the
If you want to create a room with the
LARGE_ROOM_FOR_AUDIO_ONLY room type, you need to set the HTMLAudioElement for the room.
Sets audio when creating a large 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.
Note: Share the room ID with other users for them to enter the room from the client app.
To leave a room, call
Room.exit(). On the room event listeners of the remaining participants, the
remoteParticipantExited event listener will be called.
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 an object 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 an object. By default, the
customItems is an empty object.
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
You can delete custom items by calling the
room.deleteCustomItems(customItemKeys) 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
room.on('customItemsUpdated', handler) and
room.on('customItemsDeleted', handler) to receive events from other participants. Each event contains the list of keys of the updated or deleted custom items in the
Custom items can be modified and the events are delivered to the event handlers 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
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.
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
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 the local user, you can use the following methods from the
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
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, the
remoteParticipantStreamStarted event listener will be invoked which notifies that the receiving media stream has started.
Step 3: Add a view to show the received media stream. You can receive a video stream from a participant by using the
setMediaView() method as shown below:
Note: A media view element is a HTMLMediaElement such as
<video>to display media stream. The
participant.setMediaView()is required for the media stream to be displayed. It is also recommended to set a media view element’s
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
VideoEnabled 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
remoteParticipantEntered event listener is invoked.
remoteParticipantStreamStarted event listener is invoked, create a new
HTMLMediaView and set it to the participant by using the
participant.setMediaView() method and remove the default image.
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 an event listener for the user to receive events that occur in a room that the user joins as a participant.
When a participant joins or leaves the room, other participants in the room will receive the following events.
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 event listeners that notify them of the corresponding media setting changes.
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.
To stop receiving events about a room, remove the registered listeners as shown below:
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.