section changes

Vlad Velici · Vlad Velici · commit 4f3e02dd7203 · 2025-12-30T13:09:31.000Z
diff --git a/src/pages/docs/guides/chat/support-chat.mdx b/src/pages/docs/guides/chat/support-chat.mdx
@@ -12,7 +12,7 @@ This guide covers both sides of a support chat system with Ably, with particular
 ![Support chat example mockup](../../../../images/content/chat/support-chat.png)
 </div>
 
-## Why Ably for support chat?
+## Why Ably for support chat? <a id="why-ably"/>
 
 Ably is trusted by organizations delivering chat to millions of users in realtime. The Ably platform is engineered around the four pillars of dependability:
 
@@ -23,13 +23,23 @@ Ably is trusted by organizations delivering chat to millions of users in realtim
 
 ![Ably Architecture Overview Diagram](../../../../images/content/diagrams/architecture-overview.png)
 
+### Scaling support chat <a id="scaling-support-chat"/>
+
 Support chat has unique scaling requirements. You might have thousands of concurrent tickets, each with its own chat room, while each agent handles multiple tickets simultaneously. Ably's architecture scales automatically to handle this load without provisioning or re-engineering as you grow.
 
 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 routinely handles 600 billion messages every month globally, across 2 billion devices with a global median [latency](/docs/platform/architecture/latency#message-delivery-latency) of 37ms. Ably also handles all of the edge-cases around delivery, failover and scaling.
 
 Ably uses [consistent hashing](/docs/platform/architecture/platform-scalability) to evenly distribute the management of chat rooms across instances, enabling the number of rooms to grow without limit and without causing load spikes. Whether you're managing 100 support chat rooms or 100,000 simultaneous chat rooms, the architecture remains the same.
 
-## Architecture overview
+### Seamless network disruption handling <a id="seamless-network-disruption-handling"/>
+
+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.
+
+If the connection is lost, the Ably SDK libraries [automatically attempt to reconnect](/docs/platform/architecture/connection-recovery) to the servers and resume the position in the message stream. This enables the chat to continue as if the user never left. After extended periods of disconnection, you receive a [discontinuity event](/docs/connect/states#discontinuity), after which the client can use [history](#history) to backfill missing messages.
+
+It's 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 tries the next one until the connection is re-established, ensuring minimal downtime. Ably's [fault tolerance guide](/docs/platform/architecture/fault-tolerance) describes how this works and shows that even if an entire region goes down, it has little-to-no impact on the global service and your application.
+
+## Architecture overview <a id="architecture-overview"/>
 
 A support chat system has a straightforward core architecture: **one room per ticket**. The key decisions involve the flow of support tickets through the system and the customer and agent experience:
 
@@ -63,7 +73,15 @@ Use both Ably Pub/Sub and the Ably Chat SDK to build a support chat system. The
   - Create a dedicated chat room for agents across the whole system, team, or department.
   - Use presence in this chat room to share agent availability and workload with the rest of the team.
 
-## Customer-facing chat widget
+### Build quickly: Chat React UI Kit <a id="react-ui-kit"/>
+
+If you use React, the [Chat React UI Kit](/docs/chat/react-ui-kit) provides ready-made components for building chat interfaces. It is a great fit for building both the customer-facing chat widget and the agent dashboard, or just one of them.
+
+Drop in the [App](/docs/chat/react-ui-kit/components#app) component to see a working chat UI within minutes, or use individual components like [ChatWindow](/docs/chat/react-ui-kit/components#chat-window), [ChatMessageList](/docs/chat/react-ui-kit/components#chat-message-list), [MessageInput](/docs/chat/react-ui-kit/components#message-input), and [ParticipantList](/docs/chat/react-ui-kit/components#participant-list) to build custom interfaces.
+
+Components handle message display with history loading, editing and deletion, reactions, typing indicators, and presence. [Providers](/docs/chat/react-ui-kit/providers) manage themes, avatars, and chat settings. See the [getting started guide](/docs/chat/getting-started/react-ui-kit) for setup details.
+
+## Customer-facing chat widget <a id="customer-widget"/>
 
 Building a polished chat widget requires handling message delivery guarantees, reconnection logic, presence synchronization, and typing indicators. Ably Chat abstracts away these challenges, so you can focus on the user experience rather than the infrastructure. Customers interact with one room at a time, typically through an embedded widget.
 
@@ -81,6 +99,26 @@ You can add a pre-chat flow to collect information before connecting to the room
 
 After the chat has started, you can provide a rich chat experience with the Ably Chat SDK. It requires minimal setup and provides a comprehensive set of features out of the box. See the [embedded chat guide](/docs/guides/chat/build-embedded-chat) for implementation patterns.
 
+### Authentication <a id="customer-authentication"/>
+
+Name each support chat room uniquely by using the user ID as a prefix followed by the ticket ID. For example, `support:user-343:ticket-992`.
+
+This approach allows you to grant permission for users to access all their own support tickets, even before they are created, making authentication and access control straightforward. Grant each customer a JWT with access to their own support tickets by using a capability resource specifier such as `support:user-343:*`.
+
+Example capabilities for a customer:
+
+<Code>
+```json
+{
+    "support:user-343:*": [
+        "publish",
+        "subscribe",
+        "presence"
+    ]
+}
+```
+</Code>
+
 ### Typing indicators <a id="typing-indicators"/>
 
 [Typing indicators](/docs/chat/rooms/typing) are a common feature in most chat applications. They show when someone is actively composing a message, helping to:
@@ -168,7 +206,7 @@ while (true) {
 
 ### Presence: see when agents and customers are online <a id="presence"/>
 
-[Presence](/docs/chat/rooms/presence) shows who is currently active in the room, enabling you to bring more live context to your application. You can display in realtime when an agent joins the room, along with their status, such as "Available" or "Gathering context, will join shortly".
+[Presence](/docs/chat/rooms/presence) shows who is currently active in the room, enabling you to bring more live context to your application. You can display in realtime when an agent joins the room, along with their status, such as "Available" or "Gathering context, will join shortly". You can also display to the agent if the customer is still active, and attach information about the customer.
 
 Beyond online or offline status, presence can include rich information about the user, such as their name, avatar, role, and other details.
 
@@ -196,26 +234,6 @@ await room.presence.leave();
 
 Presence can also be used to share data about the current user to the support agent, such as what page they are currently on, to assist them better with their query.
 
-### Authentication <a id="customer-authentication"/>
-
-Name each support chat room uniquely by using the user ID as a prefix followed by the ticket ID. For example, `support:user-343:ticket-992`.
-
-This approach allows you to grant permission for users to access all their own support tickets, even before they are created, making authentication and access control straightforward. Grant each customer a JWT with access to their own support tickets by using a capability resource specifier such as `support:user-343:*`.
-
-Example capabilities for a customer:
-
-```javascript
-{
-    "support:user-343:*": ["publish", "subscribe", "presence"],
-}
-```
-
-### Build quickly: React UI Kit <a id="react-ui-kit"/>
-
-The [React UI Kit](/docs/chat/react-ui-kit) provides ready-made components for building chat interfaces. Drop in the [App](/docs/chat/react-ui-kit/components#app) component to see a working chat UI within minutes, or use individual components like [ChatWindow](/docs/chat/react-ui-kit/components#chat-window), [ChatMessageList](/docs/chat/react-ui-kit/components#chat-message-list), [MessageInput](/docs/chat/react-ui-kit/components#message-input), and [ParticipantList](/docs/chat/react-ui-kit/components#participant-list) to build custom interfaces.
-
-Components handle message display with history loading, editing and deletion, reactions, typing indicators, and presence. [Providers](/docs/chat/react-ui-kit/providers) manage themes, avatars, and chat settings. See the [getting started guide](/docs/chat/getting-started/react-ui-kit) for setup details.
-
 ## Assigning tickets to agents
 
 A key part of a support system is assigning tickets to agents. You can do this on your server either in advance as tickets are created, by tracking agent workload, or by broadcasting all tickets to all agents in a shared queue.
@@ -326,11 +344,11 @@ Each attachment maintains a subscription with new messages, typing indicators, a
 
 ### Agent presence and availability <a id="agent-presence"/>
 
-Agents need to signal their availability across the entire support application, not just individual rooms.
+Agents need to signal their status and availability with other agents, for the whole application or their team. This is separate to the presence information displayed to customers. We call this app-wide presence, even though it can be scoped to a team or department.
 
-**App-wide presence** uses a dedicated channel (for example, `support:agents`) where agents enter presence when they sign in and update their status (available, busy, away) and current workload. Other agents and routing systems can see who is online and available.
+**App-wide presence** uses a dedicated channel (for example, `support:agents`, or `support:agents-sales`) where agents enter presence when they sign in and update their status (available, busy, away) and current workload. Other agents and routing systems can see who is online and available.
 
-**Room-level presence** shows the customer that their agent is present. When an agent opens a ticket room, they enter presence with their role and name, providing reassurance that help has arrived. Agents can also see if customers are still active.
+This is different to the **room-level presence** which connects the agent to individual chat rooms and customers. When an agent opens a ticket room, they enter presence with their role and name, providing reassurance that help has arrived. Agents can also see if customers are still active.
 
 ### Push notifications for agents <a id="push-notifications"/>
 
@@ -340,7 +358,7 @@ Agents aren't always watching the dashboard. You can use Ably to send [push noti
 - Mentions from other agents.
 - Customer activity on tickets assigned to them.
 
-## AI integrations
+## Adding AI to the loop
 
 AI chatbots are revolutionizing the way we interact with digital platforms. Integrating an AI agent (such as an LLM) into your support chat flow can reduce the workload for your agents and provide faster responses to customers. AI can also help support agents be more effective by providing contextual information and suggested responses. Additionally, AI can help you analyze past chats for training, monitoring, and building knowledge bases.
 
@@ -375,13 +393,6 @@ AI can assist agents in several ways:
 
 Implement this client-side in the agent dashboard, where each message from the chat is passed to your backend or AI service as it arrives. The responses can be rendered in a sidebar where the agent can review, copy and paste, or read the information to help answer the customer's questions faster.
 
-## 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.
-
-If the connection is lost, the Ably SDK libraries [automatically attempt to reconnect](/docs/platform/architecture/connection-recovery) to the servers and resume the position in the message stream. This enables the chat to continue as if the user never left. After extended periods of disconnection, you receive a [discontinuity event](/docs/connect/states#discontinuity), after which the client can use [history](#history) to backfill missing messages.
-
-It's 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 tries the next one until the connection is re-established, ensuring minimal downtime. Ably's [fault tolerance guide](/docs/platform/architecture/fault-tolerance) describes how this works and shows that even if an entire region goes down, it has little-to-no impact on the global service and your application.
 
 ## Ticket resolution and archiving <a id="ticket-resolution"/>
 
@@ -406,11 +417,14 @@ For more sophisticated export patterns such as continuous ingestion and streamin
 
 Before you go live with your support chat, review these key points:
 
-* **Authentication strategy:** Ensure you're using token authentication for all client-side communication with appropriate capabilities for each participant.
+* **Authentication strategy:** Ensure you're using token authentication for all client-side communication with appropriate capabilities for each participant. Make sure capabilities are configured correctly for each type of participant (agents and customers).
 * **Scale planning:** Confirm you are on the right Ably package for your expected volume of concurrent tickets.
 * **Error handling:** Implement proper error handling for network disruptions and ensure graceful degradation.
 * **Data retention:** Verify your message history retention policy aligns with your compliance requirements.
 * **Export strategy:** Set up a process for archiving closed tickets to your long-term storage.
+* **AI integrations:** Ensure AI integrations are configured correctly and are ready to handle the expected volume of messages.
+* **Push notifications:** Test push notifications in all scenarios and all supported platforms.
+
 
 ## Next steps
 
