one round of fixes based on comments

vladvelici · vladvelici · commit 3043e2295dc2 · 2025-10-29T10:00:01.000Z
diff --git a/src/pages/docs/guides/chat/build-task-oriented.mdx b/src/pages/docs/guides/chat/build-task-oriented.mdx
@@ -23,7 +23,7 @@ Ably is trusted by organizations delivering chat to millions of users in realtim
 
 ![Ably Architecture Overview Diagram](../../../../images/content/diagrams/architecture-overview.png)
 
-Delivering chat messages in realtime is key to an engaging experience. Ably's [serverless architecture](/docs/platform/architecture) eliminates the need for you to manage websocket servers. It automatically scales to handle millions of concurrent connections without provisioning or maintenance. Ably also handles all of the edge-cases around delivery, failover and scaling.
+Delivering chat messages in realtime is key to a smooth online experience. Ably's [serverless architecture](/docs/platform/architecture) eliminates the need for you to manage websocket servers. It automatically scales to handle millions of concurrent connections without provisioning or maintenance. Ably also handles all of the edge-cases around delivery, failover and scaling.
 
 Despite the challenges of delivering these guarantees, Ably is designed to keep costs predictable.
 You can choose between MAU-based or per-minute pricing, depending on your needs.
@@ -36,7 +36,7 @@ The most important decision when developing task-oriented chat is the experience
 
 **What are task-oriented chats?** Any chat that serves as a companion to a specific activity or workflow: resolving a support ticket, coordinating a delivery, discussing a chess game, collaborating on a project, or facilitating a marketplace transaction. These chats are typically short-lived (minutes to days) and highly contextual. They can be 1:1 or small group conversations.
 
-For large-scale chat scenarios, see our [building livestream chat guide](/docs/guides/chat/build-livestream).
+For large-scale chat scenarios with many users per room, see our [building livestream chat guide](/docs/guides/chat/build-livestream).
 
 **Task-oriented room architecture:** The optimal approach is one chat room per task, where all participants join to communicate within that specific context. Rooms are:
 
@@ -60,10 +60,10 @@ With MAU-based pricing you will only be charged for the number of unique active
 
 In task-oriented chat, each room is typically low throughput. Scaling comes by running as many rooms as you need at the same time. Ably handles everything from 1:1 conversations and small group discussions to [livestream chats](/docs/guides/chat/build-livestream) with the same reliability and scalability guarantees.
 
-Chat rooms (and Pub/Sub channels) scale horizontally. Ably allows you to have as many rooms as you need running in parallel.
+Chat rooms scale horizontally. Ably allows you to have as many rooms as you need running in parallel.
 
 * **Proven at scale:** Ably delivers over 500 million messages per day for customers.
-* **Rate limiting:** Prevent spam and maintain conversation quality with per-user rate limits or global throttling appropriate for your use case.
+* **Rate limiting:** Prevent spam and maintain conversation quality with global or per-user throttling appropriate for your use case.
 
 ## Authentication
 
@@ -97,7 +97,7 @@ const currentTime = Math.round(Date.now() / 1000);
 const claims = {
     "iat": currentTime, /* current time in seconds */
     "exp": currentTime + 14400, /* time of expiration in seconds */
-    "x-ably-capability": "{\"[chat]foo\":[\"publish\", \"subscribe\"]}",
+    "x-ably-capability": "{\"foo\":[\"publish\", \"subscribe\"]}",
     "x-ably-clientId": "your-client-id",
 }
 
