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

@@ -190,19 +190,20 @@ Channel rules can be used to enforce settings for specific channels, or channel
 
 The channel rules related to message storage are:
 
-- Persist last message := if enabled, the very last message published on a channel will be stored for a year. This message is retrievable using "rewind":/docs/channels/options/rewind by attaching to the channel with @rewind=1@. If you send multiple messages in a single protocol message, for example calling @publish()@ with an array of messages, you would receive all of them as one message. Be aware that presence messages are not stored and that messages stored in this manner are not accessible using "history":/docs/storage-history/history. Note that for each message stored using this rule, an additional message is deducted from your monthly allocation.
-- Persist all messages := if enabled, all messages published on a channel will be stored according to the storage rules for your account. This is 24 hours for free accounts and 72 hours for paid accounts. Messages stored in this manner are accessible using "history":/docs/storage-history/history. Note that for each message stored using this rule, an additional message is deducted from your monthly allocation.
+- Persist last message := If enabled, the very last message published on a channel will be stored for a year. This message is retrievable using "rewind":/docs/channels/options/rewind by attaching to the channel with @rewind=1@. If you send multiple messages in a single protocol message, for example calling @publish()@ with an array of messages, you would receive all of them as one message. Be aware that presence messages are not stored and that messages stored in this manner are not accessible using "history":/docs/storage-history/history. Note that for each message stored using this rule, an additional message is deducted from your monthly allocation.
+- Persist all messages := If enabled, all messages published on a channel will be stored according to the storage rules for your account. This is 24 hours for free accounts and 72 hours for paid accounts. Messages stored in this manner are accessible using "history":/docs/storage-history/history. Note that for each message stored using this rule, an additional message is deducted from your monthly allocation.
 
 The channel rules related to security and client identity are:
 
-- Identified := if enabled, clients will not be permitted to use (including to attach, publish, or subscribe) matching channels unless they are "identified":/docs/auth/identified-clients (they have an assigned client ID). Anonymous clients are not permitted to join these channels. Find out more about "authenticated and identified clients":/docs/auth/identified-clients.
-- TLS only := if enabled, only clients who have connected to Ably over TLS will be allowed to use matching channels. By default all of Ably's client libraries use TLS when communicating with Ably over REST or when using our Realtime transports such as Websockets.
+- Identified := If enabled, clients will not be permitted to use (including to attach, publish, or subscribe) matching channels unless they are "identified":/docs/auth/identified-clients (they have an assigned client ID). Anonymous clients are not permitted to join these channels. Find out more about "authenticated and identified clients":/docs/auth/identified-clients.
+- TLS only := If enabled, only clients who have connected to Ably over TLS will be allowed to use matching channels. By default all of Ably's client libraries use TLS when communicating with Ably over REST or when using our Realtime transports such as Websockets.
 
 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.
+- Push notifications enabled := If enabled, 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.
+- Advanced message features := If enabled, advanced messaging features including message "annotations":/docs/annotations are available on the channel. Note that advanced messaging is currently Experimental and its features are still in development and subject to rapid change. Currently, when advanced messaging is enabled, messages are "persisted":/docs/storage-history/storage#all-message-persistence by default, and "continuous history":/docs/storage-history/history#continuous-history features are not currently supported.
 
 <!-- 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/errors/codes.textile

@@ -693,6 +693,20 @@ This is a client-side issue that occurs when an up-to-date "presence":/docs/pres
 * Ensure the client has an active connection before calling @presence.get()@.
 * If an outdated presence set is acceptable, set @waitForSync@ to @false@ to retrieve the presence data even when out of sync.
 
+h2(#93001). 93001: Attempt to add an annotation listener without having requested the annotation_subscribe channel mode
+
+This error occurs when attempting to "subscribe to individual annotations":/docs/messages/annotations#subscribe-individual-annotations without having requested the @annotation_subscribe@ "channel mode":/docs/channels/options#modes .
+
+*Resolution*:
+* Ensure that @annotation_subscribe@ mode is specified in the client "channel options":/docs/channels/options before subscribing to individual annotations.
+
+h2(#93002). 93002: Annotations are only supported on channels with the Mutable Messages feature enabled
+
+This error occurs when attempting to use "message annotations":/docs/messages/annotations on a channel that does not have Mutable Messages enabled.
+
+*Resolution*:
+* Create a "channel rule":/docs/channels#rules for the channel or channel namespace with Mutable Messages enabled.
+
 h2(#101000). 101000: Space name missing
 
 This error occurs when calling "@spaces.get()@":/docs/spaces/space#options without specifying a space name. The name parameter is required to retrieve a space.

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',
+        },
       ],
     },
     {