# RoomReactions

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`.

<Code>

#### Javascript

```
const reactions = room.reactions;
```
</Code>

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

## Send a room reaction 

`reactions.send(params: SendReactionParams): Promise<void>`

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

The room should be [attached](https://ably.com/docs/chat/api/javascript/room.md#attach) to send room reactions. The connection must be in the [`connected`](https://ably.com/docs/chat/api/javascript/connection.md) state.

<Code>

### Javascript

```
await room.reactions.send({ name: '👍' });
```
</Code>

### Parameters 

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

<Table id='SendParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | Required | The reaction parameters. | <Table id='SendReactionParams'/> |

</Table>

<Table id='SendReactionParams' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| name | Required | The name of the reaction, typically an emoji or identifier. | String |
| metadata | Optional | Additional metadata to include with the reaction. | JsonObject |
| headers | Optional | Additional information in Ably message extras, usable for features like referencing external resources. | Headers |

</Table>

### Returns 

`Promise<void>`

Returns a promise. The promise is fulfilled when the reaction has been sent, or rejected with an [`ErrorInfo`](https://ably.com/docs/chat/api/javascript/chat-client.md#errorinfo) object.

## 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](https://ably.com/docs/chat/api/javascript/room.md#attach) to receive reaction events.

<Code>

### Javascript

```
const { unsubscribe } = room.reactions.subscribe((event) => {
  console.log(`${event.reaction.clientId} reacted with ${event.reaction.name}`);
});

// To stop receiving reactions
unsubscribe();
```
</Code>

### Parameters 

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

<Table id='SubscribeParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| listener | Required | Callback invoked when a room reaction is received. | <Table id='RoomReactionEvent'/> |

</Table>

<Table id='RoomReactionEvent' >

| Property | Description | Type |
| --- | --- | --- |
| type | The type of the event. Always `Reaction`. | <Table id='RoomReactionEventType'/> |
| reaction | The reaction that was received. | <Table id='RoomReaction'/> |

</Table>

<Table id='RoomReactionEventType' >

| Value | Description |
| --- | --- |
| Reaction | A room-level reaction was received. The value is `reaction`. |

</Table>

<Table id='RoomReaction' >

| Property | Description | Type |
| --- | --- | --- |
| name | The name of the reaction (e.g., an emoji). | String |
| clientId | The client ID of the user who sent the reaction. | String |
| metadata | Additional metadata included with the reaction. Empty object if none provided. | JsonObject |
| headers | Additional information from Ably message extras. Empty object if none provided. | Headers |
| createdAt | When the reaction was sent. | Date |
| isSelf | Whether the reaction was sent by the current client. | Boolean |

</Table>

### Returns 

`Subscription`

Returns an object with the following methods:

#### Unsubscribe from room reactions 

`unsubscribe(): void`

Call `unsubscribe()` to stop receiving room reaction events.

## Example

<Code>

### Javascript

```
const room = await chatClient.rooms.get('my-room');
await room.attach();

// Subscribe to room reactions
const { unsubscribe } = room.reactions.subscribe((event) => {
  // Display a floating emoji animation
  showFloatingEmoji(event.reaction.name, event.reaction.clientId);

  console.log(`${event.reaction.clientId} sent ${event.reaction.name}`);

  // Check if it's your own reaction
  if (event.reaction.isSelf) {
    console.log('This was my reaction');
  }
});

// Send reactions when users click reaction buttons
document.querySelectorAll('.reaction-button').forEach(button => {
  button.addEventListener('click', async () => {
    const emoji = button.dataset.emoji;
    await room.reactions.send({ name: emoji });
  });
});

// Send a reaction with metadata
await room.reactions.send({
  name: '🎉',
  metadata: {
    animation: 'confetti',
    color: 'gold'
  }
});

// Clean up
unsubscribe();
```
</Code>