RealtimeAnnotations
The RealtimeAnnotations object lets you publish, delete, retrieve, and subscribe to annotations on messages. Access it via the annotations property of a RealtimeChannel.
1
const annotations = channel.annotations;Subscribe to annotations
annotations.subscribe(type: string | string[], listener?: messageCallback<Annotation>): Promise<void>Register a listener that is called each time an Annotation matching one of the given types is received on the channel.
annotations.subscribe(listener?: messageCallback<Annotation>): Promise<void>Register a listener that is called each time any Annotation is received on the channel, regardless of type.
To receive individual realtime annotations (instead of just the rolled-up summaries), the annotation_subscribe channel mode must be requested, since annotations are not delivered by default. Most clients will not need this and can rely on the summary updates instead.
Parameters
typeoptionalString or String[]listeneroptionalmessageCallback<Annotation>Annotation.Returns
Promise<void>
Returns a promise. The promise is fulfilled once the listener has been registered, or rejected with an ErrorInfo object.
Publish an annotation
annotations.publish(message: Message, annotation: OutboundAnnotation): Promise<void>Publish an annotation to a message identified by a Message object.
annotations.publish(messageSerial: string, annotation: OutboundAnnotation): Promise<void>Publish an annotation to a message identified by its serial string.
The action is set automatically to annotation.create. If a clientId is set on the client, it is associated with the annotation; some annotation summarization methods require an identified client.
Parameters
Message object identifying the message to annotate. Provide either message or messageSerial.messageSerialrequiredStringmessage or messageSerial.annotationrequiredOutboundAnnotationtype; other required fields depend on the annotation type.Returns
Promise<void>
Returns a promise. The promise is fulfilled when the annotation has been published to Ably, or rejected with an ErrorInfo object.
Delete an annotation
annotations.delete(message: Message, annotation: OutboundAnnotation): Promise<void>Remove an annotation contribution from a message identified by a Message object.
annotations.delete(messageSerial: string, annotation: OutboundAnnotation): Promise<void>Remove an annotation contribution from a message identified by its serial string.
This removes the contribution this clientId previously made to the annotation summary for the message. The exact behaviour depends on the annotation type. The action is set automatically to annotation.delete. The annotation must include a type and may include a name.
Parameters
Message object identifying the message whose annotation you want to delete. Provide either message or messageSerial.messageSerialrequiredStringmessage or messageSerial.annotationrequiredOutboundAnnotationtype; other required fields depend on the annotation type.Returns
Promise<void>
Returns a promise. The promise is fulfilled when the deletion request has been published to Ably, or rejected with an ErrorInfo object.
Get annotations for a message
annotations.get(message: Message, params: GetAnnotationsParams | null): Promise<PaginatedResult<Annotation>>Retrieve all annotations for a message identified by a Message object.
annotations.get(messageSerial: string, params: GetAnnotationsParams | null): Promise<PaginatedResult<Annotation>>Retrieve all annotations for a message identified by its serial string.
Annotations are returned ordered from earliest to most recent. If you only need the latest summary, prefer channel.getMessage(); use annotations.get() only when you need the full list of raw annotations.
Parameters
Message object identifying the message to get annotations for. Provide either message or messageSerial.messageSerialrequiredStringmessage or messageSerial.paramsrequiredGetAnnotationsParams or Nullnull to apply no restrictions; the argument cannot be omitted.Returns
Promise<PaginatedResult<Annotation>>
Returns a promise, fulfilled with a PaginatedResult containing an array of Annotation objects, or rejected with an ErrorInfo object.
idStringclientIdStringnameStringcountNumbermultiple.v1 annotation type.dataAnyencodingStringdata payload.timestampNumberactionAnnotationActionserialStringmessageSerialStringtypeStringemoji:distinct.v1.extrasAnypush, headers (a map of strings to strings for arbitrary customer-supplied metadata), ephemeral, and privileged objects.Unsubscribe from annotations
annotations.unsubscribe(type: string | string[], listener: messageCallback<Annotation>): voidRemove the given listener for the specified annotation type or types.
annotations.unsubscribe(type: string | string[]): voidRemove all listeners registered for the specified annotation type or types.
annotations.unsubscribe(listener: messageCallback<Annotation>): voidRemove the given listener from all annotation types.
annotations.unsubscribe(): voidRemove all annotation listeners on the channel.
Parameters
typeoptionalString or String[]listeneroptionalmessageCallback<Annotation>Create an annotation from an encoded object
Annotation.fromEncoded(encodedAnnotation: Object, channelOptions?: ChannelOptions): Promise<Annotation>A static factory method to create an Annotation from a deserialized Annotation-like object encoded using Ably's wire protocol. Accessed on the class as Ably.Realtime.Annotation. The returned promise resolves with the decoded annotation.
1
const annotation = await Ably.Realtime.Annotation.fromEncoded(encodedAnnotation);Parameters
The Annotation.fromEncoded() method takes the following parameters:
encodedAnnotationrequiredObjectAnnotation-like deserialized object.Returns
Promise<Annotation>
Returns a promise that resolves with an Annotation object decoded from the supplied object.
Create annotations from an encoded array
Annotation.fromEncodedArray(encodedAnnotations: Object[], channelOptions?: ChannelOptions): Promise<Annotation[]>A static factory method to create an array of Annotation objects from an array of deserialized Annotation-like objects encoded using Ably's wire protocol. The returned promise resolves with the decoded annotations.
1
const annotations = await Ably.Realtime.Annotation.fromEncodedArray(encodedAnnotations);Parameters
The Annotation.fromEncodedArray() method takes the following parameters:
encodedAnnotationsrequiredArray<Object>Annotation-like deserialized objects.Returns
Promise<Annotation[]>
Returns a promise that resolves with an array of Annotation objects decoded from the supplied array.