AblyDocs

RoomReactions

Open in

The RoomReactions interface provides methods for sending and receiving ephemeral room-level reactions. These are commonly used for live interactions like floating emojis, applause, or other real-time feedback in chat rooms. Access it via room.reactions.

Kotlin

1

val reactions = room.reactions

Unlike message reactions, room reactions are not persisted and are only visible to users currently connected to the room.

Send a room reaction

suspend reactions.send(name: String, metadata: JsonObject? = null, headers: Map<String, String>? = null): Unit

Sends a room-level reaction. Room reactions are ephemeral events that are not associated with specific messages.

The room should be attached to send room reactions. The connection must be in the Connected state.

Kotlin

1

room.reactions.send(name = "👍")

Parameters

The send() method takes the following parameters:

namerequiredString
The name of the reaction, typically an emoji or identifier.
metadataoptionalJsonObject?
Additional metadata to include with the reaction.
headersoptionalMap<String, String>?
Additional information in Ably message extras, usable for features like referencing external resources.

Returns

Unit

This is a suspend function. It completes when the reaction has been sent, or throws a ChatException on failure.

Subscribe to room reactions

reactions.subscribe(listener: RoomReactionListener): Subscription

Subscribes to room-level reaction events. Receives all room reactions sent by any user in the room. This is useful for displaying floating reactions, triggering animations, or showing live audience engagement.

The room should be attached to receive reaction events.

Kotlin

1

2

3

4

5

6

val subscription = room.reactions.subscribe { event ->
    println("${event.reaction.clientId} reacted with ${event.reaction.name}")
}

// To stop receiving reactions
subscription.unsubscribe()

Parameters

The subscribe() method takes the following parameters:

listenerrequiredRoomReactionEvent
Callback invoked when a room reaction is received.

Returns

Subscription

Returns a Subscription object.

Unsubscribe from room reactions

subscription.unsubscribe(): Unit

Call unsubscribe() to stop receiving room reaction events.

Collect room reactions as a Flow

RoomReactions.asFlow(): Flow<RoomReactionEvent>

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

Kotlin

1

2

3

4

5

6

7

import kotlinx.coroutines.launch

launch {
    room.reactions.asFlow().collect { event ->
        println("${event.reaction.clientId} reacted with ${event.reaction.name}")
    }
}

Returns

Flow<RoomReactionEvent>

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

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

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

// Subscribe to room reactions with a listener
val subscription = room.reactions.subscribe { event ->
    println("${event.reaction.clientId} sent ${event.reaction.name}")

    // Check if it's your own reaction
    if (event.reaction.isSelf) {
        println("This was my reaction")
    }
}

// Or use Flow for reactive collection
launch {
    room.reactions.asFlow().collect { event ->
        println("Reaction: ${event.reaction.name}")
    }
}

// Send a simple reaction
room.reactions.send(name = "🎉")

// Send a reaction with metadata
room.reactions.send(
    name = "🎉",
    metadata = jsonObject {
        put("animation", "confetti")
        put("color", "gold")
    }
)

// Clean up
subscription.unsubscribe()