AblyDocs

Message annotations

Message annotations enable clients to append information to existing messages on a channel. You can use annotations to implement features like:

  • Message reactions - add emoji reactions (👍, ❤️, 😂) to messages
  • Content categorization - tag messages with categories such as "important" or "urgent"
  • Community moderation - flag inappropriate content for review
  • Read receipts - mark messages as "read" or "delivered"
  • Comments - clients can comment on a message, which will not show up in normal channel history, but which can be loaded on demand

When clients publish or delete an annotation, Ably automatically creates a summary that provides an aggregated view of all annotations for the associated message.

Enable annotations

Annotations can be enabled for a channel or set of channels with the Message annotations, updates, deletes, and appends rule.

In your app settings:

  1. Click Add new rule.
  2. Enter the match expression selecting the channels on which to enable message annotations, such as annotations:*.
  3. Check Message annotations, updates, deletes, and appends.
  4. Click Create rule to save.

Annotation types

Annotation types determine how annotations are processed and aggregated into summaries.

The annotation type is a string of the format namespace:summarization.version where:

  • namespace is a string (e.g. reactions) that groups related annotations. Only annotations in the same namespace will be aggregated to produce summaries.
  • summarization specifies how annotations are aggregated to produce summaries, such as total, flag, distinct, unique, or multiple.
  • version specifies the version component which allows for future changes to summarization behavior.

Total

The total.v1 summarization method keeps a running total of the number of annotations (minus the number of deletions) of a given type that were published for a message.

Using total.v1 does not attribute counts to individual clients in the summary. It maintains only a simple count per annotation type.

That means that unidentified clients can publish total.v1 annotations. It also means that there's no such thing as deleting a particular annotation; publishing a DELETE simply decrements the total for a given type (even if it goes below zero). (In contrast to, say, flag.v1, where a DELETE deletes your clientId's contribution). For the same reason, if the same client publishes an annotation of a given type to the same message multiple times, the total count will keep incrementing each time.

JSON

1

2

3

4

5

{
  "metrics:total.v1": {
    "total": 42
  }
}

Flag

The flag.v1 summarization method counts how many distinct clients have published an annotation of a given type and maintains a list of those clientIds. Clients must be identified to publish flag.v1 annotations.

Deleting an annotation decrements the total count for that message and removes the clientId from the list of clients that contributed to the summary.

A given client can contribute to the summary only once per annotation type.