@@ -111,79 +111,23 @@ console.log('JWT is: ' + ablyJwt);
 ```
 </Code>
 
-How you authenticate is also key. To balance security and experience, you want short-lived tokens that can be easily revoked if a users is misbehaving or needs their permissions changed, but automatically expire after a period of time. This means that if a token is compromised, it will only be valid for a limited time. **In production apps, you should not use API keys for client-side authentication**. You can use them server-side, but as they are long-lived and require explicit revocation, exposure to untrusted users poses a continuing risk.
+How you authenticate is also key. To balance security and experience, you want short-lived tokens that can be easily revoked if a user is misbehaving or needs their permissions changed, but automatically expire after a period of time. This means that if a token is compromised, it will only be valid for a limited time. **In production apps, you should not use API keys for client-side authentication**. You can use them server-side, but as they are long-lived and require explicit revocation, exposure to untrusted users poses a continuing risk.
 
 With Ably Chat, authentication is best achieved using JSON Web Tokens (JWTs). These are tied to a particular clientID and come with a set of [capabilities](/docs/chat/setup#authentication) that control what a client can and cannot do - for example whether they can send messages, join a certain room or moderate. Ably's SDKs handle the timing and process of requesting a new token for you, refreshing it when it expires. All you need to do is provide a server-side endpoint that can generate the JWT for the client. This enables clients to use your existing authentication systems or user sessions to generate their Ably token.
 
-## Moderation: maintaining quality conversations
-
-Effective moderation ensures your task-oriented chats remain professional, safe, and productive. While task-oriented chats typically involve fewer participants than livestreams, maintaining conversation quality is crucial for successful task completion and keeping your users safe.
-
-Ably supports [moderating messages](/docs/chat/moderation) both before and after publication, making it easy to integrate with AI-powered or human moderation systems.
-
-* **After-publish moderation:** Messages appear instantly, then are removed if flagged as inappropriate. Best for most task-oriented scenarios where immediacy matters.
-* **Before-publish moderation:** Messages are held until approved. Use this for high-stakes tasks where every message must be vetted.
-
-### Key moderation considerations for task-oriented chat
-
-1. **Platform standards**
-   * What level of moderation is appropriate for your audience?
-   * How will you handle different types of content? For example:
-     * **Hate speech and harassment:** Detecting discriminatory language, threats, or targeted abuse.
-     * **Discrimination:** Detecting discriminatory language, threats, or targeted abuse.
-     * **Inappropriate content:** Flagging adult content, violence, or graphic material.
-     * **Toxicity:** Measuring overall message sentiment and hostility
-
-
-2. **Technical integration**
-   * **Latency impact:** AI moderation adds up to 100ms to message delivery.
-   * **Integration options:** Choose from pre-built integrations or connect your existing moderation systems via webhooks, serverless functions, or queues
-
-3. **Task-specific approaches**
-   * **Customer support:** Protect both customers and agents from abuse and harassment.
-   * **Gaming:** Prevent harassment while allowing enthusiastic expressions.
-   * **Marketplace:** Ensure rules are being followed such as detecting if outside-platform contact info is exchanged.
-
-### How Ably enhances task-oriented moderation
-
-Ably's flexible moderation system adapts to your task requirements:
-
-* **Per-room policies:** Different moderation rules for different task types or user roles
-* **Fallback handling:** Configure what happens when moderation services are unavailable
-* **Custom integration:** Connect your existing moderation infrastructure via webhooks, serverless functions, or message queues
-* **Role-based permissions:** Give moderators special capabilities to manage conversations
-
-<Code>
-```javascript
-import { ErrorCode } from '@ably/chat';
-
-const room = await chatClient.rooms.get('support-ticket-123');
-
-await room.messages.send({text: 'Can you help me with my order?'}).then((message) => {
-    console.log('Message sent:', message);
-}).catch((error) => {
-    if (error.code === ErrorCode.MessageRejectedByModeration) {
-        console.log('Message needs review:', error.message);
-        return;
-    }
-    console.error('Message failed to send:', error);
-});
-```
-</Code>
-
 ## Presence: Know who's available for your task
 
 Ably's [presence](/docs/chat/rooms/presence) feature shows you who's currently active in your task-oriented chat. This is especially valuable for scenarios where task completion depends on participant availability:
 
-* **Support tickets:** See when agents are online and available to help
-* **Deliveries:** Know if the delivery driver or customer is actively monitoring the chat
-* **Gaming sessions:** See which players are currently active in the game
-* **Collaborative work:** Know who's available for real-time discussion
+* **Support tickets:** See when agents are online and available to help.
+* **Deliveries:** Know if the delivery driver or customer is actively monitoring the chat.
+* **Gaming sessions:** See which players are currently active in the game.
+* **Collaborative work:** Know who's available for real-time discussion.
 
 Beyond just online/offline status, presence can include rich information:
 
-* **Current status:** "Available", "In a meeting", "Driving", "On break"
-* **Task context:** "Working on ticket #123", "In delivery zone A"
+* **Current status:** "Available", "In a meeting", "Driving", "On break".
+* **Task context:** "Working on ticket #123", "In delivery zone A".
 * **User info:** Use presence to show an avatar, display name, role, or other information about the user.
 
 This contextual presence information helps participants understand not just who's online, but who's ready and able to engage with the current task.
@@ -192,9 +136,9 @@ This contextual presence information helps participants understand not just who'
 
 Typing indicators are now a common feature in most chat applications. They show when someone is actively composing a message, helping to:
 
-* **Manage expectations:** Users know when a response is being prepared
-* **Reduce duplicate messages:** See that someone is already addressing the question
-* **Improve flow:** Better conversation pacing in support and collaborative scenarios
+* **Manage expectations:** Users know when a response is being prepared.
+* **Reduce duplicate messages:** See that someone is already addressing the question.
+* **Improve flow:** Better conversation pacing in support and collaborative scenarios.
 
 In Ably Chat typing indicators are a core feature with a simple API:
 
@@ -219,9 +163,9 @@ Message reactions are a great way to enhance engagement in a task-oriented chat
 
 **Message reactions** provide granular feedback on specific content:
 
-* **Validate information:** ✅ for confirmed details in deliveries or transactions
-* **Request clarification:** ❓ for questions about specific messages
-* **Show appreciation:** ⭐ for helpful responses in support
+* **Validate information:** ✅ for confirmed details in deliveries or transactions.
+* **Request clarification:** ❓ for questions about specific messages.
+* **Show appreciation:** ⭐ for helpful responses in support.
 
 Send a message reaction:
 <Code>
@@ -233,38 +177,22 @@ await room.messages.reactions.send(message.serial, {name: '✅'});
 
 Message reactions in Ably Chat come in three types: `unique`, `distinct` and `multiple`, to suit different use cases: from one reaction per message to multiple reactions per message with or without counts. See the [Message reactions](/docs/chat/rooms/message-reactions) documentation for more details.
 
-## Room reactions
-
-Room reactions are a great engagement feature for chats that accompany calls, meetings, collaborative tools, and games. They are a way to quickly express a sentiment to the entire room at a point in time without adding to chat history or being tired to a message.
-
-<Code>
-```javascript
-// Subscribe to room reactions
-room.reactions.subscribe((event) => {
-  console.log('Room reaction received:', event.reaction.name, "from", event.reaction.clientId);
-});
-
-// Send a room reaction
-await room.reactions.send({name: '👍'});
-```
-</Code>
-
 ## Message history: essential task context <a id="history"/>
 
 Message history is crucial for task-oriented chats, ensuring continuity and context even when participants join mid-task or return after interruptions.
 
 Ably stores [chat history](/docs/chat/rooms/history) for 30 days by default, with options to extend up to a year.
 
-* **Task continuity:** New participants can quickly understand the current state and previous decisions
-* **Context preservation:** Users returning to a task don't lose important information
-* **Audit trail:** Complete conversation records for compliance, training, or dispute resolution
+* **Task continuity:** New participants can quickly understand the current state and previous decisions.
+* **Context preservation:** Users returning to a task don't lose important information.
+* **Audit trail:** Complete conversation records for compliance, training, or dispute resolution.
 
 For task-oriented scenarios, history is almost always beneficial:
 
-* **Support tickets:** Agents can see the full conversation history to understand the issue
-* **Collaborative work:** Team members can catch up on decisions and progress
-* **Gaming sessions:** Players can review moves and strategy discussions
-* **Marketplace transactions:** Complete communication record for orders and deliveries
+* **Support tickets:** Agents can see the full conversation history to understand the issue, after handover from automated/AI support or another agent.
+* **Collaborative work:** Team members can catch up on decisions and progress.
+* **Gaming sessions:** Players can review moves and strategy discussions.
+* **Marketplace transactions:** Complete communication record for orders and deliveries.
 
 <Code>
 ```javascript
