AblyDocs

Presence

Open in

The Presence interface provides methods for tracking which users are currently in a chat room. Access it via room.presence.

Kotlin

1

val presence = room.presence

Enter presence

suspend presence.enter(data: JsonObject? = null): Unit

Enters the current user into the chat room presence set. This notifies other users that you have joined the room.

The room must be attached before calling this method.

Kotlin

1

2

3

4

room.presence.enter(jsonObject {
    put("status", "online")
    put("nickname", "Alice")
})

Parameters

The enter() method takes the following parameters:

dataoptionalJsonObject
JSON-serializable data to associate with the user's presence.

Returns

Unit

This is a suspend function. It completes when the user has successfully entered the presence set, or throws a ChatException on failure.

Update presence data

suspend presence.update(data: JsonObject? = null): Unit

Updates the presence data for the current user in the chat room. Use this to change your status or other presence information without leaving and re-entering.

The room must be attached before calling this method.

Kotlin

1

2

3

4

room.presence.update(jsonObject {
    put("status", "away")
    put("nickname", "Alice")
})

Parameters

The update() method takes the following parameters:

dataoptionalJsonObject
JSON-serializable data to replace the user's current presence data.

Returns

Unit

This is a suspend function. It completes when the presence data has been updated, or throws a ChatException on failure.

Leave presence

suspend presence.leave(data: JsonObject? = null): Unit

Removes the current user from the chat room presence set. This notifies other users that you have left the room.

The room must be attached before calling this method.

Kotlin

1

2

3

room.presence.leave(jsonObject {
    put("status", "offline")
})

Parameters

The leave() method takes the following parameters:

dataoptionalJsonObject
Final presence data to include with the leave event.

Returns

Unit

This is a suspend function. It completes when the user has left the presence set, or throws a ChatException on failure.

Get current presence members

suspend presence.get(waitForSync: Boolean = true, clientId: String? = null, connectionId: String? = null): List<PresenceMember>

Retrieves the current members present in the chat room.

The room must be attached before calling this method.

Kotlin

1

2

3

4

5

val members = room.presence.get()

members.forEach { member ->
    println("${member.clientId} is present")
}

Parameters

The get() method takes the following parameters:

waitForSyncoptionalBoolean
Whether to wait for a full presence set synchronization before returning results. Default true.
clientIdoptionalString
Filters the returned presence members by a specific client ID.
connectionIdoptionalString
Filters the returned presence members by a specific connection ID.

Returns

List<PresenceMember>

This is a suspend function. It returns a list of presence members currently in the room, or throws a ChatException on failure.

clientIdString
The client ID of the present user.
connectionIdString
The connection ID of the present user.
dataJsonObject?
The presence data associated with the user.
extrasJsonObject
Additional data included with the presence message.
updatedAtLong
When this presence state was last updated, in milliseconds since epoch.

Check if a user is present

suspend presence.isUserPresent(clientId: String): Boolean

Checks whether a specific user is currently present in the chat room.

The room must be attached before calling this method.

Kotlin

1

2

val isAliceHere = room.presence.isUserPresent("alice-123")
println("Alice is present: $isAliceHere")

Parameters

The isUserPresent() method takes the following parameters:

clientIdrequiredString
The client ID of the user to check.

Returns

Boolean

This is a suspend function. It returns true if the user is present or false otherwise, or throws a ChatException on failure.

Subscribe to presence events

presence.subscribe(listener: PresenceListener): Subscription

Subscribes to all presence events in the chat room. Receive notifications when users enter, leave, or update their presence data.

Kotlin

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

import com.ably.chat.PresenceEventType

val subscription = room.presence.subscribe { event ->
    val member = event.member
    when (event.type) {
        PresenceEventType.Enter ->
            println("${member.clientId} joined")
        PresenceEventType.Leave ->
            println("${member.clientId} left")
        PresenceEventType.Update ->
            println("${member.clientId} updated their status")
        PresenceEventType.Present ->
            println("${member.clientId} is present")
    }
}

// To stop receiving presence events
subscription.unsubscribe()

Parameters

The subscribe() method takes the following parameters:

listenerrequiredPresenceEvent
Callback function invoked when any presence event occurs.

Returns

Subscription

Returns a Subscription object.

Unsubscribe from presence events

subscription.unsubscribe(): Unit

Call unsubscribe() to stop receiving presence events.

Collect presence events as a Flow

Presence.asFlow(): Flow<PresenceEvent>

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

Kotlin

1

2

3

4

5

6

7

import kotlinx.coroutines.launch

launch {
    room.presence.asFlow().collect { event ->
        println("${event.type}: ${event.member.clientId}")
    }
}

Returns

Flow<PresenceEvent>

Returns a Flow that emits PresenceEvent 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

38

39

40

41

42

43

44

45

import com.ably.chat.PresenceEventType
import com.ably.chat.asFlow
import kotlinx.coroutines.launch
import com.ably.chat.json.jsonObject

val room = chatClient.rooms.get("my-room")
room.attach()

// Subscribe to presence events with a listener
val subscription = room.presence.subscribe { event ->
    val member = event.member
    println("${event.type}: ${member.clientId}")
    member.data?.let { data ->
        println("Data: $data")
    }
}

// Or use Flow for reactive collection
launch {
    room.presence.asFlow().collect { event ->
        println("Presence: ${event.type} - ${event.member.clientId}")
    }
}

// Enter the room with custom data
room.presence.enter(jsonObject {
    put("status", "online")
    put("nickname", "Alice")
})

// Get everyone currently in the room
val members = room.presence.get()
println("${members.size} users in room")

// Update your status
room.presence.update(jsonObject {
    put("status", "away")
})

// Check if a specific user is present
val isBobHere = room.presence.isUserPresent("bob-456")

// Leave when done
room.presence.leave()
subscription.unsubscribe()