Skip to main content
User presence lets iOS and Android apps read whether specific users are currently online. Use it for online badges, visible member lists, or a lightweight “who is online” snapshot.
The current TypeScript and Flutter SDKs in this checkout do not expose a user presence repository. Use the iOS and Android snippets below only for those platforms.

​
Platform Surface

PlatformRepositoryMain APIs
iOSAmityUserPresenceRepository()getUserPresence(userIds:), syncUserPresence(id:viewId:), getSyncingUserPresence(), getOnlineUsersCount(), getOnlineUsersSnapshot()
AndroidAmityCoreClient.newUserPresenceRepository()getUserPresence(userIds), syncUserPresence(userId, viewId), getSyncingUserPresence(), getOnlineUsersCount(), getOnlineUsersSnapshot()
TypeScriptNot availableNot available
FlutterNot availableNot available

​
Parameters

OperationParameterRequiredDescription
getUserPresenceuserIdsYesUser IDs to read. iOS documents a maximum of 220 IDs per call. Keep Android calls bounded for the same reason.
syncUserPresenceid / userIdYesUser ID whose presence should be refreshed periodically while visible.
syncUserPresenceviewIdNoStable view identifier. Defaults to amity-global; use a custom value when the same user can appear in multiple visible UI locations.
unsyncUserPresenceid / userIdYesUser ID to remove from syncing.
unsyncUserPresenceviewIdNoMust match the viewId used when syncing if you passed a custom value.
unsyncAllUserPresenceNoneNoStops syncing all user presence tracked by the SDK presence engine.
getSyncingUserPresenceNoneNoReturns iOS AnyPublisher<[AmityUserPresence], Error> or Android Flowable<List<AmityUserPresence>>.
getOnlineUsersCountNoneNoReturns the current count of online users in the network.
getOnlineUsersSnapshotNoneNoReturns a point-in-time, paginated snapshot of online users. iOS and Android load users 20 at a time.

​
User Presence Object

FieldiOSAndroidDescription
User IDpresence.userIdpresence.getUserId()The user represented by this presence record.
Last heartbeatpresence.lastHeartbeatpresence.getLastHeartbeat()Last heartbeat timestamp, when available.
Online statepresence.isOnlinepresence.isOnline()true when the last heartbeat is within the SDK online threshold.
The SDK limits active presence syncing to 20 user IDs at a time. Unsync users when their row, card, or profile preview is no longer visible.

​
Read User Presence

Fetch presence for known users as a one-shot read. 
let repository = AmityUserPresenceRepository()

let presences = try await repository.getUserPresence(userIds: [userId])
for presence in presences {
    let isOnline = presence.isOnline
    let lastHeartbeat = presence.lastHeartbeat
    showSuccessMessage("\(presence.userId): \(isOnline)")
}

​
Sync User Presence

Sync user presence while users are visible, then unsync them when the UI no longer needs updates. 
let repository = AmityUserPresenceRepository()

let cancellable = repository.getSyncingUserPresence()
    .sink(receiveCompletion: { completion in
        if case let .failure(error) = completion {
            handleError(error)
        }
    }, receiveValue: { presences in
        for presence in presences {
            showSuccessMessage("\(presence.userId): \(presence.isOnline)")
        }
    })

repository.syncUserPresence(id: userId)

// Call when the row or screen is no longer visible.
repository.unsyncUserPresence(id: userId)

_ = cancellable

​
Read Online Users Count And Snapshot

Use the count for a network-wide online total. Use the snapshot when you need actual user objects at the time of the query. 
let repository = AmityUserPresenceRepository()

let count = try await repository.getOnlineUsersCount()
showSuccessMessage(count)

let snapshot = try await repository.getOnlineUsersSnapshot()
let users = snapshot.users

if snapshot.canLoadMore {
    await snapshot.loadMore()
}

​
Best Practices

Other users can only see the current user as online if the app enables presence and starts the current user’s heartbeat. See Heartbeat Sync.
Bind syncUserPresence to visible UI rows, cells, or cards. Call unsyncUserPresence during cell reuse, unmount, or screen dismissal.
getOnlineUsersSnapshot is a point-in-time read. For live online badges, sync specific visible users instead.

Channel Presence

Show whether any other member of a conversation channel is online.

Heartbeat Sync

Mark the current user as online with the SDK heartbeat.