RestAnnotations
The RestAnnotations object lets you publish, delete, and retrieve annotations on messages. Access it via the annotations property of a Channel.
Subscribing to individual annotations in realtime requires the realtime SDK's RealtimeAnnotations interface.
1
const annotations = channel.annotations;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.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.Rest.Annotation. The returned promise resolves with the decoded annotation.
1
const annotation = await Ably.Rest.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.Rest.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.