AblyDocs

Occupancy

Open in

The Occupancy interface provides methods for tracking the number of users in a chat room. Access it via room.occupancy.

Kotlin

1

val occupancy = room.occupancy

Properties

The Occupancy interface has the following properties:

currentOccupancyData?
The latest occupancy data cached from realtime events. Requires enableEvents to be true in the room's occupancy options.

Get current occupancy

suspend occupancy.get(): OccupancyData

Fetches the current occupancy of the chat room from the server. Retrieves the latest occupancy metrics, including the number of active connections and presence members.

This method uses the Ably Chat REST API and does not require the room to be attached.

Kotlin

1

2

3

val data = room.occupancy.get()
println("Connections: ${data.connections}")
println("Presence members: ${data.presenceMembers}")

Returns

OccupancyData

This is a suspend function. It returns the current occupancy data, or throws a ChatException on failure.

Subscribe to occupancy events

occupancy.subscribe(listener: OccupancyListener): Subscription

Subscribes to occupancy updates for the chat room. Receives updates whenever the number of connections or present members in the room changes.

Requires enableEvents to be true in the room's occupancy options. The room should be attached to receive occupancy events.

Kotlin

1

2

3

4

5

6

7

val subscription = room.occupancy.subscribe { event ->
    println("Connections: ${event.occupancy.connections}")
    println("Presence members: ${event.occupancy.presenceMembers}")
}

// To stop receiving occupancy updates
subscription.unsubscribe()

Parameters

The subscribe() method takes the following parameters:

listenerrequiredOccupancyEvent
Callback invoked when room occupancy changes.

Returns

Subscription

Returns a Subscription object.

Unsubscribe from occupancy events

subscription.unsubscribe(): Unit

Call unsubscribe() to stop receiving occupancy events.

Collect occupancy events as a Flow

Occupancy.asFlow(): Flow<OccupancyEvent>

Returns a Kotlin Flow that emits occupancy events. This is an extension function on the Occupancy interface that provides a reactive alternative to listener-based subscriptions.

Kotlin

1

2

3

4

5

6

7

import kotlinx.coroutines.launch

launch {
    room.occupancy.asFlow().collect { event ->
        println("Connections: ${event.occupancy.connections}")
    }
}

Returns

Flow<OccupancyEvent>

Returns a Flow that emits OccupancyEvent events. The flow automatically manages the underlying subscription.

Example

Kotlin

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

import com.ably.chat.asFlow
import kotlinx.coroutines.launch

val room = chatClient.rooms.get("my-room") {
    occupancy {
        enableEvents = true // Required for subscribe() and current property
    }
}

room.attach()

// Subscribe to occupancy changes with a listener
val subscription = room.occupancy.subscribe { event ->
    val connections = event.occupancy.connections
    val presenceMembers = event.occupancy.presenceMembers
    println("Room has $connections connections and $presenceMembers presence members")
}

// Or use Flow for reactive collection
launch {
    room.occupancy.asFlow().collect { event ->
        println("Occupancy updated: ${event.occupancy.connections} connections")
    }
}

// Fetch occupancy on-demand (works even without enableEvents)
val occupancy = room.occupancy.get()
println("Initial occupancy: ${occupancy.connections} connections")

// Access cached occupancy (requires enableEvents)
val cached = room.occupancy.current
cached?.let {
    println("Cached occupancy: ${it.connections}")
}

// Clean up
subscription.unsubscribe()