Group call

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 25 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 by setting the room type by using the Type property and the createRoom() method as shown below.

let roomType = RoomType.smallRoomForVideo
let params = RoomParams(roomType: roomType)
SendBirdCall.createRoom(with: params) { room, error in
    guard let room = room, error == nil else { return } // Handle error.
    // `room` is created with a unique identifier `room.roomId`.
}

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 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.fetchRoom(by:completionHandler:) method. Also, you can use the SendBirdCall.getCachedRoom(by:) method that returns the most recently cached room instance from Sendbird Calls SDK.

SendBirdCall.fetchRoom(by: ROOM_ID) { room, error in
    guard let room = room, error == nil else { return } // Handle error.
    // `room` with the identifier `ROOM_ID` is fetched from Sendbird Server.
}

let cachedRoom: Room? = SendBirdCall.getCachedRoom(by: ROOM_ID)
// Returns the most recently cached room from the SDK.
//If there is no such room with the given room ID, `nil` is returned.

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(with:completionHandler:) method to enter the room.

let params = Room.EnterParams(isVideoEnabled: true, isAudioEnabled: true)
room.enter(with: params) { error in
    guard error == nil else { return } // Handle error.
    // User has successfully entered `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 delegates of the remaining participants, the RoomDelegate.didRemoteParticipantExit(_:) method will be called.

do {
    try room.exit()
    // participant has exited the room successfully.
} catch {
    // SBCError.participantNotInRoom is thrown because participant has not entered the room.
}

You can retrieve a list of the rooms by using RoomListQuery and the following table shows all supported filters for RoomListQuery to search for specific rooms you want to retrieve.

You can specify the above filters as shown below:

let params = RoomListQuery.Params()
            .setType(.largeRoomForAudioOnly)
            .setLimit(50)
            .setState(.open)
            .setRangeForCurrentParticipantCount(3...)
            .setCreatedByUserIds([USER_ID1, USERID2])
            .setRangeForCreatedAt(..<Date())

To retrieve a list of rooms, call the RoomListQuery.next(completionHandler:) method.

let query = SendBirdCall.createRoomListQuery(with: params)
if query?.hasNext == true, query?.isLoading == false {
    query?.next{ rooms, error in
        guard let rooms = rooms, error == nil else {
            // Error has occurred
            return
        }
        ...
    }
}

When a list of rooms is retrieved, you can show the list to a user and directly let them enter the room.

rooms.first?.enter(with: .init()) { error in
    // User has entered the room.
}

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 SendBirdCall.fetchRoom(by:completionHandler:) method.

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 Room.localParticipant object:

// Mutes the local participant's microphone.
room.localParticipant.muteMicrophone()

// Unmutes the local participant's microphone.
room.localParticipant.unmuteMicrophone()

// Stops the local participant's video.
room.localParticipant.stopVideo()

// Starts the local participant's video.
room.localParticipant.startVideo()

// Switches between the front and back camera.
room.localParticipant.switchCamera(completionHandler: ErrorHandler)

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 Participant.

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 didRemoteParticipantStreamStart(_:) method will be invoked which notifies that the receiving media stream has started.

Step 3: Add a view to show the received media stream.

class MyClass: RoomDelegate {
    // Called when a remote participant is connected to the media stream and starts sending the media stream.
    func didRemoteParticipantStreamStart(_ participant: RemoteParticipant) { }
}

You can receive a video stream from a participant by configuring the videoView property as shown below:

@IBOutlet weak var participantVideoView: UIView?

// Create SendBirdVideoView.
let participantSendBirdVideoView = SendBirdVideoView(frame: self.participantVideoView?.frame ?? CGRect.zero)
self.participantVideoView?.embed(participantSendBirdVideoView)

// Configure participants video view.
// participant: Participant
participant.videoView = participantSendBirdVideoView

You can show participants in gallery view as they enter or exit the room by using UICollectionView which dynamically changes views. You can set the number of items to be the count of room.participants and the custom cells to represent each participant.

When the below methods in RoomDelegate are called, information for room.participants gets updated and the number of items are changed accordingly. To have the custom cells added or removed, you need to call UICollectionView.reloadData() for the delegate methods.

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 Participant object.

It is recommended to show an image such as the user’s profile image as the default image when the didRemoteParticipantEnter(_:) delegate method is invoked.

When the didRemoteParticipantStreamStart(_:) delegate method is invoked, create a new UIImageView and set it to the participant by adding it as a subview on the UITableView or UICollectionView cell.

A user can receive events such as other participants entering or leaving the room or changing their media settings only about a room that the user currently participates in.

Add an event delegate for the user to receive events that occur in a room that the user joins as a participant.

room.addDelegate(myClass, identifier: UNIQUE_IDENTIFIER)

class MyClass: RoomDelegate {
}

When a participant joins or leaves the room, other participants in the room will receive the following events.

class MyClass: RoomDelegate {
    // Called when a remote participant has entered the room.
    func didRemoteParticipantEnter(_ participant: RemoteParticipant) { }

    // Called when a remote participant has exited the room.
    func didRemoteParticipantExit(_ participant: RemoteParticipant) { }
}

A local participant can change the media settings such as muting their microphone or turning off their camera by using muteMicrophone() or stopVideo(). Other participants will receive event delegates that notify them of the corresponding media setting changes.

class MyClass: RoomDelegate {
 // Called when audio settings of a remote participant have been changed.
    func didRemoteAudioSettingsChange(_ participant: RemoteParticipant) { }

    // Called when video settings of a remote participant have been changed.
    func didRemoteVideoSettingsChange(_ participant: RemoteParticipant) { }
}

To stop receiving events about a room, remove the registered delegates as shown below:

// Removes registered delegate that has the matching identifier.
room.removeDelegate(identifier: UNIQUE_IDENTIFIER)

// Removes all registered delegates to stop receiving events about a room.
room.removeAllDelegates()

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.

class MyClass: RoomDelegate {
    // Called when an error has occurred.
    func didReceiveError(_ error: SBCError, participant: Participant?) {
        // Clear resources for group calls.
    }
}

Note: See the Error codes page for more information.