chat message reactions #319

vladvelici · 2025-05-07T15:54:38Z

Add spec for message reactions.

AndyTWF · 2025-05-12T11:01:07Z

textile/chat-features.textile

+* @(CHA-M11)@ A @Message@ must have a method @with@ to apply changes from events (@MessageEvent@ and @MessageReactionSummaryEvent@) to produce updated message instances.
+  ** @(CHA-M11a)@ @[Testable]@ When the method receives a @MessageEvent@ of type @created@, it must throw an @ErrorInfo@ with code @40000@ and status code @400@.
+  ** @(CHA-M11b)@ @[Testable]@ For @MessageEvent@ the method must verify that the @message.serial@ in the event matches the message's own serial. If they don't match, an error with code @40000@ and status code @400@ must be thrown.
+  ** @(CHA-M11c)@ @[Testable]@ For @MessageEvent@ of type @update@ and @delete@, if the event's @message.version@ is less than or equal to the current message's @version@, the original message must be returned unchanged.


Worth referencing this to CHA-M10 here, rather than explaining sortability again?

AndyTWF · 2025-05-12T11:04:01Z

textile/chat-features.textile

+  ** @(CHA-M11e)@ @[Testable]@ For @MessageReactionSummaryEvent@, the method must verify that the @summary.messageSerial@ in the event matches the message's own serial. If they don't match, an error with code @40000@ and status code @400@ must be thrown.
+  ** @(CHA-M11f)@ @[Testable]@ For @MessageReactionSummaryEvent@, the method must return a new @Message@ instance (deep copy) with the updated reactions, preserving all other properties of the original message.
+  ** @(CHA-M11g)@ @[Testable]@ For @MessageReactionSummaryEvent@, the method must deep-copy the reactions from the event before applying them to the returned message instance.
+  ** @(CHA-M11h)@ @[Testable]@ The method must not alter the original message instance.


This point is already covered in the points above, so is redundant

AndyTWF · 2025-05-12T11:04:32Z

textile/chat-features.textile

+
+Users can add reactions to messages, such as thumbs-up or heart emojis. Summaries (counts per reaction name, and who reacted) of the message reactions are stored with the message and are visible to all users in the room. Message reactions are powered by Pub/Sub message annotations.
+
+@MessagesReactions@ object is the entry point for interacting with Message Reactions. It shall be exposed to consumers via a @reactions@ property insde the @Messages@ obejct. From the @Room@ level: @room.messages.reactions@.


Suggested change

@MessagesReactions@ object is the entry point for interacting with Message Reactions. It shall be exposed to consumers via a @reactions@ property insde the @Messages@ obejct. From the @Room@ level: @room.messages.reactions@.

@MessagesReactions@ object is the entry point for interacting with Message Reactions. It shall be exposed to consumers via a @reactions@ property inside the @Messages@ obejct. From the @Room@ level: @room.messages.reactions@.

Thanks, I've copy-pasted this locally, in a rebased.

AndyTWF · 2025-05-12T11:06:30Z

textile/chat-features.textile

+* @(CHA-MR1)@ Message reactions are powered by Pub/Sub message annotations. The annotation type used is of the format @reaction:<aggregation>@.
+
+* @(CHA-MR2)@ There are three types of message reactions, each corresponding to a different annotation aggregation type.
+  ** @(CHA-MR2a)@ @[Testable]@ Reactions of type @Unique@ use the annotation type @reaction:unique.v1@. In this type, each client can add only one reaction (by @name@). Reacting again changes the reaction to the new one (similar to WhatsApp or iMessage).


Is this testable? What are we testing here? It feels like the testable bit would be where we say "if you receive reaction of type X, then do Y"

Removed testable, this is just explaining the reaction types but not specifically tied to an action/behaviour.

AndyTWF · 2025-05-12T11:08:22Z

textile/chat-features.textile

+  ** @(CHA-MR3b3)@ @[Testable]@ For @Distinct@ reaction types, the summary is at @Message.reactions.distinct@ and is of type @Dict<string, SummaryClientIdList>@ (see @TM7b1@).
+  ** @(CHA-MR3b2)@ @[Testable]@ For @Multiple@ reaction types, the summary is at @Message.reactions.multiple@ and is of type @Dict<string, SummaryClientIdCounts>@ (see @TM7b3@).
+
+* @(CHA-MR4)@ @[Testable]@ Sending a reaction is done via the @add@ method of the @MessagesReactions@ object (@room.messages.reactions.add@). The method accepts a message (or message serial), and a @params@ object where the @name@ (ie. emoji string), @type@ (optional) and @count@ (optional, only valid for type @multiple@) are specified.


This is quite a long point with lots of optionals. Can we split it up at all?

AndyTWF · 2025-05-12T11:09:36Z

textile/chat-features.textile

