Feature/pub 1676 message annotations

content/auth/capabilities.textile

@@ -44,6 +44,8 @@ The following capability operations are available for API keys and issued tokens
 - presence := can register presence on a channel (enter, update and leave)
 - object-subscribe := can subscribe to updates to objects on a channel
 - object-publish := can update objects on a channel
+- annotation-subscribe := can subscribe to individual annotations on a channel
+- annotation-publish := can publish annotations to messages on a channel
 - history := can retrieve message and presence state history on channels
 - stats := can retrieve current and historical usage statistics for an app
 - push-subscribe := can subscribe devices for push notifications

content/channels/index.textile

@@ -203,6 +203,7 @@ The channel rules related to enabling features are:
 - Push notifications enabled := If checked, publishing messages with a push payload in the @extras@ field is permitted. This triggers the delivery of a "Push Notification":/docs/push to devices registered for push on the channel.
 - Server-side batching := if enabled, messages are grouped into batches before being sent to subscribers. "Server-side batching":/docs/messages/batch#server-side reduces the overall message count, lowers costs, and mitigates the risk of hitting rate limits during high-throughput scenarios.
 - Message conflation := if enabled, messages are aggregated over a set period of time and evaluated against a conflation key. All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses. "Message conflation":/docs/messages#conflation reduces costs in high-throughput scenarios by removing redundant and outdated messages.
+- Annotations := if enabled, allows use of message "annotations":/docs/annotations .
 
 <!-- DASHBOARD-INSTRUCTION: Setting a channel rule -->
 To set a channel rule in the Ably dashboard:

content/channels/options/index.textile

@@ -431,6 +431,8 @@ The available set of channel mode flags are:
 | @PRESENCE@ | Can register presence on the channel. | Yes |
 | @OBJECT_PUBLISH@ | Can update objects on the channel. | No |
 | @OBJECT_SUBSCRIBE@ | Can subscribe to receive updates to objects on the channel. | No |
+| @ANNOTATION_PUBLISH@ | Can publish annotations to messages on the channel. | Yes |
+| @ANNOTATION_SUBSCRIBE@ | Can subscribe to individual annotations on the channel. | No |
 
 The set of modes available to a client is determined by the set of "capabilities":/docs/auth/capabilities granted by their token or API key.
 
@@ -442,6 +444,8 @@ The modes granted by each capability are:
 | @presence@ | @PRESENCE@ |
 | @object-subscribe@ | @OBJECT_SUBSCRIBE@ |
 | @object-publish@ | @OBJECT_PUBLISH@ |
+| @annotation-publish@ | @ANNOTATION_PUBLISH@ |
+| @annotation-subscribe@ | @ANNOTATION_SUBSCRIBE@ |
 
 The actual modes assigned to a client will be the **intersection** of the requested @modes@ and the modes available to the client according to its capabilities. For example, a client with the @subscribe@ capability which explicitly requests @SUBSCRIBE@ and @PUBLISH@ modes will be assigned only the @SUBSCRIBE@ mode.
 

content/messages/index.textile

@@ -34,6 +34,10 @@ The following are the properties of a message:
 - extras := A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include those related to "Push Notifications":/docs/push, "deltas":/docs/channels/options/deltas and headers.
 - encoding := This is typically empty, as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute contains the remaining transformations not applied to the data payload.
 
+<aside data-type='note'>
+<p>Additional properties are included on a message when using message "annotations":/docs/messages/annotations .</p>
+</aside>
+
 h2(#conflation). Message conflation
 
 Use message conflation to ensure that clients only ever receive the most up-to-date message, by removing redundant and outdated messages. Message conflation will aggregate published messages for a set period of time and evaluate all messages against a "conflation key":#routing. All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses.

content/partials/core-features/_authentication_capabilities.textile

@@ -5,6 +5,8 @@ The following capability operations are available for API keys and issued tokens
 - presence := can register presence on a channel (enter, update and leave)
 - object-subscribe := can subscribe to updates to objects on a channel
 - object-publish := can update objects on a channel
+- annotation-subscribe := can subscribe to individual annotations on a channel
+- annotation-publish := can publish annotations to messages on a channel
 - history := can retrieve message and presence state history on channels
 - stats := can retrieve current and historical usage statistics for an app
 - push-subscribe := can subscribe devices for push notifications

content/pub-sub/index.textile

@@ -444,4 +444,5 @@ if err := channel.Publish(context.Background(), "example", "message data"); err
 <aside data-type='further-reading'>
 <p>You can find out more detail about how "channels":/docs/channels and "messages":/docs/messages work.</p>
 <p>There are also more advanced ways that you can "subscribe":/docs/pub-sub/advanced#subscribe to channels, and "publish":/docs/pub-sub/advanced#publish messages, such as applying filters to your subscriptions or having a server publish messages on behalf of a client.</p>
+<p>"Annotate":/docs/messages/annotations messages to add reactions, categorization, and other metadata to messages.</p>
 </aside>

src/data/nav/pubsub.ts

@@ -146,6 +146,10 @@ export default {
           name: 'Message batching',
           link: '/docs/messages/batch',
         },
+        {
+          name: 'Message annotations',
+          link: '/docs/messages/annotations',
+        },
       ],
     },
     {