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: af0ef64d-de4a-4bf5-b6d5-f32dca2ff5b6

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

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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.

[sacOO7]

Suggested change

	<Aside data-type='note'>
	You should only use this method if you need the full list of individual, raw annotations. If you only need the latest [annotation summary](#annotation-summaries) for a message — for example on a channel you are not subscribed to, where you are not receiving `message.summary` updates — use [`channel.getMessage()`](/docs/messages/updates-deletes#get) instead. The returned message contains the up-to-date `annotations.summary`.
	<Aside data-type='note'>
	You should only use this method if you need the full list of individual, raw annotations. If you only need the latest [annotation summary](#annotation-summaries) for a message — for example on a channel you are not subscribed to, where you are not receiving `message.summary` updates — use [`channel.getMessage()`](/docs/messages/updates-deletes#get) instead. The returned `message` contains the up-to-date `summary`, accessible via `message.annotations.summary`.

[sacOO7]

Thanks — I suggested a few minor changes to make the access to the summary more explicit. This should help both third person readers and LLMs better understand the context.
Otherwise, the PR looks much better than before.

[sacOO7]

Suggested a few minor changes, this should help both third person reader and LLMs better understand the context.
Otherwise, the PR looks much better than before.

[owenpearson]

seems like in most of these we have a separate <If> for python even though the inner text is the same as other languages? for messageSerial we also have a separate tag for java when it's not necessary

[owenpearson]

neither javascript not python have a type called Integer

[SimonWoolf]

True. But if you go to https://ably.com/docs/api/realtime-sdk/types, select javascript, and ctrl-f "Integer", you get 24 results. Presumably at some point someone thought it was worth giving a more semantically-meaningful type even if the actual language's type is looser. If you disagree, feel free to raise a separate pr to change all of them at once, but for this change I'll sticking to the existing pattern

[owenpearson]

lgtm 👍