Room Management (Android)
RoomStore handles all room-related operations in AtomicXCore, offering a comprehensive set of APIs for managing the entire lifecycle of conference rooms—from creation to dissolution. Using RoomStore, you can efficiently build a robust room management system with features like retrieving and updating room details.Core Features
Create and Join Room: The host can use this API to create a room and join it immediately.
Join Room: Members can use this API to enter an existing room.
Leave Room: Members can use this API to exit a room they have joined.
End Room: The host can use this API to end the current room. All other members will receive the
onRoomEnded event.Update Room Information: Hosts or administrators can update room details. Currently, only the room name can be updated.
Get Room Information: Retrieve detailed information about a room.
Core Concepts
Before integrating RoomStore, review these key concepts:
Core Concept | Type | Core Responsibilities & Description |
data class | Data model representing room information, including all details and state management. Key features: Room info management (ID, name, creator). Real-time status tracking (member count, room status, creation time). Permission control (device and message management) . | |
data class | Maintains the user's room-related state. Key property: currentRoom represents the room state for the current user. | |
abstract class | Represents real-time events related to room activity. | |
abstract class | The main class for managing the entire room lifecycle. Supports room management operations and real-time event subscriptions via RoomListener. |
Implementation Steps
Step 1: Component Integration
Follow the Integration Overview to integrate the AtomicXCore SDK. Make sure you have completed the Implement Login Logic before proceeding.
Step 2: Host Create and Join Webinar Room
Implementation
1. Configure Room Initialization Parameters: Initialize
CreateRoomOptions to set the room name and other attributes.2. Set Room Permissions and Member Management: Define global member permissions, such as muting all members or disabling all cameras.
3. Create and Join Room: Call RoomStore's
createAndJoinRoom API to perform the operation.Note:
We recommend generating the roomID on your backend for global uniqueness and stability.
Prefix webinar room IDs with
webinar_ to distinguish them from standard meeting rooms.Sample Code
import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.CreateRoomOptionsimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomTypeprivate val roomID = "webinar_123456"private val roomType = RoomType.WEBINARfun createAndJoinRoom() {// 1. Configure room creation parameters// CreateRoomOptions defines basic room attributes and member management settingsval options = CreateRoomOptions(roomName = "Team Meeting Room", // Room display name// 2. Set initial room permission controlsisAllCameraDisabled = false, // Disable all members' camerasisAllMessageDisabled = false, // Mute all membersisAllMicrophoneDisabled = false, // Mute all membersisAllScreenShareDisabled = false // Disable screen sharing for all members)// 3. Call RoomStore to create and join the room// This method automatically handles room creation (if it doesn't exist) and joining logicRoomStore.shared().createAndJoinRoom(roomID, roomType, options, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Room created and joined successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to create and join room [Error code: $code]: $desc")}})}
Note:
Member management settings apply only to regular members; hosts and administrators are not restricted. To adjust member settings or manage individual member permissions after room creation, see the Member Management documentation.
createAndJoinRoom API Parameter Details
Parameter Name | Type | Required | Description |
roomID | String | Yes | Unique room identifier. Length: 0–48 bytes. Use only numbers, English letters (case-sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
roomType | RoomType | Yes | Room type: STANDARD: Standard room.WEBINAR: Large webinar room.For webinar scenarios, use WEBINAR. |
options | CreateRoomOptions | Yes | Room creation configuration. See CreateRoomOptions struct for details. |
completion | CompletionHandler | No | Completion callback. Returns the result of create and join operation. If failed, returns error code and message. |
CreateRoomOptions Struct Details
Parameter Name | Type | Required | Description |
roomName | String | No | Room name (optional, defaults to empty). Length: 0–60 bytes. Supports Chinese, English, numbers, and special characters. |
password | String | No | Room password. Empty string means no password. Length: 0–32 bytes. For easy mobile input, use 4–8 digits. If set, users must enter the password to join. Do not store sensitive info in plain text. Passwords are not supported for webinar rooms; leave empty. |
isAllMicrophoneDisabled | Boolean | No | Disable microphones for all members (except host/administrators): true: Disabled. false: Enabled (default). |
isAllCameraDisabled | Boolean | No | Disable cameras for all members (except host/administrators): true: Disabled. false: Enabled (default). |
isAllScreenShareDisabled | Boolean | No | Disable screen sharing for all members (only host/administrators can share): true: Disabled. false: Enabled (default). |
isAllMessageDisabled | Boolean | No | Mute all members (disable chat): true: Disabled. false: Enabled (default). |
Step 3: Audience Join Webinar Room
Audience members can join a webinar room by calling RoomStore's
joinRoom API.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomTypeprivate val roomID = "webinar_123456"private val roomType = RoomType.WEBINARfun joinRoom() {// 1. Prepare parameters for joining the room// joinRoom is used to join a known and ongoing room// 2. Call RoomStore to join the roomRoomStore.shared().joinRoom(roomID, roomType, completion = object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Joined room successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to join room [Error code: $code]: $desc")}})}
Note:
After entering the room, audience members are in a silent listening state and cannot enable their microphone or camera by default. They can raise their hand to request permission; after host approval, they become a guest and can turn on their microphone. Role changes are handled via
RoomParticipantState. For details, see Member Management.joinRoom API Parameters
Parameter Name | Type | Required | Description |
roomID | String | Yes | Unique room identifier. Length: 0–48 bytes. Use only numbers, English letters (case-sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
roomType | RoomType | Yes | Room type: STANDARD: Standard room.WEBINAR: Large webinar room.For webinar scenarios, use WEBINAR. |
password | String | No | Room password. Empty string means no password. Length: 0–32 bytes. Use 4–8 digits for easy input. If set, users must enter the password to join. Do not store sensitive info in plain text. Passwords are not supported for webinar rooms; leave empty. |
completion | CompletionHandler | No | Completion callback. Returns the result of join operation. If failed, returns error code and message. |
Step 4: Leave Room
To leave a room, call RoomStore's
leaveRoom API.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerfun leaveRoom() {// 1. Business logic description// leaveRoom is used for regular members or hosts to voluntarily exit the room// Unlike endRoom, when the host calls leaveRoom, only they leave; the room remains active// 2. Call RoomStore to leave the room// This operation stops audio/video streams and notifies the server to remove the current user from the roomRoomStore.shared().leaveRoom(object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Left room successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to leave room [Error code: $code]: $desc")}})}
Step 5: End Room
When the host wants to dissolve the room, call RoomStore's
endRoom API. After the room ends, all members receive a room ended event.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStorefun endRoom() {// 1. Business logic description// endRoom is used to permanently dissolve the current room// Note: This operation is typically restricted to the host (Owner); after dissolution, all members are forcibly removed// 2. Call RoomStore to dissolve the room// This method sends a dissolution command to the server and notifies all online members that the room has endedRoomStore.shared().endRoom(object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Room dissolved successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to dissolve room [Error code: $code]: $desc")}})}
Note:
If the host leaves the room without calling endRoom, the room remains active until it meets the auto-recycle condition (default: 10 minutes, configurable via backend).
Webinar rooms do not currently support host transfer.
Step 6: Update Room Information
To update the room name, the host can call RoomStore's
updateRoomInfo API. All room members will receive a room state change notification after the update.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.UpdateRoomOptionsimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerprivate val roomID = "webinar_123456"fun updateRoomInfo() {// 1. Configure room update parameters// UpdateRoomOptions is used to define which room attributes to updateval options = UpdateRoomOptions(roomName = "New Webinar Name" // Update room display name)// 2. Set modification flags// modifyFlagList specifies which fields to update, supports combining multiple flagsval modifyFlagList = listOf(UpdateRoomOptions.ModifyFlag.ROOM_NAME)// 3. Call RoomStore to update room information// This method submits the update request to the server and synchronizes it to all room membersRoomStore.shared().updateRoomInfo(roomID, options, modifyFlagList, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Room information updated successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to update room information [Error code: $code]: $desc")}})}
updateRoomInfo API Parameter Details
Parameter Name | Type | Required | Description |
roomID | String | Yes | Unique room identifier. Length: 0–48 bytes. Use only numbers, English letters (case-sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
options | UpdateRoomOptions | Yes | Room property update configuration. See UpdateRoomOptions struct for details. |
modifyFlagList | List | Yes | Specifies which properties to update. Webinar rooms currently support updating the room name. See ModifyFlag documentation for usage. |
completion | CompletionHandler | No | Completion callback. Returns the result of the update operation. If failed, returns error code and message. |
UpdateRoomOptions Struct Details
Parameter Name | Type | Required | Description |
roomName | String | No | Room name (optional, defaults to empty). Length: 0–60 bytes. Supports Chinese, English, numbers, and special characters. |
password | String | No | Room password. Empty string means no password. Length: 0–32 bytes. Use 4–8 digits for easy input. If set, users must enter the password to join. Do not store sensitive info in plain text. Passwords are not supported for webinar rooms; leave empty. |
UpdateRoomOptions.ModifyFlag Details
Parameter Name | Type | Required | Description |
ROOM_NAME | enum | No | Flag for updating the room name. When modifying roomName, also set the roomName flag in ModifyFlag. |
PASSWORD | enum | No | Flag for updating the room password. When modifying password, also set the password flag in ModifyFlag.Passwords are not supported for webinar rooms. |
Step 7: Get Room Information
After joining the room, call RoomStore's
getRoomInfo API to retrieve detailed room information.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomInfoimport io.trtc.tuikit.atomicxcore.api.room.GetRoomInfoCompletionHandlerprivate val roomID = "webinar_123456"fun getRoomInfo() {// 1. Business logic description// getRoomInfo is used to retrieve detailed information for a specified room// You can get the room name, creator, permission settings, and other complete information// 2. Call RoomStore to get room information// This operation fetches the latest room status and configuration from the serverRoomStore.shared().getRoomInfo(roomID, object : GetRoomInfoCompletionHandler {override fun onSuccess(roomInfo: RoomInfo) {Log.d("Room", "Room information retrieved successfully, roomInfo: $roomInfo")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to retrieve room information [Error code: $code]: $desc")}})}
Step 8: Listen to Real-Time Room Events and State Changes
Subscribe to passive room events. For example, to listen for room ended events:
import android.content.Contextimport android.util.AttributeSetimport android.util.Logimport android.widget.FrameLayoutimport io.trtc.tuikit.atomicxcore.api.room.RoomInfoimport io.trtc.tuikit.atomicxcore.api.room.RoomListenerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreclass RoomMainView @JvmOverloads constructor(context: Context,attrs: AttributeSet? = null,defStyleAttr: Int = 0) : FrameLayout(context, attrs, defStyleAttr) {// Room event listenerprivate val roomListener = object : RoomListener() {override fun onRoomEnded(roomInfo: RoomInfo) {Log.d("Room", "The current room has ended")// Recommended action: Close the current page and return to the previous screen}}override fun onAttachedToWindow() {super.onAttachedToWindow()// Add room event listenerRoomStore.shared().addRoomListener(roomListener)}override fun onDetachedFromWindow() {super.onDetachedFromWindow()// Remove listener to prevent memory leaksRoomStore.shared().removeRoomListener(roomListener)}}
To subscribe to changes in the current room information via RoomState:
import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport kotlinx.coroutines.CoroutineScopeimport kotlinx.coroutines.Dispatchersimport kotlinx.coroutines.launch// Subscribe to changes in the current room informationprivate fun subscribeCurrentRoomState() {CoroutineScope(Dispatchers.Main).launch {RoomStore.shared().state.currentRoom.collect { roomInfo ->Log.d("Room", "Room information updated, new room info: $roomInfo")}}}
API Documentation
Store/Component | Description | API Documentation |
RoomStore | Room lifecycle management: create and join / join / leave / end room / update, get room information / listen to passive room events (such as room dissolution, room info updates, etc.). |
FAQ
Is there an automatic dissolution mechanism for webinar rooms?
Yes, webinar rooms are automatically dissolved under any of these conditions. The auto-dissolution settings and waiting period can be configured per sdkAppId. For adjustments, contact info_rtc@tencent.com.
If a user joins a webinar room and it remains empty for a set period (default: 30 minutes) with no new entries, the room is dissolved automatically.
If the host leaves the room and does not re-enter within a set period (default: 10 minutes), the room is dissolved automatically. This interval can be configured (range: 2 minutes to 12 hours).
If the host is disconnected due to heartbeat timeout and does not resume the heartbeat or rejoin within a set period (default: 10 minutes), the room is dissolved automatically. This interval can be configured (range: 2 minutes to 12 hours).
Are there charges for rooms with no users that haven't been dissolved?
No. Undissolved rooms with no users only count against your package's room quota and do not incur any usage or additional charges.
What is the maximum number of webinar rooms that can exist simultaneously?
The maximum number of concurrent webinar rooms depends on your package. See TUILiveKit Package Description for details.
What is the maximum number of participants supported in a single room?
The participant limit for a webinar room depends on your package. See TUILiveKit Package Description for details.
Contact Us
For questions or feedback during integration or use, please contact info_rtc@tencent.com.
