# Presence

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

<Code>

#### Kotlin

```
val presence = room.presence
```
</Code>

## 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](https://ably.com/docs/chat/api/kotlin/room.md#attach) before calling this method.

<Code>

### Kotlin

```
room.presence.enter(jsonObject {
    put("status", "online")
    put("nickname", "Alice")
})
```
</Code>

### Parameters 

The `enter()` method takes the following parameters:

<Table id='EnterParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| data | Optional | JSON-serializable data to associate with the user's presence. | `JsonObject` |

</Table>

### Returns 

`Unit`

This is a suspend function. It completes when the user has successfully entered the presence set, or throws a [`ChatException`](https://ably.com/docs/chat/api/kotlin/chat-client.md#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](https://ably.com/docs/chat/api/kotlin/room.md#attach) before calling this method.

<Code>

### Kotlin

```
room.presence.update(jsonObject {
    put("status", "away")
    put("nickname", "Alice")
})
```
</Code>

### Parameters 

The `update()` method takes the following parameters:

<Table id='UpdateParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| data | Optional | JSON-serializable data to replace the user's current presence data. | `JsonObject` |

</Table>

### Returns 

`Unit`

This is a suspend function. It completes when the presence data has been updated, or throws a [`ChatException`](https://ably.com/docs/chat/api/kotlin/chat-client.md#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](https://ably.com/docs/chat/api/kotlin/room.md#attach) before calling this method.

<Code>

### Kotlin

```
room.presence.leave(jsonObject {
    put("status", "offline")
})
```
</Code>

### Parameters 

The `leave()` method takes the following parameters:

<Table id='LeaveParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| data | Optional | Final presence data to include with the leave event. | `JsonObject` |

</Table>

### Returns 

`Unit`

This is a suspend function. It completes when the user has left the presence set, or throws a [`ChatException`](https://ably.com/docs/chat/api/kotlin/chat-client.md#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](https://ably.com/docs/chat/api/kotlin/room.md#attach) before calling this method.

<Code>

### Kotlin

```
val members = room.presence.get()

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

### Parameters 

The `get()` method takes the following parameters:

<Table id='GetParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| waitForSync | Optional | Whether to wait for a full presence set synchronization before returning results. Default `true`. | Boolean |
| clientId | Optional | Filters the returned presence members by a specific client ID. | String |
| connectionId | Optional | Filters the returned presence members by a specific connection ID. | String |

</Table>

### Returns 

`List<PresenceMember>`

This is a suspend function. It returns a list of presence members currently in the room, or throws a [`ChatException`](https://ably.com/docs/chat/api/kotlin/chat-client.md#chatexception) on failure.

<Table id='PresenceMember'>

| Property | Description | Type |
| --- | --- | --- |
| clientId | The client ID of the present user. | String |
| connectionId | The connection ID of the present user. | String |
| data | The presence data associated with the user. | `JsonObject?` |
| extras | Additional data included with the presence message. | `JsonObject` |
| updatedAt | When this presence state was last updated, in milliseconds since epoch. | Long |

</Table>

## 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](https://ably.com/docs/chat/api/kotlin/room.md#attach) before calling this method.

<Code>

### Kotlin

```
val isAliceHere = room.presence.isUserPresent("alice-123")
println("Alice is present: $isAliceHere")
```
</Code>

### Parameters 

The `isUserPresent()` method takes the following parameters:

<Table id='IsUserPresentParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| clientId | Required | The client ID of the user to check. | String |

</Table>

### Returns 

`Boolean`

This is a suspend function. It returns `true` if the user is present or `false` otherwise, or throws a [`ChatException`](https://ably.com/docs/chat/api/kotlin/chat-client.md#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.

<Code>

### Kotlin

```
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()
```
</Code>

### Parameters 

The `subscribe()` method takes the following parameters:

<Table id='SubscribeParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| listener | Required | Callback function invoked when any presence event occurs. | <Table id='PresenceEvent'/> |

</Table>

<Table id='PresenceEvent' >

| Property | Description | Type |
| --- | --- | --- |
| type | The type of presence event. | <Table id='PresenceEventType'/> |
| member | The presence member associated with this event. | <Table id='PresenceMember'/> |

</Table>

<Table id='PresenceEventType' >

| Value | Description |
| --- | --- |
| Enter | A user has entered the presence set. |
| Leave | A user has left the presence set. |
| Update | A user has updated their presence data. |
| Present | Indicates a user is present (received during initial sync). |

</Table>

### Returns 

[`Subscription`](https://ably.com/docs/chat/api/kotlin/rooms.md#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.

<Code>

### Kotlin

```
import kotlinx.coroutines.launch

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

### Returns 

`Flow<PresenceEvent>`

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

## Example

<Code>

### Kotlin

```
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()
```
</Code>

## Related Topics

- [ChatClient](https://ably.com/docs/chat/api/kotlin/chat-client.md): API reference for the ChatClient interface in the Ably Chat Kotlin SDK.
- [Connection](https://ably.com/docs/chat/api/kotlin/connection.md): API reference for the Connection interface in the Ably Chat Kotlin SDK.
- [Rooms](https://ably.com/docs/chat/api/kotlin/rooms.md): API reference for the Rooms interface in the Ably Chat Kotlin SDK.
- [Room](https://ably.com/docs/chat/api/kotlin/room.md): API reference for the Room interface in the Ably Chat Kotlin SDK.
- [Messages](https://ably.com/docs/chat/api/kotlin/messages.md): API reference for the Messages interface in the Ably Chat Kotlin SDK.
- [Message](https://ably.com/docs/chat/api/kotlin/message.md): API reference for the Message interface in the Ably Chat Kotlin SDK.
- [MessageReactions](https://ably.com/docs/chat/api/kotlin/message-reactions.md): API reference for the MessageReactions interface in the Ably Chat Kotlin SDK.
- [Occupancy](https://ably.com/docs/chat/api/kotlin/occupancy.md): API reference for the Occupancy interface in the Ably Chat Kotlin SDK.
- [Typing](https://ably.com/docs/chat/api/kotlin/typing.md): API reference for the Typing interface in the Ably Chat Kotlin SDK.
- [RoomReactions](https://ably.com/docs/chat/api/kotlin/room-reactions.md): API reference for the RoomReactions interface in the Ably Chat Kotlin SDK.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.