+
+* @(CHA-MR5)@ @[Testable]@ Users may configure a default message reactions type for a room. This configuration is provided at the @RoomOptions.messages.defaultMessageReactionType@ property, or idiomatic equivalent. The default value is @distinct@.
+
+* @(CHA-MR6)@ @[Testable]@ Subscribing to message reactions is done via the @subscribe@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribe@). The method accepts a callback (or similar idomatic construct) that receives message reactions summary events of type @MessageReactionSummaryEvent@.


In rest of the specification, we describe behaviour like this in terms of user outcome - i.e. "users must be able to X".

Done here and some other places

AndyTWF · 2025-05-12T11:12:57Z

textile/chat-features.textile

+* @(CHA-MR8)@ @[Testable]@ Subscribing to raw message reactions (as individual annotations) is done via the @subscribeRaw@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribeRaw@). The method accepts a callback (or similar idomatic construct) that receives individual annotations of type @MessageReactionRawEvent@.
+* @(CHA-MR8a)@ @[Testable]@ Subscribing to raw message reactions throws an error if the room is not configured to support raw message reactions by setting room option @RoomOptions.messages.rawMessageReactions@ to @true@ (defaults to @false@).
+
+* @(CHA-MR9)@ The @MessageReactionRawEvent@ interface provides information about individual message reaction events.


We have talked for a while about having an IDL for Chat. Should we move these points into an IDL section (i.e. an interface definition of the type), and perhaps just have spec points cover specific behvaiour we expect for each one (beyond plain old data)?

Moved those next to where the example data for them is given as well.

AndyTWF · 2025-05-12T11:13:39Z

textile/chat-features.textile

+* @(CHA-MR10)@ @[Testable]@ The room option @RoomOptions.messages.rawMessageReactions@ controls whether raw message reactions are enabled or not. The default value is @false@. 
+  ** @(CHA-MR10a)@ @[Testable]@ If the room option is set to @true@, the SDK will add the @ANNOTATION_SUBSCRIBE@ channel mode to the realtime channel used for the room.
+
+* @(CHA-MR11)@ @[Testable]@ The SDK always adds the @ANNOTATION_PUBLISH@ channel mode to the realtime channel used for the room.


Suggested change

* @(CHA-MR11)@ @[Testable]@ The SDK always adds the @ANNOTATION_PUBLISH@ channel mode to the realtime channel used for the room.

* @(CHA-MR11)@ @[Testable]@ The client must always add the @ANNOTATION_PUBLISH@ channel mode to the realtime channel used for the room.

Applied locally, thanks.

AndyTWF

Just a couple more comments and we should be good to go :)

AndyTWF · 2025-05-22T08:51:30Z

textile/chat-features.textile

+* @(CHA-MR6)@ @[Testable]@ Users must be able to subscribe to message reaction summaries via the @subscribe@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribe@). The method accepts a callback (or similar idiomatic construct) that receives message reactions summary events of type @MessageReactionSummaryEvent@.
+
+* @(CHA-MR7)@ @[Testable]@ Users must be able to subscribe to raw message reactions (as individual annotations) via the @subscribeRaw@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribeRaw@). This method accepts a callback (or similar idiomatic construct) that receives individual annotations of type @MessageReactionRawEvent@.
+  ** @(CHA-MR7a)@ @[Testable]@ The attempt to subscribe to raw message reactions must fail with an error if the room is not configured to support raw message reactions (when room option @RoomOptions.messages.rawMessageReactions@ is not set to @true@; it defaults to @false@).


What error code?

AndyTWF · 2025-05-22T08:54:57Z

textile/chat-features.textile

+
+* @(CHA-MR5)@ @[Testable]@ Users may configure a default message reactions type for a room. This configuration is provided at the @RoomOptions.messages.defaultMessageReactionType@ property, or idiomatic equivalent. The default value is @distinct@.
+
+* @(CHA-MR6)@ @[Testable]@ Users must be able to subscribe to message reaction summaries via the @subscribe@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribe@). The method accepts a callback (or similar idiomatic construct) that receives message reactions summary events of type @MessageReactionSummaryEvent@.


I think we shouldn't reference callbacks explicitly here - as in Swift/Kotlin you may not pass in a callback at all, but simply return a flow object that "acts" as the callback

AndyTWF · 2025-05-22T08:55:30Z

textile/chat-features.textile

+* @(CHA-MR7)@ @[Testable]@ Users must be able to subscribe to raw message reactions (as individual annotations) via the @subscribeRaw@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribeRaw@). This method accepts a callback (or similar idiomatic construct) that receives individual annotations of type @MessageReactionRawEvent@.
+  ** @(CHA-MR7a)@ @[Testable]@ The attempt to subscribe to raw message reactions must fail with an error if the room is not configured to support raw message reactions (when room option @RoomOptions.messages.rawMessageReactions@ is not set to @true@; it defaults to @false@).
+
+* @(CHA-MR8)@ Raw message reactions should not be used to update the message reaction summary on the client-side as this is likely to produce wrong results. Message reaction summaries are to be used for this.