@@ -287,6 +215,90 @@ You can use our [React UI Kit](/docs/chat/react-ui-kit) to easily create a [full
 that handles subscrbing to messages, loading history, message updates and deletes, message reactions, and more.
 See the [React UI Kit](/docs/chat/react-ui-kit) for more details.
 
+## Enriching tasks with Ably's realtime services
+
+Ably's comprehensive platform enables you to combine chat with other realtime features to create rich, interactive task experiences.
+
+**Pub/Sub channels** add interactive elements:
+- **Live polls:** Quick feedback during collaborative decisions
+- **Status updates:** Real-time progress indicators for tasks
+- **Interactive ratings:** Instant feedback collection
+- **Live auctions:** Real-time bidding in marketplace scenarios
+
+These combined services transform basic chat into comprehensive task management platforms, where communication, coordination, and real-time updates work together seamlessly.
+
+## Moderation: maintaining quality conversations
+
+Effective moderation ensures your task-oriented chats remain professional, safe, and productive. While task-oriented chats typically involve fewer participants than livestreams, maintaining conversation quality is crucial for successful task completion and keeping your users safe.
+
+Ably supports [moderating messages](/docs/chat/moderation) both before and after publication, making it easy to integrate with AI-powered or human moderation systems.
+
+* **After-publish moderation:** Messages appear instantly, then are removed if flagged as inappropriate. Best for most task-oriented scenarios where immediacy matters.
+* **Before-publish moderation:** Messages are held until approved. Use this for high-stakes tasks where every message must be vetted.
+
+### Key moderation considerations for task-oriented chat
+
+1. **Platform standards**
+   * What level of moderation is appropriate for your audience?
+   * How will you handle different types of content? For example:
+     * **Hate speech and harassment:** Detecting discriminatory language, threats, or targeted abuse.
+     * **Discrimination:** Detecting discriminatory language, threats, or targeted abuse.
+     * **Inappropriate content:** Flagging adult content, violence, or graphic material.
+     * **Toxicity:** Measuring overall message sentiment and hostility
+
+
+2. **Technical integration**
+   * **Latency impact:** AI moderation adds up to 100ms to message delivery.
+   * **Integration options:** Choose from pre-built integrations or connect your existing moderation systems via webhooks, serverless functions, or queues
+
+3. **Task-specific approaches**
+   * **Customer support:** Protect both customers and agents from abuse and harassment.
+   * **Gaming:** Prevent harassment while allowing enthusiastic expressions.
+   * **Marketplace:** Ensure rules are being followed such as detecting if outside-platform contact info is exchanged.
+
+### How Ably enhances task-oriented moderation
+
+Ably's flexible moderation system adapts to your task requirements:
+
+* **Per-room policies:** Different moderation rules for different task types or user roles
+* **Fallback handling:** Configure what happens when moderation services are unavailable
+* **Custom integration:** Connect your existing moderation infrastructure via webhooks, serverless functions, or message queues
+* **Role-based permissions:** Give moderators special capabilities to manage conversations
+
+<Code>
+```javascript
+import { ErrorCode } from '@ably/chat';
+
+const room = await chatClient.rooms.get('support-ticket-123');
+
+room.messages.send({text: 'Can you help me with my order?'}).then((message) => {
+    console.log('Message sent:', message);
+}).catch((error) => {
+    if (error.code === ErrorCode.MessageRejectedByModeration) {
+        console.log('Message rejected by moderation:', error.message);
+        return;
+    }
+    console.error('Message failed to send:', error);
+});
+```
+</Code>
+
+## Room reactions
+
+Room reactions are a great engagement feature for chats that accompany calls, meetings, collaborative tools, and games. They are a way to quickly express a sentiment to the entire room at a point in time without adding to chat history or being tired to a message.
+
+<Code>
+```javascript
+// Subscribe to room reactions
+room.reactions.subscribe((event) => {
+  console.log('Room reaction received:', event.reaction.name, "from", event.reaction.clientId);
+});
+
+// Send a room reaction
+await room.reactions.send({name: '👍'});
+```
+</Code>
+
 ## Handling network disruption
 
 Network disruption happens - mobile internet loses signal or someone drives through a tunnel. All of Ably's SDKs are designed with this in mind, so that you don't have to handle complicated reconnection logic.
@@ -348,18 +360,6 @@ Ably Pub/Sub channels can be used for push notifications. See the [Push notifica
 
 You can also use a separate channel to control notifications, in which case you can tailor them to individual users. Read more about push notifications with Ably in the [Push notifications](/docs/push/publish) documentation.
 
-## Enriching tasks with Ably's realtime services
-
-Ably's comprehensive platform enables you to combine chat with other realtime features to create rich, interactive task experiences.
-
-**Pub/Sub channels** add interactive elements:
-- **Live polls:** Quick feedback during collaborative decisions
-- **Status updates:** Real-time progress indicators for tasks
-- **Interactive ratings:** Instant feedback collection
-- **Live auctions:** Real-time bidding in marketplace scenarios
-
-These combined services transform basic chat into comprehensive task management platforms, where communication, coordination, and real-time updates work together seamlessly.
-
 ## Production-ready checklist
 
 Before you go live with your task-oriented chat, review these key points:
