Room Presence

Room presence tracks who is currently watching a live room. Use it for viewer counts, “who is watching” panels, and host tools that need to know which users are present in a room right now.

Room presence is available on iOS, Android, and TypeScript. It is not available in the current Flutter SDK checkout.

Platform Surface

Platform	Repository	Main APIs
TypeScript	`RoomPresenceRepository`	`startHeartbeat(roomId)`, `stopHeartbeat(roomId)`, `getRoomUserCount(roomId)`, `getRoomOnlineUsers(roomId)`
iOS	`AmityRoomPresenceRepository(roomId:)`	`startHeartbeat()`, `stopHeartbeat()`, `getRoomUserCount()`, `getRoomOnlineUsers()`
Android	`AmityCoreClient.newRoomPresenceRepository().roomId(roomId)`	`startHeartbeat()`, `stopHeartbeat()`, `getOnlineUsersCount()`, `observeOnlineUsersCount(interval:)`, `getOnlineUsersSnapshot()`
Flutter	Not available	Not available

Parameters

Operation	Platform	Parameter	Required	Description
Repository creation	iOS, Android	`roomId`	Yes	Room ID whose presence should be tracked.
`startHeartbeat`	TypeScript	`roomId`	Yes	Room ID where the current user should be counted as present.
`startHeartbeat`	iOS, Android	None	No	Uses the `roomId` already bound to the repository.
`stopHeartbeat`	TypeScript	`roomId`	Yes	Room ID whose heartbeat should stop.
`stopHeartbeat`	iOS, Android	None	No	Stops the active room heartbeat managed by the repository or presence service.
`getRoomUserCount` / `getOnlineUsersCount`	All supported platforms	None or `roomId`	Platform-dependent	Reads the current online viewer count for the room.
`observeOnlineUsersCount`	Android	`interval`	No	Poll interval in seconds. Defaults to 15 seconds.
`getRoomOnlineUsers` / `getOnlineUsersSnapshot`	All supported platforms	None or `roomId`	Platform-dependent	Reads a point-in-time list or snapshot of online room users. Android snapshots paginate 20 users at a time.

Start Room Heartbeat

Start the room heartbeat when the user enters the room, and stop it when they leave. The SDK sends the first heartbeat immediately and continues at the server-configured interval.

let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

try await roomPresence.startHeartbeat()

// Call when the viewer leaves the room.
roomPresence.stopHeartbeat()

val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.startHeartbeat()
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({
        showSuccessMessage("Room heartbeat started")
    }, { error ->
        showErrorMessage(error = error)
    })

// Call when the viewer leaves the room.
roomPresence.stopHeartbeat()

import { RoomPresenceRepository } from '@amityco/ts-sdk';

RoomPresenceRepository.startHeartbeat(roomId);

// Call when the viewer leaves the room.
RoomPresenceRepository.stopHeartbeat(roomId);

Read Room User Count

Use the count as the source of truth for how many users are currently present in the room.

let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

let count = try await roomPresence.getRoomUserCount()
showSuccessMessage(count)

val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.getOnlineUsersCount()
    .subscribe({ count ->
        showSuccessMessage(count)
    }, { error ->
        showErrorMessage(error = error)
    })

import { RoomPresenceRepository } from '@amityco/ts-sdk';

const { count } = await RoomPresenceRepository.getRoomUserCount(roomId);
updateUI(count);

Keep the Count Live

The count is a point-in-time read. Android provides a built-in polling stream. On iOS and TypeScript, use your own timer and choose an interval that fits the UI.

let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

let timer = Timer.scheduledTimer(withTimeInterval: 30, repeats: true) { _ in
    Task { @MainActor in
        if let count = try? await roomPresence.getRoomUserCount() {
            showSuccessMessage(count)
        }
    }
}

timer.invalidate()

val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.observeOnlineUsersCount(interval = 30)
    .subscribe({ count ->
        showSuccessMessage(count)
    }, { error ->
        showErrorMessage(error = error)
    })

import { RoomPresenceRepository } from '@amityco/ts-sdk';

const timer = setInterval(async () => {
  const { count } = await RoomPresenceRepository.getRoomUserCount(roomId);
  updateUI(count);
}, 30_000);

clearInterval(timer);

Read Room Online Users

Use the online-user list when the app needs actual user objects, such as avatars in a “who is watching” panel. For large rooms, display the count as the total and treat the list as a snapshot.

let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

let users = try await roomPresence.getRoomOnlineUsers()
displayUserList(users)

val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.getOnlineUsersSnapshot()
    .subscribe({ snapshot ->
        val users = snapshot.getUsers()
        if (snapshot.canLoadMore()) {
            snapshot.loadMore().subscribe()
        }
    }, { error ->
        showErrorMessage(error = error)
    })

import { RoomPresenceRepository } from '@amityco/ts-sdk';

const { data: users } = await RoomPresenceRepository.getRoomOnlineUsers(roomId);
renderResults(users);

Best Practices

Heartbeat only for active viewing

Start room heartbeat when the viewer enters the live room screen. Stop it when the viewer leaves, switches rooms, backgrounds the screen, or the view model is torn down.

Count for totals, list for faces

The count is the total active viewer number. The online-user list is best for UI that needs actual user objects, such as avatars or invite-to-cohost flows.

Poll count thoughtfully

Android defaults observeOnlineUsersCount to 15 seconds. On iOS and TypeScript, avoid very aggressive polling unless the count is central to the experience.

Heartbeat Sync

Learn when to start and stop current user and room heartbeats.

Room Posts

Create social posts that reference live rooms.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

Platform Surface

Parameters

Start Room Heartbeat

Read Room User Count

Keep the Count Live

Read Room Online Users

Best Practices

Heartbeat Sync

Room Posts

​Platform Surface

​Parameters

​Start Room Heartbeat

​Read Room User Count

​Keep the Count Live

​Read Room Online Users

​Best Practices

​Related Topics

Heartbeat Sync

Room Posts

Platform Surface

Parameters

Start Room Heartbeat

Read Room User Count

Keep the Count Live

Read Room Online Users

Best Practices

Related Topics