Document annotations API in SDK reference docs

src/pages/docs/api/realtime-sdk/channels.mdx

@@ -106,6 +106,14 @@ Provides access to the [Presence](/docs/presence-occupancy/presence) object for
 
 Provides access to the [PushChannel](/docs/api/realtime-sdk/push#push-channel) object for this channel which can be used to access members present on the channel, or participate in presence.
 
+<If lang="javascript,nodejs,objc,swift,java,python">
+
+#### annotations <a id="channel-annotations" />
+
+Provides access to the [`RealtimeAnnotations`](#realtime-annotations) object for this channel, which can be used to publish, delete, retrieve and subscribe to [annotations](/docs/messages/annotations) on messages.
+
+</If>
+
 <If lang="javascript">
 #### object <a id="object" />
 
@@ -1763,6 +1771,234 @@ Checks if a channel is in a given state and returns `null` if it is, else calls
 Returns a promise. If the channel is already in the given state, the promise will immediately resolve to `null`. If not, it will call [`once()`](#once) to return a promise which resolves the next time the channel transitions to the given state.
 </If>
 
+<If lang="javascript,nodejs,objc,swift,java,python">
+
+## <If lang="javascript,nodejs">RealtimeAnnotations</If><If lang="objc,swift">ARTRealtimeAnnotations</If><If lang="java">io.ably.lib.realtime.RealtimeAnnotations</If><If lang="python">RealtimeAnnotations</If> <a id="realtime-annotations" />
+
+The `RealtimeAnnotations` object, accessed from the [annotations](#channel-annotations) property of a `Channel`, is used to publish, delete, retrieve, and subscribe to [annotations](/docs/messages/annotations) on messages. See the [annotations documentation](/docs/messages/annotations) for an overview of annotation concepts and types.
+
+### RealtimeAnnotations Methods <a id="realtime-annotations-methods" />
+
+#### <If lang="javascript,nodejs,objc,swift,java,python">publish</If> <a id="annotations-publish" />
+
+<If lang="javascript,nodejs">
+
+`publish(Message message, Annotation annotation): Promise<void>`
+
+`publish(String messageSerial, Annotation annotation): Promise<void>`
+
+</If>
+<If lang="java">
+
+`void publish(Message message, Annotation annotation)`
+
+`void publish(String messageSerial, Annotation annotation)`
+
+`void publish(Message message, Annotation annotation, CompletionListener listener)`
+
+`void publish(String messageSerial, Annotation annotation, CompletionListener listener)`
+
+</If>
+<If lang="objc,swift">
+
+`publishForMessage(message: ARTMessage, annotation: ARTAnnotation, callback: ARTCallback?)`
+
+`publishForMessageSerial(messageSerial: String, annotation: ARTAnnotation, callback: ARTCallback?)`
+
+</If>
+<If lang="python">
+
+`async publish(msg_or_serial, annotation: Annotation)`
+
+</If>
+
+Publishes an [`Annotation`](/docs/api/realtime-sdk/types#annotation) for a message, identified either by a [`Message`](#message) instance or by its [`serial`](#serial). The annotation must include at least a `type`; other required fields depend on the annotation type. The `action` is set automatically to `annotation.create`.
+
+If a [`clientId`](/docs/api/realtime-sdk/types#client-options) is set on the client, it will be associated with the published annotation. Some annotation [summarization methods](/docs/messages/annotations#annotation-types) require an [identified](/docs/auth/identified-clients) client.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| <If lang="python">msg_or_serial</If><If lang="javascript,nodejs,objc,swift,java">message or messageSerial</If> | The message to annotate, identified either by a [`Message`](#message) instance or by its `serial` | <If lang="objc,swift">[`ARTMessage`](#message) or `String`</If><If lang="javascript,nodejs,java,python">[`Message`](#message) or `String`</If> |
+| annotation | The annotation to publish. Must include at least the `type` | <If lang="objc,swift">[`ARTAnnotation`](/docs/api/realtime-sdk/types#annotation)</If><If lang="javascript,nodejs,java,python">[`Annotation`](/docs/api/realtime-sdk/types#annotation)</If> |
+
+#### <If lang="javascript,nodejs,objc,swift,java,python">delete</If> <a id="annotations-delete" />
+
+<If lang="javascript,nodejs">
+
+`delete(Message message, Annotation annotation): Promise<void>`
+
+`delete(String messageSerial, Annotation annotation): Promise<void>`
+
+</If>
+<If lang="java">
+
+`void delete(Message message, Annotation annotation)`
+
+`void delete(String messageSerial, Annotation annotation)`
+
+`void delete(Message message, Annotation annotation, CompletionListener listener)`
+
+`void delete(String messageSerial, Annotation annotation, CompletionListener listener)`
+
+</If>
+<If lang="objc,swift">
+
+`deleteForMessage(message: ARTMessage, annotation: ARTAnnotation, callback: ARTCallback?)`
+
+`deleteForMessageSerial(messageSerial: String, annotation: ARTAnnotation, callback: ARTCallback?)`
+
+</If>
+<If lang="python">
+
+`async delete(msg_or_serial, annotation: Annotation)`
+
+</If>
+
+Publishes an annotation removal request for a message, removing the contribution that this `clientId` previously made to the [annotation summary](/docs/messages/annotations#annotation-summaries). The exact behaviour depends on the [annotation type](/docs/messages/annotations#annotation-types). The `action` is set automatically to `annotation.delete`.
+
+The annotation must include at least a `type`, and may include a `name` for those annotation types where the name is needed to identify which contribution to remove.
+
+##### Parameters
+
+The parameters are the same as for [`publish`](#annotations-publish).
+
+#### <If lang="javascript,nodejs,objc,swift,java,python">get</If> <a id="annotations-get" />
+
+<If lang="javascript,nodejs">
+
+`get(Message message, GetAnnotationsParams? params): Promise<PaginatedResult<Annotation>>`
+
+`get(String messageSerial, GetAnnotationsParams? params): Promise<PaginatedResult<Annotation>>`
+
+</If>
+<If lang="java">
+
+`PaginatedResult<Annotation> get(Message message, Param[] params)`
+
+`PaginatedResult<Annotation> get(String messageSerial, Param[] params)`
+
+`PaginatedResult<Annotation> get(Message message)`
+
+`PaginatedResult<Annotation> get(String messageSerial)`
+
+`void getAsync(Message message, Param[] params, Callback<AsyncPaginatedResult<Annotation>> callback)`
+
+`void getAsync(String messageSerial, Param[] params, Callback<AsyncPaginatedResult<Annotation>> callback)`
+
+</If>
+<If lang="objc,swift">
+
+`getForMessage(message: ARTMessage, query: ARTAnnotationsQuery, callback: ARTPaginatedAnnotationsCallback)`
+
+`getForMessageSerial(messageSerial: String, query: ARTAnnotationsQuery, callback: ARTPaginatedAnnotationsCallback)`
+
+</If>
+<If lang="python">
+
+`async get(msg_or_serial, params: dict | None = None) -> PaginatedResult`
+
+</If>
+
+Retrieves a [paginated result](#paginated-result) containing all individual [`Annotation`](/docs/api/realtime-sdk/types#annotation) events that have been published for a message, ordered from earliest to most recent.
+
+If you only need the latest [annotation summary](/docs/messages/annotations#annotation-summaries) for a message, prefer [`channel.getMessage()`](/docs/messages/updates-deletes#get): the returned message contains the up-to-date `annotations.summary`. Use `annotations.get()` only when you need the full list of raw annotations.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| <If lang="python">msg_or_serial</If><If lang="javascript,nodejs,objc,swift,java">message or messageSerial</If> | The message to retrieve annotations for, identified either by a [`Message`](#message) instance or by its `serial` | <If lang="objc,swift">[`ARTMessage`](#message) or `String`</If><If lang="javascript,nodejs,java,python">[`Message`](#message) or `String`</If> |
+| <If lang="objc,swift">query</If><If lang="javascript,nodejs,java,python">params</If> | An optional set of restrictions on which annotations to retrieve, in particular a `limit` | <If lang="javascript,nodejs">[`GetAnnotationsParams`](/docs/api/realtime-sdk/types#get-annotations-params)</If><If lang="java">[`Param[]`](#param)</If><If lang="objc,swift">[`ARTAnnotationsQuery`](/docs/api/realtime-sdk/types#annotations-query)</If><If lang="python">`dict`</If> |
+
+##### Returns
+
+A [`PaginatedResult`](#paginated-result) containing an array of [`Annotation`](/docs/api/realtime-sdk/types#annotation) objects.
+
+#### <If lang="javascript,nodejs,objc,swift,java,python">subscribe</If> <a id="annotations-subscribe" />
+
+<If lang="javascript,nodejs">
+
+`subscribe(messageCallback<Annotation> listener): Promise<void>`
+
+`subscribe(String | String[] type, messageCallback<Annotation> listener): Promise<void>`
+
+</If>
+<If lang="java">
+
+`void subscribe(AnnotationListener listener)`
+
+`void subscribe(String type, AnnotationListener listener)`
+
+</If>
+<If lang="objc,swift">
+
+`subscribe(callback: (ARTAnnotation) -> Void) -> ARTEventListener?`
+
+`subscribe(type: String, callback: (ARTAnnotation) -> Void) -> ARTEventListener?`
+
+</If>
+<If lang="python">
+
+`async subscribe(listener)`
+
+`async subscribe(type_or_types, listener)`
+
+</If>
+
+Registers a listener that is called each time an individual [`Annotation`](/docs/api/realtime-sdk/types#annotation) is received on the channel.
+
+To receive individual realtime annotations (instead of just the rolled-up [summaries](/docs/messages/annotations#annotation-summaries)), the channel must have requested the `ANNOTATION_SUBSCRIBE` [channel mode](/docs/channels/options#modes). Most clients will not need this and can rely on the summary updates instead.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| type | An optional annotation `type` (or array of types) to filter the listener on. If omitted, the listener is called for all annotations on the channel | `String` or `String[]` |
+| listener | A function called with each received annotation | <If lang="javascript,nodejs">`(annotation: Annotation) => void`</If><If lang="java">`AnnotationListener`</If><If lang="objc,swift">`(ARTAnnotation) -> Void`</If><If lang="python">`callable`</If> |
+
+#### <If lang="javascript,nodejs,objc,swift,java,python">unsubscribe</If> <a id="annotations-unsubscribe" />
+
+<If lang="javascript,nodejs">
+
+`unsubscribe(): void`
+
+`unsubscribe(messageCallback<Annotation> listener): void`
+
+`unsubscribe(String | String[] type, messageCallback<Annotation> listener): void`
+
+</If>
+<If lang="java">
+
+`void unsubscribe(AnnotationListener listener)`
+
+`void unsubscribe(String type, AnnotationListener listener)`
+
+</If>
+<If lang="objc,swift">
+
+`unsubscribe()`
+
+`unsubscribe(listener: ARTEventListener)`
+
+`unsubscribe(type: String, listener: ARTEventListener)`
+
+</If>
+<If lang="python">
+
+`unsubscribe()`
+
+`unsubscribe(listener)`
+
+`unsubscribe(type_or_types, listener)`
+
+</If>
+
+Deregisters annotation listeners. Called with no arguments, removes all listeners. Called with a `listener`, removes that listener from all types it was registered for. Called with a `type` and a `listener`, removes the listener from that type only.
+
+</If>
+
 ## Related types <a id="related-types" />
 
 ### <If lang="javascript,nodejs">ChannelState</If><If lang="objc,swift">ARTRealtimeChannelState</If><If lang="ruby">Channel::STATE Enum</If><If lang="java">io.ably.lib.realtime.ChannelState Enum</If><If lang="csharp">IO.Ably.Realtime.ChannelState Enum</If><If lang="flutter">ably.ChannelState Enum</If>