chat: add react message reactions examples, restructure message reactions page by owenpearson · Pull Request #2653 · ably/docs

owenpearson · 2025-06-06T17:41:56Z

adds react code examples for message reactions
restructures the page so that reaction types and the default type are explained before 'how to actually send a reaction'.

coderabbitai · 2025-06-06T17:42:03Z

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

AndyTWF · 2025-06-09T08:18:40Z


-The default reaction type can be configured at room-level using the Room Options. If nothing is set, the default is `Distinct`.
+<If lang="react">
+Use the [`deleteReaction()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_react.UseMessagesResponse.html#deleteReaction) method available from the response of the `useMessages` hook to remove a reaction from a message. This method takes the following parameters:


Suggested change

Use the [`deleteReaction()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_react.UseMessagesResponse.html#deleteReaction) method available from the response of the `useMessages` hook to remove a reaction from a message. This method takes the following parameters:

Use the [`deleteReaction()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#deleteReaction) method available from the response of the `useMessages` hook to remove a reaction from a message. This method takes the following parameters:

AndyTWF · 2025-06-09T08:19:49Z

+
 ## Messages and reactions <a id="messages-and-reactions"/>

 The `Message` object contains a `reactions` property which is an object that looks like this:


Need to add equivalent language option for React here or it says this feature isn't available in React

Annoyingly I couldn't find a way to say "This code block should appear for javascript AND react", so have just duplicated the javascript one for now

Mmm, I didn't add this as a requirement for the move to MDX because I wanted to get away from always duplicating JS and Node. I can't believe it happens that often between React and JS to be an issue though, right?

well any snippet like this which is just explaining a return type of an API will probably be identical for both, the react APIs are only different from js in terms of how you use them, what they actually return should always be the same. I have no idea how many snippets overall would fit into this category though 🤷

AndyTWF · 2025-06-09T08:24:02Z

+```
 </Code>

 The `annotation-subscribe` capability is required for receiving individual reactions, however it is not required to receive summaries.


Ditto above re putting this into a callout box for extra visibility

m-hulbert

Just a few comments 🙂

m-hulbert · 2025-06-11T08:52:15Z

+| Type | Description | Example | Similar to |
+| ---- | ----------- | ------- | --------- |
+| `Unique` | A user can react to a message only once, with a reaction of their choice. When a user reacts a second time their reaction is changed. | Can 👍 or ❤️ but not both or more than once. | iMessage, WhatsApp, Facebook Messenger |
+| `Distinct` | A user can react to a message with each reaction at most once. | Can 👍 and ❤️ but each reaction only once. No 👍👍. | Slack |


have improved the wording here 👍

m-hulbert · 2025-06-11T08:57:13Z

+
+### Configure the default reaction type <a id="default-type"/>
+
+The default reaction type can be configured at room-level using the Room Options. If nothing is set, the default is `Distinct`.


RoomOption. Should we also state which option this falls under - though we don't seem to have any reference to MessageOptions in the rooms page, nor in the messages page (or here).

have also improved the wording here. it's a lot easier to just show how room options are used in an example (which we're doing in the snippet below) than to describe exactly what the API is, but i think what i have now is more clear either way

m-hulbert · 2025-06-11T08:59:01Z

+<If lang="javascript,swift,kotlin">
 To add a message reaction use `room.messages.reactions.send(message, params)`. This method takes the following parameters:
-* `message` - The message to add the reaction to. It can also be an object of format `{serial: "message serial"}`.
+* `message` - The message to add the reaction to. This can be a Message object, or just the string serial.


Should this be more like 'the serial of a message' rather than 'the string serial'?

good spot, have updated all descriptions of this argument

m-hulbert · 2025-06-11T09:04:26Z

+<If lang="javascript,swift,kotlin">
+Raw individual reactions are published for every reaction, unlike summaries which can be rolled up. Raw reactions are useful for receiving all reaction events, but they are not suitable for the purpose of displaying message reaction counts as their effect on the reactions summary depends on the previous reactions.
+
+Individual reactions are not received by default to save bandwidth and to reduce the number of messages and cost. If you want to receive them, you can configure them via a room option which, in turn, sets the appropriate channel options to enable receiving individual annotations and reactions:


RoomOption.

Also do we need to let them know that it sets the associated ChannelOption? I think it's somewhat irrelevant.

More broadly, I think we should explain what summaries are, and that they are the default behaviour before we start talking about subscribing to them (them being raw events).

As an aside.. Is 'raw event' the correct term? Does 'individual reactions' or something make more sense?

This was actually already here, my PR just duplicated it for react but i've reverted that change. "raw" events is the correct term because the feature is called rawReactions in the API. And tbh i think the previous section adequately describes how summary reactions work, enough for this section to make sense. I agree that the channel options part is irrelevant so have removed that 👍

AndyTWF · 2025-06-30T18:12:21Z

+
+### Configure the default reaction type <a id="default-type"/>
+
+The default reaction type can be configured at room-level by passing `RoomOptions` when calling `rooms.get`. If nothing is set, the default is `Distinct`.


This sentence doesn't apply to React - with React it's the options passed to the ChatRoomProvider

ah good spot, have wrapped in an thingy with a case for react

AndyTWF · 2025-06-30T18:13:43Z

+import { ChatRoomProvider } from '@ably/chat/react';
+
+const MyComponent = () => {
+  const roomOptions = {


This would need to be outside the component or memoised, as the provide doesn't do that

have moved it outside the component scope. to be fair, it costs basically nothing to redeclare a static object and i don't think this component would ever re-render anyway but agree it's slightly neater 👍

AndyTWF · 2025-06-30T18:18:43Z

+
+  return <div>...</div>;
+};
+```


Not this PR, but the @ in the timeserial comes out a bit odd in the table below

AndyTWF · 2025-06-30T18:19:06Z

+import { ChatRoomProvider } from '@ably/chat/react';
+
+const MyComponent = () => {
+  const roomOptions = {


Ditto re room options memoisation

owenpearson requested review from AndyTWF and m-hulbert June 6, 2025 17:41

ably-ci temporarily deployed to ably-docs-chat-docs-imp-ncycru June 6, 2025 17:42 Inactive

AndyTWF reviewed Jun 9, 2025

View reviewed changes

owenpearson force-pushed the chat-docs-improvements branch from 1b42d5b to cad7d52 Compare June 10, 2025 16:54

owenpearson requested a review from AndyTWF June 10, 2025 16:57

m-hulbert reviewed Jun 11, 2025

View reviewed changes

owenpearson force-pushed the chat-docs-improvements branch from a6d7790 to c7e8c19 Compare June 26, 2025 15:32

owenpearson requested a review from m-hulbert June 26, 2025 15:40

AndyTWF reviewed Jun 30, 2025

View reviewed changes

owenpearson added 13 commits July 8, 2025 21:23

chat: add react examples for message reactions

f5bbdd4

restructure reactions page

71c733b

chat: improvements to message reactions docs

d2483d9

chat: put reactions capability requirements in callouts

c46f4e7

chat: remove pub/sub annotation type from reaction types table

53f88fb

chat: add react Messages and Reactions snippet

b467f10

chat: improve message reaction type descriptions

fcf0996

chat: clarify how message reaction room options are configured

73d5f61

chat: improve reaction send argument description

6935ec1

chat: fix duplication of raw reactions description

7d31079

chat: improve raw reactions description

112fac1

chat: clarify room options API for react

f3b444e

chat: rename addReaction -> sendReaction

059aaa0

owenpearson force-pushed the chat-docs-improvements branch from c271ce5 to ba68805 Compare July 8, 2025 20:37

owenpearson requested a review from AndyTWF July 8, 2025 20:37

chat: declare roomOptions outside example component

ac8d6b0

owenpearson force-pushed the chat-docs-improvements branch from ba68805 to ac8d6b0 Compare July 8, 2025 20:41

AndyTWF approved these changes Jul 9, 2025

View reviewed changes

owenpearson merged commit 48cedc9 into main Jul 9, 2025
6 checks passed

owenpearson deleted the chat-docs-improvements branch July 9, 2025 09:11

	Use the [`deleteReaction()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_react.UseMessagesResponse.html#deleteReaction) method available from the response of the `useMessages` hook to remove a reaction from a message. This method takes the following parameters:
	Use the [`deleteReaction()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#deleteReaction) method available from the response of the `useMessages` hook to remove a reaction from a message. This method takes the following parameters:


		## Messages and reactions <a id="messages-and-reactions"/>

		The `Message` object contains a `reactions` property which is an object that looks like this:

	\| `Distinct` \| A user can react to a message with each reaction at most once. \| Can 👍 and ❤️ but each reaction only once. No 👍👍. \| Slack \|
	\| `Distinct` \| A user can react to a message with each reaction at most once. \| Can 👍 and ❤️ but only once per reaction. No 👍👍. \| Slack \|


		### Configure the default reaction type <a id="default-type"/>

		The default reaction type can be configured at room-level using the Room Options. If nothing is set, the default is `Distinct`.

Conversation

owenpearson commented Jun 6, 2025

Uh oh!

coderabbitai Bot commented Jun 6, 2025

Review skipped

Chat

Support

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

m-hulbert 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!

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!

m-hulbert Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

CodeRabbit Configuration File (`.coderabbit.yaml`)

m-hulbert Jun 11, 2025 •

edited

Loading