The Presence interface provides methods for tracking which users are currently in a chat room. Access it via room.presence.
1
const presence = room.presence;Enter presence
presence.enter(data?: PresenceData): Promise<void>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.
1
await room.presence.enter({ status: 'online', nickname: 'Alice' });Parameters
The enter() method takes the following parameters:
dataoptionalPresenceDataReturns
Promise<void>
Returns a promise. The promise is fulfilled when the user has successfully entered the presence set, or rejected with an ErrorInfo object.
Update presence data
presence.update(data?: PresenceData): Promise<void>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.
1
await room.presence.update({ status: 'away', nickname: 'Alice' });Parameters
The update() method takes the following parameters:
dataoptionalPresenceDataReturns
Promise<void>
Returns a promise. The promise is fulfilled when the presence data has been updated, or rejected with an ErrorInfo object.
Leave presence
presence.leave(data?: PresenceData): Promise<void>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.
1
await room.presence.leave({ status: 'offline' });Parameters
The leave() method takes the following parameters:
dataoptionalPresenceDataReturns
Promise<void>
Returns a promise. The promise is fulfilled when the user has left the presence set, or rejected with an ErrorInfo object.
Get current presence members
presence.get(params?: RealtimePresenceParams): Promise<PresenceMember[]>Retrieves the current members present in the chat room.
The room must be attached before calling this method.
1
2
3
4
5
const members = await room.presence.get();
members.forEach(member => {
console.log(`${member.clientId} is ${member.data?.status}`);
});Parameters
The get() method takes the following parameters:
paramsoptionalRealtimePresenceParamsReturns
Promise<PresenceMember[]>
Returns a promise. The promise is fulfilled with an array of presence members currently in the room, or rejected with an ErrorInfo object.
Check if a user is present
presence.isUserPresent(clientId: string): Promise<boolean>Checks whether a specific user is currently present in the chat room.
The room must be attached before calling this method.
1
2
const isAliceHere = await room.presence.isUserPresent('alice-123');
console.log('Alice is present:', isAliceHere);Parameters
The isUserPresent() method takes the following parameters:
clientIdrequiredStringReturns
Promise<boolean>
Returns a promise. The promise is fulfilled with true if the user is present or false otherwise, or rejected with an ErrorInfo object.
Subscribe to presence events
presence.subscribe(listener: PresenceListener): SubscriptionSubscribes to all presence events in the chat room. Receive notifications when users enter, leave, or update their presence data.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { PresenceEventType } from '@ably/chat';
const { unsubscribe } = room.presence.subscribe((event) => {
const member = event.member;
switch (event.type) {
case PresenceEventType.Enter:
console.log(`${member.clientId} joined`);
break;
case PresenceEventType.Leave:
console.log(`${member.clientId} left`);
break;
case PresenceEventType.Update:
console.log(`${member.clientId} updated their status`);
break;
case PresenceEventType.Present:
console.log(`${member.clientId} is present`);
break;
}
});
// To stop receiving presence events
unsubscribe();Parameters
The subscribe() method takes the following parameters:
listenerrequiredPresenceEventReturns
Subscription
Returns an object with the following methods:
Unsubscribe from presence events
unsubscribe(): voidCall unsubscribe() to stop receiving presence events.
Example
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
const room = await chatClient.rooms.get('my-room');
await room.attach();
// Subscribe to presence events
const { unsubscribe } = room.presence.subscribe((event) => {
const member = event.member;
console.log(`${event.type}: ${member.clientId}`);
if (member.data) {
console.log('Data:', member.data);
}
});
// Enter the room with custom data
await room.presence.enter({
status: 'online',
nickname: 'Alice',
avatar: 'https://example.com/alice.png'
});
// Get everyone currently in the room
const members = await room.presence.get();
console.log(`${members.length} users in room`);
// Update your status
await room.presence.update({ status: 'away' });
// Check if a specific user is present
const isBobHere = await room.presence.isUserPresent('bob-456');
// Leave when done
await room.presence.leave();
unsubscribe();