Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed.
A true value means only that no sync is in progress. It does not mean the presence set is populated, since the flag is also true once the local set is cleared, and it returns to false whenever a new sync starts.
To wait for an in-progress sync, call get(), which by default resolves only once the sync completes.
Enters the presence set for the channel, optionally passing a data payload. Implicitly attaches the channel if it is not already attached.
Requires an identified client. If the clientId is unset, or is the wildcard *, the call rejects with an ErrorInfo. Set a clientId in ClientOptions or in the token, or use enterClient() to enter on behalf of another identity.
The member is automatically re-entered when the channel re-attaches after a disconnection. If that fails, the ErrorInfo arrives as a channel update event rather than as a rejection.
Optional data: any
The payload associated with the presence member.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.presence.enter({ status: 'online' });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#enter
The payload associated with the presence member.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.presence.enter(data) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.presence.enter(data, (err) => {});
// v2:
await channel.presence.enter(data);
Enters the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. Implicitly attaches the channel if it is not already attached.
Requires an API key or token bound to a wildcard clientId. Without one the call rejects with an ErrorInfo from the server.
The member is automatically re-entered when the channel re-attaches after a disconnection. If that fails, the ErrorInfo arrives as a channel update event rather than as a rejection.
The ID of the client to enter into the presence set.
Optional data: any
The payload associated with the presence member.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.presence.enterClient('bob', { status: 'online' });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#enter-client
Retrieves the current members present on the channel and the metadata for each member, such as their PresenceAction and ID. Implicitly attaches the channel if it is not already attached. Without the presence_subscribe mode the call resolves with an empty array.
On a channel in the suspended state the call rejects with an ErrorInfo. Pass waitForSync: false to resolve with the last known members instead.
Optional params: RealtimePresenceParams
A set of parameters which are used to specify which presence members should be retrieved.
A promise which, upon success, will be fulfilled with an array of PresenceMessage objects. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const members = await channel.presence.get();
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#get
A RealtimePresenceParams object.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.presence.get(params) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.presence.get(params, (err, members) => {});
// v2:
const members = await channel.presence.get(params);
Retrieves a PaginatedResult object, containing an array of historical PresenceMessage objects for the channel. Presence messages are returned from storage only when message persistence is enabled for the channel by a rule. If message persistence is not enabled, only presence messages from the last two minutes are returned.
Optional params: RealtimeHistoryParams
A set of parameters which are used to specify which presence messages should be retrieved.
A promise which, upon success, will be fulfilled with a PaginatedResult object containing an array of PresenceMessage objects. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const result = await channel.presence.history();
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#history
A RealtimeHistoryParams object.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.presence.history(params) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.presence.history(params, (err, result) => {});
// v2:
const result = await channel.presence.history(params);
Leaves the presence set for the channel. Use leaveClient() to leave on behalf of another identity.
Leaving does not implicitly attach the channel. It requires a channel in the attached state. On an attaching channel the call is queued until the channel attaches, unless queueMessages is disabled. In any other channel state, or when the connection is unusable, it rejects with an ErrorInfo.
Optional data: any
The payload associated with the presence member.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.presence.leave();
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#leave
The payload associated with the presence member.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.presence.leave(data) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.presence.leave(data, (err) => {});
// v2:
await channel.presence.leave(data);
Leaves the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection.
Requires an API key or token bound to a wildcard clientId. Without one the call rejects with an ErrorInfo from the server.
Leaving does not implicitly attach the channel. It requires a channel in the attached state. On an attaching channel the call is queued until the channel attaches, unless queueMessages is disabled. In any other channel state, or when the connection is unusable, it rejects with an ErrorInfo.
The ID of the client to leave the presence set for.
Optional data: any
The payload associated with the presence member.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.presence.leaveClient('bob');
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#leave-client
Registers a listener that is called each time a PresenceMessage matching a given PresenceAction, or an action within an array of PresenceActions, is received on the channel, such as a new member entering the presence set. Implicitly attaches the channel unless attachOnSubscribe is false. Without the presence_subscribe mode the server delivers no presence events and the listener never fires.
A PresenceAction or an array of PresenceActions to register the listener for.
Optional listener: messageCallback<PresenceMessage>
An event listener function.
A promise which resolves upon success of the channel attach() operation and rejects with an ErrorInfo object upon its failure. When attachOnSubscribe is false, no attach is performed.
await channel.presence.subscribe('enter', (member) => console.log(member.clientId));
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#subscribe
Registers a listener that is called each time a PresenceMessage is received on the channel, such as a new member entering the presence set. Implicitly attaches the channel unless attachOnSubscribe is false. Without the presence_subscribe mode the server delivers no presence events and the listener never fires.
Optional listener: messageCallback<PresenceMessage>
An event listener function.
A promise which resolves upon success of the channel attach() operation and rejects with an ErrorInfo object upon its failure. When attachOnSubscribe is false, no attach is performed.
await channel.presence.subscribe((member) => console.log(member.clientId));
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#subscribe
A PresenceAction or an array of PresenceActions.
An event listener function.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.presence.subscribe(action, listener) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.presence.subscribe('enter', listener, (err) => {});
// v2:
await channel.presence.subscribe('enter', listener);
Deregisters a specific listener that is registered to receive PresenceMessage on the channel for a given PresenceAction. This removes local listeners only and does not detach the channel or remove this client from the presence set. The server keeps streaming presence events to an attached channel, subject to the client's capabilities.
A specific PresenceAction to deregister the listener for.
An event listener function.
channel.presence.unsubscribe('enter', listener);
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#unsubscribe
Deregisters a specific listener that is registered to receive PresenceMessage on the channel for a given array of PresenceAction objects. This removes local listeners only and does not detach the channel or remove this client from the presence set. The server keeps streaming presence events to an attached channel, subject to the client's capabilities.
An array of PresenceAction objects to deregister the listener for.
An event listener function.
Deregisters any listener that is registered to receive PresenceMessage on the channel for a specific PresenceAction. This removes local listeners only and does not detach the channel or remove this client from the presence set. The server keeps streaming presence events to an attached channel, subject to the client's capabilities.
A specific PresenceAction to deregister the listeners for.
Deregisters any listener that is registered to receive PresenceMessage on the channel for an array of PresenceAction objects. This removes local listeners only and does not detach the channel or remove this client from the presence set. The server keeps streaming presence events to an attached channel, subject to the client's capabilities.
An array of PresenceAction objects to deregister the listeners for.
Deregisters a specific listener that is registered to receive PresenceMessage on the channel. This removes local listeners only and does not detach the channel or remove this client from the presence set. The server keeps streaming presence events to an attached channel, subject to the client's capabilities.
An event listener function.
Deregisters all listeners currently receiving PresenceMessage for the channel. This removes local listeners only and does not detach the channel or remove this client from the presence set. The server keeps streaming presence events to an attached channel, subject to the client's capabilities.
Updates the data payload for a presence member. If called before entering the presence set, this is treated as an ENTER event. Implicitly attaches the channel if it is not already attached.
Requires an identified client. If the clientId is unset, or is the wildcard *, the call rejects with an ErrorInfo. Use updateClient() to update on behalf of another identity.
Optional data: any
The payload to update for the presence member.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.presence.update({ status: 'busy' });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#update
The payload to update for the presence member.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.presence.update(data) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.presence.update(data, (err) => {});
// v2:
await channel.presence.update(data);
Updates the data payload for a presence member using a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. Implicitly attaches the channel if it is not already attached.
Requires an API key or token bound to a wildcard clientId. Without one the call rejects with an ErrorInfo from the server.
The ID of the client to update in the presence set.
Optional data: any
The payload to update for the presence member.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.presence.updateClient('bob', { status: 'busy' });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#update-client
Generated using TypeDoc
Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel.