diff --git a/src/components/Layout/mdx/Admonition.tsx b/src/components/Layout/mdx/Admonition.tsx index 5848d66904..e13b105e13 100644 --- a/src/components/Layout/mdx/Admonition.tsx +++ b/src/components/Layout/mdx/Admonition.tsx @@ -2,7 +2,7 @@ import React from 'react'; import cn from '@ably/ui/core/utils/cn'; import Aside from '../../blocks/dividers/Aside'; -const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental', 'public-preview']; +const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental', 'see-evidence']; type AdmonitionVariant = 'neutral' | 'note' | 'further-reading' | 'important' | 'warning'; @@ -51,7 +51,7 @@ const Admonition: React.FC = ({ 'data-type': dataType = 'note', return ; } - const { borderColor, backgroundColor, title } = admonitionConfig[dataType]; + const { borderColor, backgroundColor, title } = admonitionConfig[dataType] || admonitionConfig.note; return ( + Use the [`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status)[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus)[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/status.html) property to check which status a connection is currently in: diff --git a/src/pages/docs/chat/index.mdx b/src/pages/docs/chat/index.mdx index c4b96234fa..3581f81af3 100644 --- a/src/pages/docs/chat/index.mdx +++ b/src/pages/docs/chat/index.mdx @@ -17,6 +17,8 @@ The Chat SDK contains a set of purpose-built APIs that abstract away the complex * [Getting started: Chat in Kotlin (JVM)](/docs/chat/getting-started/jvm) * [Getting started: Chat in Swift](/docs/chat/getting-started/swift) + + ## Chat features Ably Chat provides the following key features: diff --git a/src/pages/docs/chat/integrations.mdx b/src/pages/docs/chat/integrations.mdx index 404f47e97a..91fa5ed560 100644 --- a/src/pages/docs/chat/integrations.mdx +++ b/src/pages/docs/chat/integrations.mdx @@ -36,6 +36,8 @@ Be aware that message actions are numeric values over the realtime channels, Pub If possible, use an Ably Pub/Sub SDK with `fromEncoded()` or `fromEncodedArray()` to decode the message. This will ensure that the message is decoded correctly and all the fields are present, as well as convert things like numerical action values to their string representations. Details on how to do this are available in the [platform integrations documentation](/docs/platform/integrations/webhooks). Then you can apply the mapping from the table above to get a Chat message form the Pub/Sub message. + + ### Is this message new, updated, or deleted? To determine if a message is new, updated, or deleted, you can use the `action` field. diff --git a/src/pages/docs/chat/react-ui-kit/index.mdx b/src/pages/docs/chat/react-ui-kit/index.mdx index 9462910ced..91bcf073a5 100644 --- a/src/pages/docs/chat/react-ui-kit/index.mdx +++ b/src/pages/docs/chat/react-ui-kit/index.mdx @@ -16,9 +16,13 @@ Some of the benefits include: * **Tried and tested** – rely on components that are already fully covered by a suite of tests. * **Chat-centric design** – layouts, interactions, and accessibility are built with chat workflows in mind. - ![Ably Chat React App](../../../../images/examples/chat-ui-app.png) + + + ## Components and Providers The React UI Kit is organized into two main categories: diff --git a/src/pages/docs/chat/rooms/history.mdx b/src/pages/docs/chat/rooms/history.mdx index cef507e3d9..f1acb7b57a 100644 --- a/src/pages/docs/chat/rooms/history.mdx +++ b/src/pages/docs/chat/rooms/history.mdx @@ -4,9 +4,6 @@ meta_description: "Retrieve previously sent messages from history." --- The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 30 days by default. You can extend this up to 365 days by [contacting us](https://ably.com/support). - -## Retrieve previously sent messages - Use the [`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html) method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages. @@ -82,6 +79,10 @@ The following optional parameters can be passed when retrieving previously sent | orderBy | The order in which to retrieve messages from; either `oldestFirst` or `newestFirst`. | | limit | Maximum number of messages to be retrieved per page, up to 1,000. | + + ## Retrieve messages sent prior to subscribing Users can also retrieve historical messages that were sent to a room before the point that they registered a listener by [subscribing](/docs/chat/rooms/messages#subscribe). The order of messages returned is from most recent, to oldest. This is useful for providing conversational context when a user first joins a room, or when they subsequently rejoin it later on. It also ensures that the message history they see is continuous, without any overlap of messages being returned between their subscription and their history call. diff --git a/src/pages/docs/chat/rooms/index.mdx b/src/pages/docs/chat/rooms/index.mdx index a287773942..7c82b77a50 100644 --- a/src/pages/docs/chat/rooms/index.mdx +++ b/src/pages/docs/chat/rooms/index.mdx @@ -162,6 +162,10 @@ By default the `ChatRoomProvider` will automatically call [`release()`](https:// To start receiving messages and events from a room, you need to attach to it. Attaching to a room tells Ably to start streaming messages to the client, and ensures that events are not missed in case of temporary network interruptions. + + Once an instance of a room has been created using `rooms.get()`, clients attach to it to start receiving messages and events from the room. diff --git a/src/pages/docs/chat/rooms/media.mdx b/src/pages/docs/chat/rooms/media.mdx index a4f72b2e3c..0fdecbb31a 100644 --- a/src/pages/docs/chat/rooms/media.mdx +++ b/src/pages/docs/chat/rooms/media.mdx @@ -8,6 +8,10 @@ Share media such as images, videos and files with users in a chat room. Upload the media to your own storage service, such as AWS S3, and then use the `metadata` field to reference the location of the media when a user [sends a message](/docs/chat/rooms/messages#send). On the receiving end, display the media to [subscribers](/docs/chat/rooms/messages#subscribe) that received the message. + + ## Access control Ensure that you add a layer of authentication server-side if the media shouldn't be publicly available. diff --git a/src/pages/docs/chat/rooms/message-reactions.mdx b/src/pages/docs/chat/rooms/message-reactions.mdx index 961e129af3..9b53689aa0 100644 --- a/src/pages/docs/chat/rooms/message-reactions.mdx +++ b/src/pages/docs/chat/rooms/message-reactions.mdx @@ -5,6 +5,10 @@ meta_description: "React to chat messages" Send, remove and display message reactions in a chat room. Users can react to messages, typically with emojis but can be any string, and others can see the reactions to the message. Message reactions can be sent and removed and a summary of the reactions is persisted with the message. + + The reaction `name` represents the reaction itself, for example an emoji. Reactions are aggregated by `name` and the aggregation method including how many reactions a user can place for a message is controlled by the reaction `type`. The `count` is an optional parameter that can be set when sending a reaction of type `Multiple`. The reaction `name` can be any string. Summaries are aggregated based on unique `name` values. UTF-8 emojis are a common use case, but any string can be used as long as they are consistent across all front-ends of your app. Examples of common reaction names are `👍`, `❤️`, `:like:`, `like`, `+1`, and so on. How those are presented to the user is entirely up to the app. diff --git a/src/pages/docs/chat/rooms/messages.mdx b/src/pages/docs/chat/rooms/messages.mdx index 6018c86335..34a78d6728 100644 --- a/src/pages/docs/chat/rooms/messages.mdx +++ b/src/pages/docs/chat/rooms/messages.mdx @@ -95,7 +95,13 @@ The following are the properties of a message: | | `description`: Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | String or undefined | | | `metadata`: Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | Object or undefined | -See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application. +Each message contains a `serial` property that provides deterministic global ordering. See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application. + + + + ### Unsubscribe from messages diff --git a/src/pages/docs/chat/rooms/presence.mdx b/src/pages/docs/chat/rooms/presence.mdx index 5af6cdece7..8b7d747971 100644 --- a/src/pages/docs/chat/rooms/presence.mdx +++ b/src/pages/docs/chat/rooms/presence.mdx @@ -122,6 +122,10 @@ unsubscribe() Users can enter and leave the presence set of a room to indicate when they are online or offline. They can also set user data when entering and leaving the set, such as their current status. Presence is also linked to a user's [connection status](/docs/chat/connect). For example, if a user goes offline then a leave event will be emitted for them. + + diff --git a/src/pages/docs/chat/rooms/reactions.mdx b/src/pages/docs/chat/rooms/reactions.mdx index e494ebc5e6..5ac731c33a 100644 --- a/src/pages/docs/chat/rooms/reactions.mdx +++ b/src/pages/docs/chat/rooms/reactions.mdx @@ -7,6 +7,10 @@ Users can send reactions to the entire chat room to show their sentiment as to w Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time. + + ## Subscribe to room reactions diff --git a/src/pages/docs/chat/rooms/replies.mdx b/src/pages/docs/chat/rooms/replies.mdx index ae5b54ab3f..121831bbff 100644 --- a/src/pages/docs/chat/rooms/replies.mdx +++ b/src/pages/docs/chat/rooms/replies.mdx @@ -8,6 +8,10 @@ Reply to messages that have been previously sent in the chat room. Message replies are implemented using the `metadata` field when you [send a message](/docs/chat/rooms/messages#send). + + ## Send a reply Use the [`metadata`](/docs/chat/rooms/messages#structure) field of a message to store the reply when you [send a message](/docs/chat/rooms/messages#send). diff --git a/src/pages/docs/chat/rooms/typing.mdx b/src/pages/docs/chat/rooms/typing.mdx index ec6b07adfd..469261d68e 100644 --- a/src/pages/docs/chat/rooms/typing.mdx +++ b/src/pages/docs/chat/rooms/typing.mdx @@ -89,6 +89,10 @@ The following are the properties of a typing event: You can use the size of the `currentlyTyping` set to decide whether to display individual user names, or that multiple people are typing in your user interface. + + ### Unsubscribe from typing events diff --git a/src/pages/docs/chat/setup.mdx b/src/pages/docs/chat/setup.mdx index fdb0aafdaf..75a05a6349 100644 --- a/src/pages/docs/chat/setup.mdx +++ b/src/pages/docs/chat/setup.mdx @@ -41,6 +41,10 @@ When setting the capabilities for Chat, you can apply them to specific chat room For more guidance, see the [capabilities documentation](/docs/auth/capabilities). + + ## Install The Chat SDK is built on top of the Ably Pub/Sub SDK and uses that to establish a connection with Ably. diff --git a/src/pages/docs/guides/chat/build-livestream.mdx b/src/pages/docs/guides/chat/build-livestream.mdx index 72300d6d59..faa45060cc 100644 --- a/src/pages/docs/guides/chat/build-livestream.mdx +++ b/src/pages/docs/guides/chat/build-livestream.mdx @@ -14,6 +14,8 @@ This guide explains the architectural decisions, technical challenges, and uniqu Ably is trusted by organizations delivering chat to millions of users in realtime. Its platform is engineered around the four pillars of dependability: + + * **[Performance](/docs/platform/architecture/performance):** Ultra-low latency messaging, even at global scale. * **[Integrity](/docs/platform/architecture/message-ordering):** Guaranteed message ordering and delivery, with no duplicates or data loss. * **[Reliability](/docs/platform/architecture/fault-tolerance):** 99.999% uptime SLA, with automatic failover and seamless re-connection. @@ -58,6 +60,8 @@ Livestream chat is defined by high message rates and unpredictable spikes. Ably * **Server-side batching:** Reduce costs and network overhead by grouping messages before delivery. As shown in the [example](#server-side-batching), [batching messages](#server-side-batching) reduces the number of outbound messages such that it increases linearly with the number of users in the chatroom. * **Rate limiting:** Control the flow of messages per user to maintain readability and prevent spam. Choose between per-connection rate limits or global throttling. + + Decisions that you need to make around throughput and rates: * What is the maximum message rate you want users to experience on average?