improvements based on revivew

vladvelici · vladvelici · commit 06b1e6ebb218 · 2025-11-18T09:46:40.000Z
diff --git a/src/pages/docs/guides/chat/build-task-oriented.mdx b/src/pages/docs/guides/chat/build-task-oriented.mdx
@@ -6,7 +6,7 @@ meta_keywords: "task-oriented chat, 1:1 chat, small group chat, realtime messagi
 
 Ably Chat is purpose-built for task-oriented chat experiences, from 1:1 conversations to small group interactions that enhance specific activities and workflows.
 
-> If you need to deliver seamless, contextual chat experiences that enhance tasks like support tickets, deliveries, gaming sessions, collaborative work, or transactional processes, without sacrificing performance, reliability, or costs, then Ably is the proven choice.
+If you need to deliver seamless, contextual chat experiences that enhance tasks like support tickets, deliveries, gaming sessions, collaborative work, or transactional processes, without sacrificing performance, reliability, or costs, then Ably is the proven choice.
 
 Building with Ably means that you no longer need to worry about managing websocket servers, handling failover, network disruptions, or keeping latency low. Ably handles all of this for you, leaving you free to focus on creating engaging task-oriented experiences.
 
@@ -46,26 +46,25 @@ For large-scale chat scenarios with many users per room, see our [building lives
 
 Each room includes all task participants: customers and agents in support, buyers and sellers in marketplaces, players in games, team members in projects. Participants can join and leave as the task evolves. Access to message history and other features can be granted to all or select participants via capabilities.
 
-## Message throughput and rate management
+Key considerations for task-oriented chat rooms:
+- When will the room be joined by participants and how will it be linked to the task (delivery, support ticket, game session and so on)?
+  - For something like support, you could create a ticket when the user opens the chat window in the UI and perhaps provides a name or category for the request. First create a support ticket, and also deliver a token for authentication and room name for the user to join.
+  - For games it can be one room per game session (such as a chess game), or for a MMORPG, each quest or location could be allocated a room.
+  - For deliveries, appointments, calls, there is usually a clear 1:1 mapping of task to room, and typically users join the room when they join the task.
+- Does the room have to be active for the whole duration of the task, or just sometimes?
+  - Only attaching to rooms when they are needed is more cost-effective and saves resources.
+  - For example, during a delivery, the chat room doesn't always have to be active. With a good strategy for push notifications to alert inactive users of new messages, they can attach for very short periods of time for each delivery.
+- Do you need any spam prevention measures applied before allowing users to join rooms?
+  - For example, in a support chat scenario, you could add a captcha or other measures before creating a new ticket and issuing a token that allows the user to join the room for that ticket.
+- Do you need long-term archiving of the chat history?
+  - Check out the guide for [exporting chat data](/docs/guides/chat/export-chat) for an overview of your options.
 
-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 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 global or per-user throttling appropriate for your use case.
 
 ## Authentication
 
 Authentication is a design decision. 
 
-In some cases, you'll want to tie participants to their identity in your application.
-In others, anyone can join and participate.
-Ably Chat supports both of these scenarios - you don't need to go through the hassle of setting up
-users in Ably and trying to keep them in sync with your application. Every client has a `clientId`.
-If you want to allow random users, just use a random string. If you want to tie it to your application,
-then use the ID of the user or some other well-known identifier. Just make sure you can tell them apart if
-you allow both at the same time, for example by using distinct prefixes.
+In some cases, you'll want to tie participants to their identity in your application. In others, anyone can join and participate. Ably Chat supports both of these scenarios - you don't need to go through the hassle of setting up users in Ably and trying to keep them in sync with your application. Every client has a `clientId`. If you want to allow random users, just use a random string. If you want to tie it to your application, then use the ID of the user or some other well-known identifier. Just make sure you can tell them apart if you allow both at the same time, for example by using distinct prefixes.
 
 <Code>
 ```javascript
@@ -131,6 +130,9 @@ const { unsubscribe } = room.presence.subscribe((event) => {
   console.log('Present members:', presentMembers);
 });
 
+// attach the room
+await room.attach();
+
 // join presence
 await room.presence.enter({ status: 'available' });
 
@@ -159,6 +161,9 @@ room.typing.subscribe((event) => {
   console.log('Currently typing:', event.currentlyTyping);
 });
 
+// attach the room
+await room.attach();
+
 // show a typing indicator (call on every keystroke, Ably Chat SDKs throttle this to a predefined interval)
 await room.typing.keystroke();
 
@@ -215,6 +220,9 @@ const subscription = room.messages.subscribe((messageEvent) => {
   // handle message event to update state and UI
 });
 
+// attach the room
+await room.attach();
+
 // Load recent history for context
 // This ensures you get a complete picture without missing messages
 let historyResponse = await subscription.historyBeforeSubscription({limit: 50});
@@ -239,7 +247,7 @@ See the [React UI Kit](/docs/chat/react-ui-kit) for more details.
 
 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:
+**Pub/Sub channels** enable you to build rich, interactive task experiences:
 - **Live polls:** Quick feedback during collaborative decisions.
 - **Status updates:** Real-time progress indicators for tasks.
 - **Interactive ratings:** Instant feedback collection.
@@ -254,7 +262,7 @@ Effective moderation ensures your task-oriented chats remain professional, 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 often matters. It can be used to detect abusive behaviour or inappropriate content after the fact, and can also be used to remove users if necessary.
+Best for most task-oriented scenarios, where immediacy often matters. It can be used to detect abusive behaviour or inappropriate content after the fact.
 * **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
@@ -279,7 +287,7 @@ Best for most task-oriented scenarios, where immediacy often matters. It can be
 
 Ably's flexible moderation system adapts to your task requirements:
 
-* **Per-room policies:** Different moderation rules for different task types or user roles.
+* **Per-room policies:** Different moderation rules for different task rooms.
 * **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.
@@ -306,7 +314,7 @@ room.messages.send({text: 'Can you help me with my order?'}).then((message) => {
 
 AI chatbots are revolutionizing the way we interact with digital platforms. Integrating AI functionality into your chat experience can provide automated contextual moderation, personalized interactions, automatically creating training material, and more.
 
-Ably's flexible [integration capabilities](/docs/platform/integrations) make it easy to connect your chat system with AI services. Through Ably's integrations, you can automatically route messages to:
+Ably's flexible [integration capabilities](/docs/chat/integrations) make it easy to connect your chat system with AI services. Through Ably's integrations, you can automatically route messages to:
 
 * Serverless functions (AWS Lambda, Azure Functions, and others).
 * Event streaming services including Kafka, SQS and Pulsar.
@@ -320,11 +328,7 @@ This enables powerful AI features like:
 * Chat summarization and key point extraction.
 * Automatically adding contextual information for your agents to help them be more effective.
 
-For example, you could set up an integration that sends all messages from each chat room to an AI service for sentiment analysis,
-which then automatically flags detected negative customer sentiments for review, to ensure they are handled appropriately, which
-could increase overall customer satisfaction.
-Or route messages to a language model to generate contextual responses to common questions, or to pull relevant information
-for your agent to increase their effectiveness in handling support queries.
+For example, you could set up an integration that sends all messages from each chat room to an AI service for sentiment analysis, which then automatically flags detected negative customer sentiments for review, to ensure they are handled appropriately, which could increase overall customer satisfaction. Or route messages to a language model to generate contextual responses to common questions, or to pull relevant information for your agent to increase their effectiveness in handling support queries.
 
 ## Room reactions
 
@@ -346,16 +350,9 @@ await room.reactions.send({name: '👍'});
 
 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.
 
-Every SDK instance keeps track of where it's at in the message stream. If the connection is lost, the library will 
-[automatically attempt to reconnect](/docs/platform/architecture/connection-recovery) to the servers and in
-doing so, resume its position in the stream. This enables the chat to continue as if the user never left.
-After extended periods of disconnection, the client can make use of [history](#history) to backfill missing messages.
+Every SDK instance keeps track of where it's at in the message stream. If the connection is lost, the library will  [automatically attempt to reconnect](/docs/platform/architecture/connection-recovery) to the servers and in doing so, resume its position in the stream. This enables the chat to continue as if the user never left. After extended periods of disconnection, the client can make use of [history](#history) to backfill missing messages.
 
-It's incredibly rare, but sometimes a client might lose connection to a particular data center. Ably operates in multiple data centers around
-the world with multiple fallback regions available. If a client can't reach the nearest data center, it will try the next one until the
-connection is re-established, ensuring minimal downtime and that network issues don't disrupt the experience that you are trying to build.
-Ably's [fault tolerance guide](/docs/platform/architecture/fault-tolerance) describes how we do this and that, even if an entire region
-goes down, it has little-to-no impact on the global service and your application.
+It's incredibly rare, but sometimes a client might lose connection to a particular data center. Ably operates in multiple data centers around the world with multiple fallback regions available. If a client can't reach the nearest data center, it will try the next one until the connection is re-established, ensuring minimal downtime and that network issues don't disrupt the experience that you are trying to build. Ably's [fault tolerance guide](/docs/platform/architecture/fault-tolerance) describes how we do this and shows that even if an entire region goes down, it has little-to-no impact on the global service and your application.
 
 ## Priced for task-oriented efficiency
 
@@ -400,10 +397,9 @@ Before you go live with your task-oriented chat, review these key points:
 
 * **Authentication strategy:** Ensure you're using token authentication for all client-side communication with appropriate JWT expiration times for your task duration.
 * **Permission model:** Apply the principle of least privilege - participants should only have access to their specific task rooms and relevant capabilities.
-* **Performance tuning:** Validate your message rate and batching configuration based on your typical task conversation patterns.
 * **Monitoring setup:** Monitor task room activity, message delivery success rates, and connection stability across your user base.
-* **Scale planning:** Confirm you are on the right Ably package for your expected task volume and user concurrency.
-* **Error handling:** Implement proper error handling for network disruptions and ensure graceful degradation when tasks are interrupted.
+* **Scale planning:** Confirm you are on the right Ably package for your expected volume.
+* **Error handling:** Implement proper error handling for network disruptions and ensure graceful degradation when network connections are interrupted.
 * **Data retention:** Verify your message history retention policy aligns with your task lifecycle and any compliance requirements.
 * **Integration testing:** Test all third-party integrations (AI services, moderation, external APIs) under realistic task scenarios.
 
@@ -412,7 +408,7 @@ Before you go live with your task-oriented chat, review these key points:
 * **Explore Ably Chat:** Dive into the [Ably Chat documentation](/docs/chat) for comprehensive API details and advanced features.
 * **Try the examples:** Play around with [task-oriented chat examples](/examples?product=chat) to see real implementations.
 * **Get started quickly:** Follow the [JavaScript/TypeScript](/docs/chat/getting-started/javascript) or [React](/docs/chat/getting-started/react) getting started guides.
-* **Add intelligence:** Learn how to integrate [AI assistance](/docs/platform/integrations) for smarter task experiences.
+* **Add intelligence:** Learn how to integrate [AI assistance](/docs/chat/integrations) for smarter task experiences.
 * **Secure your chats:** Understand [token authentication](/docs/auth/token#jwt) for production-ready security.
 * **Moderate effectively:** Implement [chat moderation](/docs/chat/moderation) tailored to your task scenarios.
 * **Scale with confidence:** Explore [server-side batching](/docs/messages/batch#server-side) for optimal performance.