I think this one should be a "must"

…, and avoid implying callbacks

sacOO7 · 2025-06-23T09:33:18Z

textile/chat-features.textile

+* @(CHA-MR4)@ @[Testable]@ Users should be able to send a reaction via the `add` method of the `MessagesReactions` object (@room.messages.reactions.add@).
+** @(CHA-MR4a)@ @[Testable]@ The `add` method accepts a message (or message serial) as the first parameter to identify which message to react to.
+** @(CHA-MR4b)@ @[Testable]@ The `add` method accepts a `params` object as the second parameter with the following properties:
+*** @(CHA-MR4b1)@ @[Testable]@ A `name` property (required) specifying the reaction identifier (e.g., emoji string).


Can we add non-empty client check for name property?

github-actions bot temporarily deployed to staging/pull/319 May 7, 2025 15:55 Inactive

vladvelici force-pushed the chat-message-reactions branch from 51f754b to 077c262 Compare May 7, 2025 23:02

github-actions bot temporarily deployed to staging/pull/319 May 7, 2025 23:02 Inactive

github-actions bot temporarily deployed to staging/pull/319 May 7, 2025 23:10 Inactive

github-actions bot temporarily deployed to staging/pull/319 May 9, 2025 10:57 Inactive

AndyTWF reviewed May 12, 2025

View reviewed changes

Base automatically changed from chat-single-channel to integration/single-channel-migration May 21, 2025 10:49

AndyTWF force-pushed the integration/single-channel-migration branch from 2a12630 to a458c4c Compare May 21, 2025 11:02

Base automatically changed from integration/single-channel-migration to main May 21, 2025 11:32

vladvelici added 3 commits May 21, 2025 23:46

Add chat message reactions spec

a4fe577

update message reaction spec to rename 'reaction' field to 'name'

a7dfe66

improve message reactions spec based on PR feedback

de30fe7

vladvelici force-pushed the chat-message-reactions branch from 3db3be7 to de30fe7 Compare May 22, 2025 08:39

github-actions bot temporarily deployed to staging/pull/319 May 22, 2025 08:39 Inactive

vladvelici requested a review from AndyTWF May 22, 2025 08:40

AndyTWF reviewed May 22, 2025

View reviewed changes

add specific error codes, not using raw reactions for state is a must…

ef0d3e5

…, and avoid implying callbacks

vladvelici requested a review from AndyTWF May 22, 2025 11:35

github-actions bot deployed to staging/pull/319 May 22, 2025 11:36 View deployment

AndyTWF approved these changes May 23, 2025

View reviewed changes

vladvelici merged commit 47e44d8 into main May 23, 2025
2 checks passed

vladvelici deleted the chat-message-reactions branch May 23, 2025 10:14

sacOO7 mentioned this pull request Jun 18, 2025

[ECO-5065] feat: add message reactions feature to chat API ably/ably-chat-kotlin#139

Merged

sacOO7 reviewed Jun 23, 2025

View reviewed changes


		Users can add reactions to messages, such as thumbs-up or heart emojis. Summaries (counts per reaction name, and who reacted) of the message reactions are stored with the message and are visible to all users in the room. Message reactions are powered by Pub/Sub message annotations.

		@MessagesReactions@ object is the entry point for interacting with Message Reactions. It shall be exposed to consumers via a @reactions@ property insde the @Messages@ obejct. From the @Room@ level: @room.messages.reactions@.


		* @(CHA-MR5)@ @[Testable]@ Users may configure a default message reactions type for a room. This configuration is provided at the @RoomOptions.messages.defaultMessageReactionType@ property, or idiomatic equivalent. The default value is @distinct@.

		* @(CHA-MR6)@ @[Testable]@ Subscribing to message reactions is done via the @subscribe@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribe@). The method accepts a callback (or similar idomatic construct) that receives message reactions summary events of type @MessageReactionSummaryEvent@.

	* @(CHA-MR11)@ @[Testable]@ The SDK always adds the @ANNOTATION_PUBLISH@ channel mode to the realtime channel used for the room.
	* @(CHA-MR11)@ @[Testable]@ The client must always add the @ANNOTATION_PUBLISH@ channel mode to the realtime channel used for the room.


		* @(CHA-MR5)@ @[Testable]@ Users may configure a default message reactions type for a room. This configuration is provided at the @RoomOptions.messages.defaultMessageReactionType@ property, or idiomatic equivalent. The default value is @distinct@.

		* @(CHA-MR6)@ @[Testable]@ Users must be able to subscribe to message reaction summaries via the @subscribe@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribe@). The method accepts a callback (or similar idiomatic construct) that receives message reactions summary events of type @MessageReactionSummaryEvent@.

chat message reactions #319

chat message reactions #319

Uh oh!

Conversation

vladvelici commented May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AndyTWF left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vladvelici commented May 7, 2025 •

edited

Loading