A RealtimeAnnotations object.
An ErrorInfo object describing the last error which occurred on the channel, if any. This is null until an error occurs, for example a transition in channel state to failed or suspended. Guard against null despite the declared type.
An array of ResolvedChannelMode objects reflecting the modes the server granted on the most recent attach. The server grants only the modes the key or token capability permits, so this may be a subset of the modes requested via modes.
It is undefined before the channel attaches for the first time. When the server grants no modes, it is also undefined, not an empty array. Guard against undefined despite the declared type.
Readonly name
The channel name.
Optional channel parameters that configure the behavior of the channel. After the channel attaches this reflects the parameters the server confirmed on the most recent attach.
It is undefined before the channel attaches for the first time, so guard against undefined despite the declared type.
A RealtimePresence object.
A PushChannel object that manages device push notification subscriptions for this channel. Accessing this property requires the Push plugin to be registered via plugins. The default and modular builds do not bundle the Push plugin. If the plugin is absent, the getter throws an ErrorInfo rather than returning a PushChannel.
Readonly state
The current ChannelState of the channel.
Appends data to an existing message. The supplied data field is appended to the previous message's data, while all other fields (name, extras) replace the previous values if provided.
The channel must be configured to allow message appends, enabled by a rule.
The supplied Message must carry a populated serial. A newly constructed Message has none, so the call rejects with an ErrorInfo.
A Message object containing a populated serial field and the data to append.
Optional operation: MessageOperation
An optional MessageOperation object containing metadata about the append operation.
Optional options: PublishOptions
Optional parameters to modify how the publish is made.
A promise which, upon success, will be fulfilled with an UpdateDeleteResult object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const result = await channel.appendMessage({ ...message, data: ' more text' });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#append-message
Attach to this channel so that messages published on it are received by any listeners registered with subscribe(). It also emits the resulting channel state change to listeners registered with on() or once().
As a convenience you need not call this directly. It is invoked implicitly by channel.subscribe(), by presence.enter(), presence.enterClient(), presence.update(), presence.updateClient(), presence.subscribe(), or presence.get(), by annotations.subscribe(), or by LiveObjects get().
The returned promise rejects with an ErrorInfo if the connection is in the suspended, closing, closed, or failed state. It also rejects if the channel transitions to detaching, detached, suspended, or failed instead of attaching.
A promise which, upon success, if the channel became attached will be fulfilled with a ChannelStateChange object. If the channel was already attached the promise will be fulfilled with null. Upon failure, the promise will be rejected with an ErrorInfo object.
await channel.attach();
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#attach
Marks a message as deleted by publishing an update with an action of MESSAGE_DELETE. This does not remove the message from the server, and the full message history remains accessible.
Uses patch semantics: non-null name, data, and extras fields in the provided message replace the corresponding fields in the existing message, while null fields are left unchanged. A deleted message keeps its previous data unless the delete explicitly sets data to an empty value.
The channel must be configured to allow message deletes, enabled by a rule.
The supplied Message must carry a populated serial. A newly constructed Message has none, so the call rejects with an ErrorInfo.
A Message object containing a populated serial field.
Optional operation: MessageOperation
An optional MessageOperation object containing metadata about the delete operation.
Optional options: PublishOptions
Optional parameters to modify how the publish is made.
A promise which, upon success, will be fulfilled with an UpdateDeleteResult object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const result = await channel.deleteMessage(message);
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#delete-message
Detach from this channel. Any resulting channel state change is emitted to listeners registered with on() or once().
Detaching stops the server sending this channel's messages and any other channel traffic to the client. Locally registered listeners remain registered.
Once all clients globally have detached from the channel, the channel is released in the Ably service within two minutes.
Detaching from a channel in the suspended or detached state resolves without further action. Calling detach() on a channel in the detaching state does not start a second detach, and the returned promise resolves once the channel transitions to the detached state. Detaching from a channel in the failed state rejects with an ErrorInfo. Release the channel with release() and get it again with get() to start afresh.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.detach();
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#detach
Retrieves the latest version of a specific message by its serial identifier.
The channel must be configured to allow message updates, enabled by a rule.
The supplied serial or Message must carry a populated serial. A newly constructed Message has none, so the call rejects with an ErrorInfo.
A promise which, upon success, will be fulfilled with a Message object representing the latest version of the message. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const message = await channel.getMessage(serial);
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#get-message
Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent update, delete, or append operations.
The supplied serial or Message must carry a populated serial. A newly constructed Message has none, so the call rejects with an ErrorInfo.
Message versions exist only when the channel is configured to allow updating, deleting, or appending messages, enabled by a rule.
A promise which, upon success, will be fulfilled with a PaginatedResult object containing an array of Message objects representing all versions of the message. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const versions = await channel.getMessageVersions(message);
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#get-message-versions
Retrieves a PaginatedResult object, containing an array of historical InboundMessage objects for the channel.
Messages are returned from storage only when message persistence is enabled for the channel by a rule. If message persistence is not enabled, only messages from the last two minutes are returned.
Optional params: RealtimeHistoryParams
A set of parameters which are used to specify which messages should be retrieved.
A promise which, upon success, will be fulfilled with a PaginatedResult object containing an array of InboundMessage objects. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const result = await channel.history({ limit: 25 });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#history
A RealtimeHistoryParams object.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.history(params) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.history(params, (err, result) => {});
// v2:
const result = await channel.history(params);
Returns the listeners for a specified EventType.
Optional eventName: ChannelEvent
The event name to retrieve the listeners for.
Removes all registrations that match both the specified listener and the specified event.
The named event.
The event listener.
Deregisters the specified listener. Removes all registrations matching the given listener, regardless of whether they are associated with an event or not.
The event listener.
Deregisters all registrations, for all events and listeners.
Registers the provided listener for the specified event. If on() is called more than once with the same listener and event, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using on(), and an event is emitted once, the listener would be invoked twice.
The named event to listen for.
The event listener.
Registers the provided listener for the specified events. If on() is called more than once with the same listener and event, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using on(), and an event is emitted once, the listener would be invoked twice.
The named events to listen for.
The event listener.
Registers the provided listener all events. If on() is called more than once with the same listener and event, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using on(), and an event is emitted once, the listener would be invoked twice.
The event listener.
Registers the provided listener for the first occurrence of a single named event specified as the Event argument. If once is called more than once with the same listener, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using once, and an event is emitted once, the listener would be invoked twice. However, all subsequent events emitted would not invoke the listener as once ensures that each registration is only invoked once.
The named event to listen for.
The event listener.
Registers the provided listener for the first event that is emitted. If once() is called more than once with the same listener, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using once(), and an event is emitted once, the listener would be invoked twice. However, all subsequent events emitted would not invoke the listener as once() ensures that each registration is only invoked once.
The event listener.
Returns a promise which resolves upon the first occurrence of a single named event specified as the Event argument.
The named event to listen for.
A promise which resolves upon the first occurrence of the named event.
Returns a promise which resolves upon the first occurrence of an event.
A promise which resolves upon the first occurrence of an event.
Publishes a single message to the channel with the given event name and payload.
The event name.
The message payload.
Optional options: PublishOptions
Optional parameters to modify how the publish is made.
A promise which, upon success, will be fulfilled with a PublishResult object containing the serial of the published message. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
await channel.publish('event', { text: 'hello' });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#publish
Publishes an array of messages to the channel.
An array of Message objects.
Optional options: PublishOptions
Optional parameters to modify how the publish is made.
A promise which, upon success, will be fulfilled with a PublishResult object containing the serials of the published messages. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
await channel.publish([{ name: 'event', data: { text: 'hello' } }]);
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#publish
Publishes a message to the channel.
A Message object.
Optional options: PublishOptions
Optional parameters to modify how the publish is made.
A promise which, upon success, will be fulfilled with a PublishResult object containing the serial of the published message. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
await channel.publish({ name: 'event', data: { text: 'hello' } });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#publish
The event name.
The message payload.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.publish(name, data) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.publish('event', data, (err) => { if (err) console.error(err); });
// v2:
await channel.publish('event', data);
Sets the ChannelOptions for the channel.
Changing modes or params while the channel is attached or attaching re-attaches it to apply them, and the promise resolves only once the server confirms the new options. It rejects with an ErrorInfo if the channel transitions to detached or failed instead. If the channel is not attached or attaching, changed modes or params are stored and applied on the next attach. Other options, such as a cipher, take effect immediately.
The promise also rejects with an ErrorInfo when the supplied options are invalid.
A ChannelOptions object.
A promise which resolves upon success of the operation and rejects with an ErrorInfo object upon its failure.
await channel.setOptions({ params: { rewind: '1' } });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#set-options
Registers a listener for messages with a given event name on this channel. Implicitly attaches the channel unless attachOnSubscribe is false. Without the subscribe mode the server delivers no messages and the listener never fires.
The event name.
Optional listener: messageCallback<InboundMessage>
An event listener function.
A promise which, upon successful attachment to the channel, will be fulfilled with a ChannelStateChange object. If the channel was already attached the promise will be resolved with null. The promise also resolves with null when attachOnSubscribe is false, in which case no attach is attempted. Upon failure, the promise will be rejected with an ErrorInfo object.
await channel.subscribe('event', (message) => console.log(message.data));
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#subscribe
Registers a listener for messages on this channel for multiple event name values. Implicitly attaches the channel unless attachOnSubscribe is false. Without the subscribe mode the server delivers no messages and the listener never fires.
An array of event names.
Optional listener: messageCallback<InboundMessage>
An event listener function.
A promise which, upon successful attachment to the channel, will be fulfilled with a ChannelStateChange object. If the channel was already attached the promise will be resolved with null. The promise also resolves with null when attachOnSubscribe is false, in which case no attach is attempted. Upon failure, the promise will be rejected with an ErrorInfo object.
await channel.subscribe(['event1', 'event2'], (message) => console.log(message.data));
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#subscribe
Registers a listener for messages on this channel that match the supplied filter. Implicitly attaches the channel unless attachOnSubscribe is false. Without the subscribe mode the server delivers no messages and the listener never fires.
Optional listener: messageCallback<InboundMessage>
An event listener function.
A promise which, upon successful attachment to the channel, will be fulfilled with a ChannelStateChange object. If the channel was already attached the promise will be resolved with null. The promise also resolves with null when attachOnSubscribe is false, in which case no attach is attempted. Upon failure, the promise will be rejected with an ErrorInfo object.
await channel.subscribe({ name: 'event' }, (message) => console.log(message.data));
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#subscribe
Registers a listener for messages on this channel. Implicitly attaches the channel unless attachOnSubscribe is false. Without the subscribe mode the server delivers no messages and the listener never fires.
An event listener function.
A promise which, upon successful attachment to the channel, will be fulfilled with a ChannelStateChange object. If the channel was already attached the promise will be resolved with null. The promise also resolves with null when attachOnSubscribe is false, in which case no attach is attempted. Upon failure, the promise will be rejected with an ErrorInfo object.
await channel.subscribe((message) => console.log(message.data));
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#subscribe
The event name.
An event listener function.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.subscribe(name, listener) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.subscribe('event', listener, (err) => { if (err) console.error(err); });
// v2:
await channel.subscribe('event', listener);
Deregisters the given listener for the specified event name. This removes local listeners only and does not detach the channel. The server keeps streaming messages to an attached channel, subject to the client's capabilities.
The event name.
An event listener function.
Deregisters the given listener from all event names in the array. This removes local listeners only and does not detach the channel. The server keeps streaming messages to an attached channel, subject to the client's capabilities.
An array of event names.
An event listener function.
Deregisters all listeners for the given event name. This removes local listeners only and does not detach the channel. The server keeps streaming messages to an attached channel, subject to the client's capabilities.
The event name.
Deregisters all listeners for all event names in the array. This removes local listeners only and does not detach the channel. The server keeps streaming messages to an attached channel, subject to the client's capabilities.
An array of event names.
Deregisters listeners registered with the supplied MessageFilter. The filter is matched by object identity, so pass the same object given to subscribe(). Any other filter object removes nothing and no error is raised. This removes local listeners only and does not detach the channel. The server keeps streaming messages to an attached channel, subject to the client's capabilities.
Optional listener: messageCallback<InboundMessage>
An event listener function.
Deregisters the given listener from all event names. This removes local listeners only and does not detach the channel. The server keeps streaming messages to an attached channel, subject to the client's capabilities.
An event listener function.
Deregisters all listeners to messages on this channel. This removes local listeners only and does not detach the channel. The server keeps streaming messages to an attached channel, subject to the client's capabilities.
The event name.
An event listener function.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use channel.unsubscribe(name, listener) — the v2 API is synchronous. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
channel.unsubscribe('event', listener, (err) => {});
// v2:
channel.unsubscribe('event', listener);
Publishes an update to an existing message with patch semantics. Non-null name, data, and extras fields in the provided message replace the corresponding fields in the existing message, while null fields are left unchanged.
The channel must be configured to allow message updates, enabled by a rule.
The supplied Message must carry a populated serial. A newly constructed Message has none, so the call rejects with an ErrorInfo.
A Message object containing a populated serial field and the fields to update.
Optional operation: MessageOperation
An optional MessageOperation object containing metadata about the update operation.
Optional options: PublishOptions
Optional parameters to modify how the publish is made.
A promise which, upon success, will be fulfilled with an UpdateDeleteResult object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
await channel.updateMessage({ ...message, data: 'edited text' });
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#update-message
If the channel is already in the given state, resolves immediately with null. Otherwise resolves with the ChannelStateChange the next time the channel transitions to the given state. If the channel never transitions to the given state, the promise never settles and no error is raised.
The channel state to wait for.
const stateChange = await channel.whenState('attached');
https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel#when-state
Generated using TypeDoc
Enables messages to be published and subscribed to. Also enables historic messages to be retrieved and provides access to the RealtimePresence object of a channel.