Today, we’re excited to introduce Annotations in Ably Pub/Sub, a powerful way to enrich your realtime streams with structured, abstracted data.
Annotations let you layer context onto messages, from emojis and read receipts to custom tags and beyond. Think of them as stickers of information you can attach to messages, tracking and aggregating them however you need.
Annotations are built directly into Ably Pub/Sub, making them available for any realtime application you’re working on, whether it’s collaborative chat, IoT sensor streams, live trading data, or collaborative documents.
This opt-in, low-level feature gives you total flexibility to create and shape interactive, meaningful message streams.
Annotation types
Let’s take a closer look at the different types of annotations you can use. We’ll use message reactions as the example here, but the underlying concepts apply across any realtime data stream you’re building.
| Annotation type | Behavior | Example use case |
|---|---|---|
| Total | Tracks the cumulative count of annotations, regardless of value or user. | Use for aggregate counts, like a simple “like” or “upvote” counter. |
| Distinct | Allows multiple annotation values per user, but only one instance of each value. Multiple users can share the same value. | Works like Slack reactions - a user can add both 👍 and ❤️ to a message, but only once per reaction type. |
| Unique | Restricts each user to one annotation value per message. | Works like WhatsApp reactions - a user can react with 👍 or ❤️, but not both. |
| Multiple | Allows users to send the same annotation multiple times per value. | GIdeal for repeated actions, like goal celebrations where users can send 🎉 multiple times. |
| Flag | Represents a binary user state - flagged or unflagged. Each user can flag a message once, and multiple users can flag the same message. | Use for moderation workflows, e.g. flagging a message for review or follow-up. |
Beyond reactions: Annotations for any data stream
While emoji reactions are a familiar example, annotations are designed to be much more than a single-use feature. They open the door to a wide range of possibilities beyond chat, including:
- Live sports data feeds: Broadcasters or fans can tag significant moments like goals, fouls, or player substitutions in realtime match data streams. These tags can later power highlight reels, dynamic leaderboards, or instant replays.
- IoT data: Operators can add context to realtime sensor data, flagging anomalies that need investigation, or tagging specific events with quick notes. This makes IoT dashboards more than just data, they become collaborative, interactive tools.
- Live trading streams: Financial analysts and traders can instantly annotate market events, such as flagging key price moves, sharing commentary, or adding contextual tags to historical data - all in realtime.
- Transportation & logistics tracking: In a supply chain monitoring system, operators can highlight delays, mark points of interest (like completed stops), or annotate realtime fleet updates with issues or notes for future reference.
These are just a few ways to bring annotations to life in your realtime streams. Ultimately, the floor is yours - we’re excited to see how you’ll take this foundation and build the next layer of interactive experiences.
Getting started
Annotations are part of the Ably Pub/Sub API and require enabling the mutableMessages channel rule to support them. You’ll find a complete guide in our Annotations documentation to walk you through configuration and integration.
For a quick example, here’s what adding an emoji reaction to a message looks like in JavaScript:
const channel = ably.channels.get('my-channel');
channel.annotations.publish(message, 'reaction:distinct.v1', '👍');
As you can see, annotations add a rich layer of interactivity and context, no matter the domain. And this is only the beginning: we’re already working on bringing edit and delete capabilities to your messages, so stay tuned!
Annotations are currently available in our JavaScript, Cocoa, and Java SDKs, with support for more coming soon. We can’t wait to see the creative ways you’ll bring annotations to life.
