Document annotations API in SDK reference docs

[SimonWoolf]

Summary

• Adds a Retrieve annotations section to the message annotations doc covering `channel.annotations.get()`, with samples for JS, Node, Java, Swift, and Python, plus a note pointing users to `channel.getMessage()` when they only need the latest summary. Also promotes Annotation message properties to a top-level heading.
• Adds the previously undocumented annotations API surface to the SDK reference: a `Channel.annotations` property and full `RealtimeAnnotations` / `RestAnnotations` sections (publish, delete, get, subscribe, unsubscribe) on the realtime and rest channels pages.
• Adds the missing related types to `realtime-sdk/types.mdx`: `Annotation`, `AnnotationAction`, `GetAnnotationsParams` / `ARTAnnotationsQuery`, and the per-language summary entry types (`SummaryClientIdList`, `SummaryClientIdCounts`, `SummaryTotal`, plus the Java `Summary` wrapper). Also fleshes out the `MessageAnnotations.summary` row, which previously just said `Record<String, JsonObject>`.
• Following the existing convention (single `Message` rather than `OutboundMessage`), uses a single `Annotation` type and notes which fields are server-set.
• Restricts new content to the languages that actually ship the API today: JS, Node, Java, Swift, Objective-C, Python (verified by grepping each SDK repo).

Test plan

• Add the `review-app` label and check the rendered output for both `/docs/messages/annotations` and the new sections in the realtime + rest SDK reference channels/types pages.
• Spot-check that the `Channel.annotations` link on each channels page lands in the new RealtimeAnnotations / RestAnnotations section.
• Spot-check the type cross-links from channels.mdx → types.mdx (`Annotation`, `GetAnnotationsParams`, `ARTAnnotationsQuery`, summary entry types).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b0096307-ee9f-41ac-b782-c482569a6dfa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch annotations-get-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR expands the documentation coverage for the message annotations API, adding end-user guidance for retrieving annotations and filling in previously missing SDK reference surface area and related types.

Changes:

• Adds a Retrieve annotations section to the message annotations guide, including multi-language examples and guidance on when to prefer channel.getMessage().
• Documents Channel.annotations and the full REST/Realtime annotations API surfaces (publish/delete/get/subscribe/unsubscribe) in the SDK reference channel pages.
• Adds and expands missing related types in the realtime SDK types reference, including Annotation, AnnotationAction, query params/types, and summary entry types.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/pages/docs/messages/annotations.mdx	Adds end-user “Retrieve annotations” guidance and promotes annotation properties to a top-level section.
src/pages/docs/api/rest-sdk/channels.mdx	Documents Channel.annotations and introduces RestAnnotations reference section and methods.
src/pages/docs/api/realtime-sdk/channels.mdx	Documents Channel.annotations and introduces RealtimeAnnotations reference section and methods (incl. subscribe/unsubscribe).
src/pages/docs/api/realtime-sdk/types.mdx	Adds annotation-related types and fleshes out MessageAnnotations.summary typing and summary entry structures.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

[sacOO7]

Fixes https://ably.atlassian.net/browse/DX-925

[sacOO7]

@claude review

[sacOO7]

Deployed current branch preview at https://ably-docs-annotations-g-nzmo0d.herokuapp.com/docs/messages/annotations with username/password = preview.

This seems like a really short note to retrieve annotation summary for given message/message-serial.

As a third person going through the docs, I understand following

Annotations as a feature is defined by the summary =>

• The five aggregation methods (total.v1, flag.v1, distinct.v1, unique.v1, multiple.v1) all exist to produce different shapes of summary. 
• Since, summary is a user-facing output, we should explicitly mention ways to retrieve it.
• IMHO, a dedicated section to retrieve individual annotations using channel.annotations.get with examples provides a very limited use-case value. Also, same events can already be consumed in real time via annotations.subscribe.

Keeping channel.annotations.get section is fine, but a section focused on retrieving summaries under channel.subscribe with relevant examples would provide significantly more value to readers/LLMs.

So, a new Retrieve annotation summary section can be added with examples using channel.getMessage and channel.history -> Internal slack link - ways to retrieve summary

[sacOO7]

Other changes look good

[SimonWoolf]

a section focused on retrieving summaries under channel.subscribe with relevant examples would provide significantly more value

This already exists, it's the section entitled "Subscribe to annotation summaries".

[sacOO7]

Above mentioned link Internal slack link - ways to retrieve summary, Currently, 3 ways to show summaries

1. Live: subscribe to the channel message listener; the server pushes `MESSAGE_SUMMARY` actions.
2. Per-message latest: `channel.getMessage(serial).annotations.summary`.
3. Bulk historical: `channel.history()`; each `Message` already carries `annotations.summary`.

We missing section for 2nd and 3rd one, they are specific to Retrieve annotation summary rather than Subscribe to annotation summaries.

[SimonWoolf]

I don't agree that annotations.summary being a field on a message means that the annotation docs should have individual sections documenting every api we have that is capable of retrieving messages . Those apis have their own docs pages: once a user knows that the annotation summary is part of the message, they can use that knowledge together with other parts of our documentation; the annotations page need not stand in isolation.

But I am happy to add a short paragraph mentioning those two apis to document that both they will indeed give you the latest version of the summary.