From 0fd50d38ffb698f0923d8901dbe76a94ebd2ac04 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 16 Nov 2026 17:56:58 +0530 Subject: [PATCH 01/13] docs(react-native): offline support for the React Native UI Kit Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WEaVigCRBjkftm78T25MQA --- docs.json | 1 + ui-kit/react-native/core-features.mdx | 12 + ui-kit/react-native/llms-react-native-v5.mdx | 1 + ui-kit/react-native/offline-support.mdx | 519 +++++++++++++++++++ 4 files changed, 533 insertions(+) create mode 100644 ui-kit/react-native/offline-support.mdx diff --git a/docs.json b/docs.json index 40eea0779..0a5e8a003 100644 --- a/docs.json +++ b/docs.json @@ -1083,6 +1083,7 @@ "group": "Chat", "pages": [ "ui-kit/react-native/core-features", + "ui-kit/react-native/offline-support", "ui-kit/react-native/extensions", "ui-kit/react-native/ai-features" ] diff --git a/ui-kit/react-native/core-features.mdx b/ui-kit/react-native/core-features.mdx index d227e757c..70f5130d7 100644 --- a/ui-kit/react-native/core-features.mdx +++ b/ui-kit/react-native/core-features.mdx @@ -291,6 +291,18 @@ CometChat facilitates Group Chats, allowing users to have conversations with mul For a comprehensive understanding and guide on implementing and using the Groups feature in CometChat, refer to the detailed guide on [Groups](/ui-kit/react-native/groups). +## Offline Support + +Offline Support keeps chat usable without a network. Chats and messages the user has opened appear at once from the device, messages sent offline are queued and go out when the connection returns, and failed messages offer Retry and Delete. It is **off by default**: turn it on with the `offline` setting in `UIKitSettings` (UI Kit 5.6.0 and Chat SDK 4.2.0 or later). + +| Components | Functionality | +| --- | --- | +| [Conversations](/ui-kit/react-native/conversations), [Users](/ui-kit/react-native/users), [Groups](/ui-kit/react-native/groups), [Group Members](/ui-kit/react-native/group-members) | Show saved rows first and merge the server's page in place; offline with nothing saved, show **Connect to load …**. | +| [Message List](/ui-kit/react-native/message-list) | Shows saved history, marks queued and failed messages, and offers **Connect to load more** at a blocked edge. | +| [Message Composer](/ui-kit/react-native/message-composer) | Queues messages sent offline and keeps staged attachments across restarts. | + +See [Offline Support](/ui-kit/react-native/offline-support) for setup, native dependencies and the full behavior. + --- ## Next Steps diff --git a/ui-kit/react-native/llms-react-native-v5.mdx b/ui-kit/react-native/llms-react-native-v5.mdx index c6a5b7835..b5f39f0de 100644 --- a/ui-kit/react-native/llms-react-native-v5.mdx +++ b/ui-kit/react-native/llms-react-native-v5.mdx @@ -81,6 +81,7 @@ components, theming tokens, or feature enablement. ## Core & configuration - [Core Features](/ui-kit/react-native/core-features) +- [Offline Support](/ui-kit/react-native/offline-support) - [Methods](/ui-kit/react-native/methods) - [Events](/ui-kit/react-native/events) - [Sound Manager](/ui-kit/react-native/sound-manager) diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx new file mode 100644 index 000000000..db7d18dc2 --- /dev/null +++ b/ui-kit/react-native/offline-support.mdx @@ -0,0 +1,519 @@ +--- +title: "Offline Support" +sidebarTitle: "Offline Support" +description: "Show saved chats and messages without a connection, queue messages while offline, and send them on reconnect with the CometChat React Native UI Kit." +--- + + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-uikit-react-native` 5.6.0 or later, with `@cometchat/chat-sdk-react-native` 4.2.0 or later | +| Default | **Off.** Without the `offline` setting the UI Kit behaves as before | +| Enable | `CometChatUIKit.init({ ...uiKitSettings, offline: { enabled: true } })` — `offline` takes `true`, an options object, or a `CometChat.OfflineConfig` | +| `initFromSettings` | `CometChatUIKit.initFromSettings(settings, offline?)` — or put the value under `chatSDK.offline` in the settings | +| Native peers | `@op-engineering/op-sqlite` 9.0.0+ (required for offline), `react-native-fs` (optional; media), `react-native-keychain` (encryption only). Rebuild the native app after installing | +| Expo | Development build or `expo prebuild` only; Expo Go is not supported | +| Runtime check | `CometChat.isOfflineEnabled()` from `@cometchat/chat-sdk-react-native` | +| Props | `hideOfflineNotices` on `CometChatMessageList` and `CometChatConversations` (default `false`) | +| Styles | `messageListStyles.offlineStyles` in the theme: `failedRowStyle`, `failedIconStyle`, `retryTextStyle`, `notSentYetTextStyle`, `mediaPlaceholderStyle`, `footerStyle`, `noticeStyle` | +| Events | `OfflineMessageEvents.ccMessageSendStateChanged`, `OfflineMessageEvents.ccOfflineCacheReset` on `CometChatUIEventHandler.addMessageListener` | +| Types | `UIKitOfflineSettings`, `MessageSendState`, `MessageSendStateChangedEvent`, `OfflineCacheResetEvent` | +| Options reference | [React Native SDK: Offline Configuration & API Reference](/sdk/react-native/offline-reference) | + + + +With offline support turned on, the UI Kit keeps working when the network drops. Chats, messages and lists the user has already opened appear at once from the device, messages sent while offline are queued and go out when the connection returns, and the lists update in place when the server answers. + +The UI Kit builds on the [offline support in the React Native Chat SDK](/sdk/react-native/offline-overview). You turn it on once in the UI Kit settings; the components handle the rest. + + +Offline support is available from React Native UI Kit **5.6.0** with React Native Chat SDK **4.2.0** or later. It is **off by default**. + + +## Overview + +**Works offline** + +- Conversations, users, groups, group members, messages and threads the user has opened before appear at once from the device, then the server's page merges into them in place when it arrives. +- New messages (text, media and custom messages) are queued on the device, survive an app restart, and are sent automatically when the connection returns. +- A message that could not be sent shows **Not sent. Tap to retry**, with Retry and Delete. +- Images, videos, audio and files the device has already saved are shown from the device. +- Attachments staged in the composer survive leaving the chat and an app restart. +- When the connection returns, everything that changed while the device was away (new messages, and edits, deletes and reactions made by others) syncs into the lists. + +**Needs a connection** + +- The first load of a chat, list or page that was never opened on this device. +- Keyword search with no saved match, message information, call logs, calls and AI streamed replies. +- Editing, deleting and reacting to messages that are already sent. These are not queued offline. See [Edits, deletes and reactions](#edits-deletes-and-reactions). +- Media the device never downloaded. + +## Requirements + +| Requirement | Version | +| --- | --- | +| `@cometchat/chat-uikit-react-native` | 5.6.0 or later | +| `@cometchat/chat-sdk-react-native` | 4.2.0 or later | + +The UI Kit's peer dependency on the Chat SDK stays `*`. The kit checks at runtime whether the installed SDK supports offline, so an app on an older SDK keeps working online only, and the `offline` setting is ignored. + +### Install the native dependencies + +Offline support stores data in a local database, which the Chat SDK opens through native modules that you install in your app: + +| Package | Needed for | +| --- | --- | +| `@op-engineering/op-sqlite` (9.0.0 or later) | The local database. **Required for offline support.** Without it the SDK runs online only. | +| `react-native-fs` | Optional. Caching media on the device, and playable copies of cached audio and video in the UI Kit. Without it, the UI Kit uses the cached file as it is. | +| `react-native-keychain` | Only for [encrypting the cache](/sdk/react-native/offline-encryption). | + +```bash +npm install @op-engineering/op-sqlite react-native-fs +``` + +The SDK documents these packages in [Enable Offline Support](/sdk/react-native/offline-enable). Pick an `op-sqlite` release that supports your React Native version. + +### Rebuild the native app + +These packages are native modules, and the UI Kit itself also ships native code (5.6.0 adds native file-copy code so Download and Share can use a saved file). After you install or upgrade, rebuild the native app; a JavaScript reload is not enough. + + + +```bash +cd ios && pod install && cd .. +npx react-native run-ios +``` + + +```bash +npx react-native run-android +``` + + + +### Android: compileSdk and media3 + +The UI Kit's Android module plays voice notes with `androidx.media3` **1.8.0**, which needs **`compileSdkVersion` 35** or later. If your app must stay on `compileSdkVersion` 34, pin an older media3 release with the `RNVideo_media3Version` key (the same key `react-native-video` reads) in the `ext` block of your project-level `android/build.gradle`: + +```groovy android/build.gradle +buildscript { + ext { + // keep your other ext values + RNVideo_media3Version = "1.4.1" + } +} +``` + +### Expo + +The UI Kit and the offline database are native modules, so offline support runs in a [development build](https://docs.expo.dev/develop/development-builds/introduction/) or after `expo prebuild`, not in Expo Go. See [Expo Integration](/ui-kit/react-native/expo-integration). + +## Enable Offline Support + +Add the `offline` field to the `UIKitSettings` you pass to `CometChatUIKit.init()`. The UI Kit hands it to the Chat SDK's `AppSettingsBuilder.setOfflineConfig(...)` for you. + + + +```tsx +import { CometChatUIKit, UIKitSettings } from "@cometchat/chat-uikit-react-native"; +import { CometChat } from "@cometchat/chat-sdk-react-native"; + +const uiKitSettings: UIKitSettings = { + appId: "APP_ID", + authKey: "AUTH_KEY", + region: "REGION", + subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS as UIKitSettings["subscriptionType"], + offline: { + enabled: true, + mediaCaching: CometChat.MediaCachingMode.AUTO, + }, +}; + +CometChatUIKit.init(uiKitSettings) + .then(() => { + console.log("CometChat UI Kit initialized with offline support."); + }) + .catch((error) => { + console.error("CometChat UI Kit initialization failed:", error); + }); +``` + + +```jsx +import { CometChatUIKit } from "@cometchat/chat-uikit-react-native"; +import { CometChat } from "@cometchat/chat-sdk-react-native"; + +const uiKitSettings = { + appId: "APP_ID", + authKey: "AUTH_KEY", + region: "REGION", + subscriptionType: CometChat.AppSettings.SUBSCRIPTION_TYPE_ALL_USERS, + offline: { + enabled: true, + mediaCaching: CometChat.MediaCachingMode.AUTO, + }, +}; + +CometChatUIKit.init(uiKitSettings) + .then(() => { + console.log("CometChat UI Kit initialized with offline support."); + }) + .catch((error) => { + console.error("CometChat UI Kit initialization failed:", error); + }); +``` + + + +`offline` accepts three forms: + +| Value | Result | +| --- | --- | +| `true` | Offline support with the SDK's default options. | +| An options object (`UIKitOfflineSettings`) | The options you set, with defaults for the rest. Include `enabled: true`: without it, `enabled` is `false` and offline support stays off. Every option is listed in the [SDK's `OfflineConfig` options](/sdk/react-native/offline-reference#offlineconfig-options). | +| A `CometChat.OfflineConfig` | Passed to the SDK as it is. Create it with `enabled: true`. | + +If you leave `offline` out, or set it to `false`, offline support stays off and the UI Kit works exactly as before. + +### With `initFromSettings` + +If you initialize with `CometChatUIKit.initFromSettings()`, pass the same value as its second argument, or put it under `chatSDK.offline` in the settings. A value passed as the argument replaces the one in the settings. + +```tsx +CometChatUIKit.initFromSettings(settings, { enabled: true }); +``` + +### Check that it is running + +The UI Kit never reads back the value you configured. It asks the SDK with `CometChat.isOfflineEnabled()` each time it needs to, because offline support can be inactive even when you enabled it: before anyone logs in, when the local database cannot open, or when it is turned off for your app remotely. Do the same in your own code. + +```tsx +import { CometChat } from "@cometchat/chat-sdk-react-native"; + +const active: boolean = CometChat.isOfflineEnabled(); +``` + + +Without `@op-engineering/op-sqlite`, or with a Chat SDK older than 4.2.0, offline support stays off and the UI Kit works online only. Check `CometChat.isOfflineEnabled()` after login to confirm it is running. + + +## How the Components Behave Offline + +Everything in this section applies only while offline support is running. With it off, every component behaves as before. + +### Lists + +The same rule applies to [Conversations](/ui-kit/react-native/conversations), [Users](/ui-kit/react-native/users), [Groups](/ui-kit/react-native/groups), [Group Members](/ui-kit/react-native/group-members) (banned members too), the [Message List](/ui-kit/react-native/message-list) and threads, [Search](/ui-kit/react-native/search), the reactions list, [Pinned Messages](/ui-kit/react-native/pinned-messages), [Saved Messages](/ui-kit/react-native/saved-messages) and the [Notification Feed](/ui-kit/react-native/notification-feed): + +- **Saved rows show at once.** The server's page then merges into them in place, with no flicker or reload. +- **Offline with rows on screen:** a load that fails because there is no connection leaves the rows on screen, with no error view. +- **Offline with nothing saved:** the list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, messages, reactions, notifications), with no Retry button. If you passed your own `ErrorView`, it shows instead. +- **Online, the server returns nothing:** the empty view (yours, if you passed one). +- **Online, a real error:** the error view with Retry when nothing is on screen, as before; rows already on screen stay. +- **On reconnect:** rows update in place. A list reloads once by itself only if it was showing the offline state or an offline search. + +### Search + +A keyword search offline shows the saved matches. With no saved match it shows **Connect to search**, with the second line **Search needs an internet connection.** If you passed your own empty view, it shows instead. When the connection returns, the search runs again once. + +Only a real keyword counts as a search. A list opened with only a filter (for example, online users only, a tags filter, or a request builder without a keyword) is a plain list, and offline with nothing saved it shows that list's **Connect to load …** text. + +On the [Search](/ui-kit/react-native/search) screen, with nothing saved, **Connect to search** shows when a keyword could not reach the server, or when neither the chats search nor the messages search could. A filter-only search where only one of them could not reach the server shows the plain empty state. + +### Message list and threads + +- A chat or thread opened before shows its saved messages at once. +- At the older end of the saved history, the list shows a tappable **Connect to load more** row. After a jump to a message, the same row can also appear at the newer end. When the connection returns, the page behind each blocked edge loads once by itself, older pages first. Tapping or scrolling there works too. +- A failed older page (a server error or no connection) never ends the list; only an empty server page does. +- **Start from the first unread** (`startFromUnreadMessages`) and a jump to a message land on the right message before the list pages or follows new messages. After a jump to an older message, scrolling to the end (or "latest") loads the rest, so no message is skipped. +- On reconnect the message and conversation lists use the SDK's catch-up instead of making their own requests. Pull-to-refresh on the conversation list asks the SDK to sync. + +### Sending messages + +- A message sent offline appears in the list straight away with a clock icon and **Not sent yet**, and is queued on the device, even if the app is closed. It is sent automatically when the connection returns. A queued message is not a failure. +- A message that could not be sent shows an error icon and **Not sent. Tap to retry**. Failures come from the SDK's message status, so they survive an app restart. +- Every unsent message (waiting, sending or failed) offers **Retry** and **Delete** in its menu, and nothing else, because the other actions need a message that reached the server. For a queued message, Retry asks the SDK to send that same message again rather than creating a new one, so it cannot duplicate it. A message that failed before it was queued is sent again as a new message. Delete removes it from the device for good. +- If the message is being sent at that moment, Retry and Delete change nothing and the UI Kit shows **Sending… try again in a moment** for about four seconds. +- When the device's outbox is full, the send is refused and the UI Kit shows **Too many messages waiting to send** once for that message. A file too large to queue shows **File too large to send offline**. See [Queue Limits](/sdk/react-native/offline-send#queue-limits) for the SDK's limits. +- The conversation's row in [Conversations](/ui-kit/react-native/conversations) shows the same clock or error icon while its last message is waiting or failed. +- If offline support is turned off for your app remotely while messages are waiting, those rows turn failed at the next connection change, with one notice. Retry then sends them as new messages. + +### Attachments and media + +- Attachments staged in the composer tray (both the [Message Composer](/ui-kit/react-native/message-composer) and the [Compact Message Composer](/ui-kit/react-native/compact-message-composer)) survive leaving the chat and an app restart. Files that finished uploading stay done; interrupted files come back failed with a retry button. Nothing uploads by itself. +- Images, videos, audio and files come from the SDK's saved copy when it has one, with `mediaCaching` set to `AUTO` (the default). See [Media Caching](/sdk/react-native/offline-media-caching). +- Media the device never downloaded shows **Available when online** while offline. Tapping it online asks the SDK to download and save it. +- Download, "Download all" and Share in the media viewer use the saved file when there is one, without fetching it again. Offline with no saved copy, they show **Available when online**. + +### Edits, deletes and reactions + +Editing or deleting a sent message and adding or removing a reaction are not queued offline: they go to the server when the user acts and fail without a connection (see the [SDK's rules](/sdk/react-native/offline-send#edits-deletes-and-reactions-need-a-connection)). The UI Kit handles the failure for you: + +- An edit that fails offline keeps its text in edit mode, in both composers, so the user can send it again. +- A reaction that fails is rolled back; the message shows what it showed before the tap. +- A failed edit, delete or reaction shows the UI Kit's "Something went wrong" notice. + +Edits, deletes and reactions made by other users while the device was offline arrive with the catch-up when it reconnects. + +### Presence + +While the SDK is disconnected, nobody shows online: no "Online" subtitle, no green status dot and no typing text, in every list and header. Presence comes back when the connection returns. + +### Pinned, Saved, Reactions and Notifications + +[Pinned Messages](/ui-kit/react-native/pinned-messages), [Saved Messages](/ui-kit/react-native/saved-messages), the reactions list and the [Notification Feed](/ui-kit/react-native/notification-feed) follow the [list rule](#lists): saved rows first, and **Connect to load messages**, **Connect to load reactions** or **Connect to load notifications** when nothing is saved. + +### Group changes while offline + +If the user was kicked, banned or removed from a group while the device was offline, the conversation list drops that conversation when the catch-up arrives, as the message header and the groups list do. + +### Logout and user switch + +The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray, and the SDK deletes that user's cached data, cached media and queued messages. Logging in again as the same user keeps the cache. You don't need to clear anything yourself. See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). + +## Offline States and Texts + +These texts appear only with offline support running. Each one has a localization key you can override (see [Change the texts](#change-the-texts)). They are translated in all 18 locales of the UI Kit. + +| Text | Key | Where it appears | +| --- | --- | --- | +| Connect to load chats | `OFFLINE_CONNECT_TO_LOAD_CHATS` | Conversations, offline with nothing saved | +| Connect to load users | `OFFLINE_CONNECT_TO_LOAD_USERS` | Users, offline with nothing saved (also a filter-only list) | +| Connect to load groups | `OFFLINE_CONNECT_TO_LOAD_GROUPS` | Groups, offline with nothing saved | +| Connect to load members | `OFFLINE_CONNECT_TO_LOAD_MEMBERS` | Group Members and banned members, offline with nothing saved | +| Connect to load messages | `OFFLINE_CONNECT_TO_LOAD_MESSAGES` | Message list, threads, Pinned and Saved, offline with nothing saved | +| Connect to load reactions | `OFFLINE_CONNECT_TO_LOAD_REACTIONS` | Reactions list, offline with nothing saved | +| Connect to load notifications | `OFFLINE_CONNECT_TO_LOAD_NOTIFICATIONS` | Notification Feed, offline with nothing saved | +| Connect to search | `OFFLINE_CONNECT_TO_SEARCH`, `OFFLINE_CONNECT_TO_SEARCH_MESSAGES` | A keyword search offline with no saved match | +| Search needs an internet connection. | `OFFLINE_CONNECT_TO_SEARCH_SUBTITLE` | Second line under **Connect to search** | +| Connect to load more | `OFFLINE_CONNECT_TO_LOAD_MORE` | Tappable row at a blocked edge of the message list or a thread, and the footer of other lists | +| Not sent yet | `OFFLINE_MESSAGE_NOT_SENT_YET` | Under an own message waiting to be sent | +| Not sent. Tap to retry | `OFFLINE_MESSAGE_NOT_SENT_TAP_TO_RETRY` | Under an own message that failed | +| Sending… try again in a moment | `OFFLINE_SEND_IN_FLIGHT` | Notice after Retry or Delete on a message being sent | +| Too many messages waiting to send | `OFFLINE_QUEUE_FULL` | Notice when the outbox is full | +| File too large to send offline | `OFFLINE_FILE_TOO_LARGE` | Notice when a file cannot be queued | +| Available when online | `OFFLINE_MEDIA_AVAILABLE_WHEN_ONLINE` | Media the device never downloaded, and Download or Share without a saved copy | +| 1 unsent message was removed | `OFFLINE_UNSENT_MESSAGE_REMOVED` | Notice, with **Copy** for a text message, when an unsent message was removed | +| {count} message wasn't sent / {count} messages weren't sent | `OFFLINE_MESSAGES_NOT_SENT_ONE`, `OFFLINE_MESSAGES_NOT_SENT_OTHER` | Notice when queued messages failed | +| {count} unsent message couldn't be recovered / {count} unsent messages couldn't be recovered | `OFFLINE_UNSENT_MESSAGES_LOST_ONE`, `OFFLINE_UNSENT_MESSAGES_LOST_OTHER` | Notice after a cache reset lost queued messages | +| Some unsent messages may not have been sent | `OFFLINE_UNSENT_MESSAGES_MAYBE_LOST` | Notice after a cache reset when the SDK could not count the lost messages | + +Keys with a count have `_ONE` and `_OTHER` forms; `{count}` is replaced with the number. + +## Errors and Callbacks + +### When `onError` fires + +| Situation | What shows | `onError` | +| --- | --- | --- | +| Offline, rows on screen, a load fails | The rows stay | Not called | +| Offline, nothing on screen | **Connect to load …** (or your `ErrorView`) | Called once for that load | +| Offline keyword search, no saved match | **Connect to search** (or your empty view) | Not called | +| Online, a real error, nothing on screen | The error view with Retry (or your `ErrorView`) | Called | +| Online, a real error, rows on screen | The rows stay | Called once if the user or your app started the load (opening the list, `reload()`, pull-to-refresh, a keyword change, paging, a jump to a message). Not called for loads the UI Kit starts by itself (reconnect, catch-up pages, cache reset) | + +The reactions list, Pinned and Saved have no `onError` prop, so they show the state only. + +### `CometChatUIKit.send*` promises + +With offline support running, the promise returned by `CometChatUIKit.sendTextMessage`, `sendMediaMessage` and `sendCustomMessage`: + +- **resolves** when the message reaches the server, also when it was queued first; +- **rejects** on a final failure; +- never rejects just because the message was queued; +- **rejects once, quietly,** with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED` when the user logs out or switches user while the send is waiting, or when a cache reset loses the queued message. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. + +If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` as "the send ended with the session", not as a failure to show the user. + +```tsx +import { CometChatUIKit } from "@cometchat/chat-uikit-react-native"; + +try { + await CometChatUIKit.sendTextMessage(textMessage); +} catch (error: any) { + if (error?.code === "ERROR_OFFLINE_MESSAGE_DISCARDED") { + // The session ended before the message was sent. Nothing to show. + return; + } + // A real failure. +} +``` + +### Offline events + +The UI Kit emits two events on the existing message event bus. Both are new and **never emitted with offline support off**. `ccMessageSent` keeps its meaning. + +| Event | Payload | When | +| --- | --- | --- | +| `ccMessageSendStateChanged` | `MessageSendStateChangedEvent`: `{ message, state, reason? }` | An own message's send state changed. `state` is a `MessageSendState`: `"sending"`, `"sent"`, `"failed"` or `"discarded"`. `reason` is the SDK's `MessageFailureReason` for `"failed"` and `"discarded"`. | +| `ccOfflineCacheReset` | `OfflineCacheResetEvent`: `{ reason, pendingMessagesLost }` | The SDK rebuilt its offline cache. `reason` is the SDK's `OfflineCacheResetReason`; `pendingMessagesLost` is the number of unsent messages lost, or `null` when the SDK could not count them. | + +The event names are on `OfflineMessageEvents`, and the payload types are exported from the package. + + + +```tsx +import { useEffect } from "react"; +import { + CometChatUIEventHandler, + OfflineMessageEvents, + MessageSendStateChangedEvent, + OfflineCacheResetEvent, +} from "@cometchat/chat-uikit-react-native"; + +const LISTENER_ID = "OFFLINE_EVENTS_LISTENER"; + +useEffect(() => { + CometChatUIEventHandler.addMessageListener(LISTENER_ID, { + [OfflineMessageEvents.ccMessageSendStateChanged]: ({ message, state, reason }: MessageSendStateChangedEvent) => { + console.log("Send state:", state, reason); + }, + [OfflineMessageEvents.ccOfflineCacheReset]: ({ reason, pendingMessagesLost }: OfflineCacheResetEvent) => { + console.log("Offline cache reset:", reason, pendingMessagesLost); + }, + }); + return () => CometChatUIEventHandler.removeMessageListener(LISTENER_ID); +}, []); +``` + + +```jsx +import { useEffect } from "react"; +import { + CometChatUIEventHandler, + OfflineMessageEvents, +} from "@cometchat/chat-uikit-react-native"; + +const LISTENER_ID = "OFFLINE_EVENTS_LISTENER"; + +useEffect(() => { + CometChatUIEventHandler.addMessageListener(LISTENER_ID, { + [OfflineMessageEvents.ccMessageSendStateChanged]: ({ message, state, reason }) => { + console.log("Send state:", state, reason); + }, + [OfflineMessageEvents.ccOfflineCacheReset]: ({ reason, pendingMessagesLost }) => { + console.log("Offline cache reset:", reason, pendingMessagesLost); + }, + }); + return () => CometChatUIEventHandler.removeMessageListener(LISTENER_ID); +}, []); +``` + + + +For the SDK's own listeners (sync progress, the outbox, cache resets), see [Stay in Sync](/sdk/react-native/offline-sync) and [Send While Offline](/sdk/react-native/offline-send). + +## Customization + +### Hide the offline notices + +`CometChatMessageList` and `CometChatConversations` take `hideOfflineNotices` (default `false`). It hides the one-line notices: an unsent message removed, the outbox full, messages not sent, and the cache rebuilt or unsent messages lost. It has no effect with offline support off. The **Not sent** rows, the offline states and **Connect to load more** still show. + +```tsx + + +``` + +### Your own error and empty views + +If you pass your own `ErrorView` to a list, it shows instead of the UI Kit's **Connect to load …** state. If you pass your own `EmptyView`, it shows instead of **Connect to search**. + +### Style the offline states + +Set `messageListStyles.offlineStyles` in your theme. Everything is optional: anything you leave out uses the theme's existing error and date styles. These styles are used by the message list, the conversation list (its notice) and the media bubbles. + +| Property | Type | Styles | +| --- | --- | --- | +| `failedRowStyle` | `ViewStyle` | The tappable **Not sent. Tap to retry** row of a failed message (no tint by default) | +| `failedIconStyle` | `ImageStyle` | The error icon of a failed message | +| `retryTextStyle` | `TextStyle` | The **Not sent. Tap to retry** text | +| `notSentYetTextStyle` | `TextStyle` | The **Not sent yet** text | +| `mediaPlaceholderStyle` | `{ containerStyle?: ViewStyle; textStyle?: TextStyle }` | The **Available when online** placeholder for media | +| `footerStyle` | `{ containerStyle?: ViewStyle; textStyle?: TextStyle }` | The **Connect to load more** row and list footer | +| `noticeStyle` | `{ containerStyle?: ViewStyle; textStyle?: TextStyle; actionTextStyle?: TextStyle }` | The one-line notices and their **Copy** action | + +```tsx +import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native"; + + + {/* your app */} + +``` + +See [Theming](/ui-kit/react-native/theme) for how theme values merge with the defaults. + +### Change the texts + +Override any key from the [table above](#offline-states-and-texts) with `CometChatI18nProvider`. See [Localization](/ui-kit/react-native/localize) for how keys and language codes resolve. + +```tsx +import { CometChatI18nProvider } from "@cometchat/chat-uikit-react-native"; + + + {/* your app */} + +``` + +## With Offline Support Turned Off + +If you don't set `offline`, none of the behavior on this page runs: no offline states, no queued sends, no new events, and no new request, timer, connectivity check, file or storage. Upgrading to 5.6.0 still changes a few things for every app: + +- **Retry on a failed text or custom message works.** It used to do nothing. It now sends again through the same `CometChatUIKit.send*` path and emits `ccMessageSent` (in progress, then success or error) again. +- **A message rejected by moderation keeps its error icon and no longer offers Retry.** +- **A failed reaction is rolled back**, so the message shows what it showed before the tap. +- **Edits always update the right message.** Two messages without a `muid` could match each other before. +- **Reconnect catch-up pages forward.** A full page is followed by the next one instead of fetching the same page again. +- **Lists reload with your current request builder on reconnect,** not the one from their first render. +- **Automation identifiers:** the composer input has the `testID` `cc-composer-input` and the send button `CometChatComposer.send`. View-snapshot tests that include them may change. + +## Limitations and Known Issues + +- The cache holds only what the user loaded while online, plus what the catch-up brings in on reconnect. A user who has never been online on this device has nothing to show offline. +- Keyword search with no saved match, message information, call logs, calls and AI streamed replies need a connection. +- Edits, deletes and reactions on sent messages are not queued offline. +- If the acknowledgement of a send is lost, the server can occasionally end up with one duplicate of that message. +- After a quick reconnect, missed messages can take up to about 10 seconds to appear. +- After an app restart, the reason a message failed may be unknown; it is still offered Retry. +- A chat can stop receiving updates while online if a send got no answer while connected; it resumes at the next reconnect. +- With `encryption: true` and `PLAINTEXT_FALLBACK` on a device without a secure key store, the SDK resets the cache with `ENCRYPTION_CHANGED` on every launch. Install `react-native-keychain`. The UI Kit shows a notice only when queued messages were lost. See [Encrypt the Cache](/sdk/react-native/offline-encryption). +- A conversation started offline can be removed by the SDK and its queued messages discarded; the UI Kit shows a notice with **Copy** for the text. +- On Android, a file the SDK saved but the UI Kit never downloaded may not open offline; the UI Kit shows **Available when online**. iOS opens it. With `enableMultipleAttachments={false}`, the older single-file bubble opens files only when online, on both platforms. + +--- + +## Next Steps + + + + How caching, the send outbox and catch-up work in the Chat SDK + + + Every OfflineConfig option, method, listener and error code + + + The outbox, retry and discard, and queue limits + + + See how the components power each chat feature + + From ac2cd8c5cc66dea9334c2377a5147482277812e8 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Wed, 18 Nov 2026 00:37:51 +0530 Subject: [PATCH 02/13] docs: a failed edit clears the composer, as on Android Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XbguTt1cqFxTDQyroF6wHx --- ui-kit/react-native/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index db7d18dc2..fd17dbcbd 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -250,7 +250,7 @@ On the [Search](/ui-kit/react-native/search) screen, with nothing saved, **Conne Editing or deleting a sent message and adding or removing a reaction are not queued offline: they go to the server when the user acts and fail without a connection (see the [SDK's rules](/sdk/react-native/offline-send#edits-deletes-and-reactions-need-a-connection)). The UI Kit handles the failure for you: -- An edit that fails offline keeps its text in edit mode, in both composers, so the user can send it again. +- An edit that fails offline leaves the message with its old text. The composer clears and leaves edit mode when the edit is sent, as it does online. - A reaction that fails is rolled back; the message shows what it showed before the tap. - A failed edit, delete or reaction shows the UI Kit's "Something went wrong" notice. From 100710a46b484e02b036b4cc31f79ea58b802be2 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 17:07:18 +0530 Subject: [PATCH 03/13] docs(ENG-57592): correct the React Native offline support page - Files picked into the composer tray are not queued offline; say so, and list what is queued (text, custom, voice notes, uploaded media). - Logout and user switch delete the cache; a restart with the same user keeps it (the old "logging in again keeps the cache" was wrong). - Retry on a message the SDK no longer holds removes the row. - A failed edit is not put back and goes to the composer's onError. - Download and Share copy local files only from the SDK media folder. - Thread header counts a queued reply once. - Escape the {count} placeholders so MDX does not evaluate them. Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/core-features.mdx | 2 +- ui-kit/react-native/offline-support.mdx | 21 +++++++++++++-------- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/ui-kit/react-native/core-features.mdx b/ui-kit/react-native/core-features.mdx index 70f5130d7..cff38a00c 100644 --- a/ui-kit/react-native/core-features.mdx +++ b/ui-kit/react-native/core-features.mdx @@ -299,7 +299,7 @@ Offline Support keeps chat usable without a network. Chats and messages the user | --- | --- | | [Conversations](/ui-kit/react-native/conversations), [Users](/ui-kit/react-native/users), [Groups](/ui-kit/react-native/groups), [Group Members](/ui-kit/react-native/group-members) | Show saved rows first and merge the server's page in place; offline with nothing saved, show **Connect to load …**. | | [Message List](/ui-kit/react-native/message-list) | Shows saved history, marks queued and failed messages, and offers **Connect to load more** at a blocked edge. | -| [Message Composer](/ui-kit/react-native/message-composer) | Queues messages sent offline and keeps staged attachments across restarts. | +| [Message Composer](/ui-kit/react-native/message-composer) | Queues messages sent offline and keeps staged attachments across restarts. Files picked into the tray while offline are not queued: retry their upload once online. | See [Offline Support](/ui-kit/react-native/offline-support) for setup, native dependencies and the full behavior. diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index fd17dbcbd..5ebb299fe 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -36,7 +36,7 @@ Offline support is available from React Native UI Kit **5.6.0** with React Nativ **Works offline** - Conversations, users, groups, group members, messages and threads the user has opened before appear at once from the device, then the server's page merges into them in place when it arrives. -- New messages (text, media and custom messages) are queued on the device, survive an app restart, and are sent automatically when the connection returns. +- New messages (text and custom messages, voice notes, and media messages whose files have already uploaded) are queued on the device, survive an app restart, and are sent automatically when the connection returns. - A message that could not be sent shows **Not sent. Tap to retry**, with Retry and Delete. - Images, videos, audio and files the device has already saved are shown from the device. - Attachments staged in the composer survive leaving the chat and an app restart. @@ -47,6 +47,7 @@ Offline support is available from React Native UI Kit **5.6.0** with React Nativ - The first load of a chat, list or page that was never opened on this device. - Keyword search with no saved match, message information, call logs, calls and AI streamed replies. - Editing, deleting and reacting to messages that are already sent. These are not queued offline. See [Edits, deletes and reactions](#edits-deletes-and-reactions). +- Uploading files picked in the composer tray. A file picked while offline is not queued; see [Attachments and media](#attachments-and-media). - Media the device never downloaded. ## Requirements @@ -56,7 +57,7 @@ Offline support is available from React Native UI Kit **5.6.0** with React Nativ | `@cometchat/chat-uikit-react-native` | 5.6.0 or later | | `@cometchat/chat-sdk-react-native` | 4.2.0 or later | -The UI Kit's peer dependency on the Chat SDK stays `*`. The kit checks at runtime whether the installed SDK supports offline, so an app on an older SDK keeps working online only, and the `offline` setting is ignored. +The UI Kit's peer dependency on the Chat SDK stays `*`. The kit checks at runtime whether the installed SDK supports offline, so an app on an older SDK keeps working online only, and the `offline` setting is ignored. Use the latest Chat SDK release, which includes the newest offline fixes. ### Install the native dependencies @@ -65,7 +66,7 @@ Offline support stores data in a local database, which the Chat SDK opens throug | Package | Needed for | | --- | --- | | `@op-engineering/op-sqlite` (9.0.0 or later) | The local database. **Required for offline support.** Without it the SDK runs online only. | -| `react-native-fs` | Optional. Caching media on the device, and playable copies of cached audio and video in the UI Kit. Without it, the UI Kit uses the cached file as it is. | +| `react-native-fs` | Optional. Caching media on the device, the SDK's copy of media queued offline, and playable copies of cached audio and video in the UI Kit. Without it, the UI Kit uses the cached file as it is. | | `react-native-keychain` | Only for [encrypting the cache](/sdk/react-native/offline-encryption). | ```bash @@ -228,12 +229,13 @@ On the [Search](/ui-kit/react-native/search) screen, with nothing saved, **Conne - A failed older page (a server error or no connection) never ends the list; only an empty server page does. - **Start from the first unread** (`startFromUnreadMessages`) and a jump to a message land on the right message before the list pages or follows new messages. After a jump to an older message, scrolling to the end (or "latest") loads the rest, so no message is skipped. - On reconnect the message and conversation lists use the SDK's catch-up instead of making their own requests. Pull-to-refresh on the conversation list asks the SDK to sync. +- The [thread header](/ui-kit/react-native/threaded-messages-header) counts the user's own reply once, when it is queued, and takes it back if the reply is removed before it was sent. ### Sending messages - A message sent offline appears in the list straight away with a clock icon and **Not sent yet**, and is queued on the device, even if the app is closed. It is sent automatically when the connection returns. A queued message is not a failure. - A message that could not be sent shows an error icon and **Not sent. Tap to retry**. Failures come from the SDK's message status, so they survive an app restart. -- Every unsent message (waiting, sending or failed) offers **Retry** and **Delete** in its menu, and nothing else, because the other actions need a message that reached the server. For a queued message, Retry asks the SDK to send that same message again rather than creating a new one, so it cannot duplicate it. A message that failed before it was queued is sent again as a new message. Delete removes it from the device for good. +- Every unsent message (waiting, sending or failed) offers **Retry** and **Delete** in its menu, and nothing else, because the other actions need a message that reached the server. For a queued message, Retry asks the SDK to send that same message again rather than creating a new one, so it cannot duplicate it. A message that failed before it was queued is sent again as a new message. If the SDK no longer holds the message (for example, its chat was removed from the device after the send failed), Retry removes the row, because there is nothing left to send. Delete removes it from the device for good. - If the message is being sent at that moment, Retry and Delete change nothing and the UI Kit shows **Sending… try again in a moment** for about four seconds. - When the device's outbox is full, the send is refused and the UI Kit shows **Too many messages waiting to send** once for that message. A file too large to queue shows **File too large to send offline**. See [Queue Limits](/sdk/react-native/offline-send#queue-limits) for the SDK's limits. - The conversation's row in [Conversations](/ui-kit/react-native/conversations) shows the same clock or error icon while its last message is waiting or failed. @@ -242,15 +244,17 @@ On the [Search](/ui-kit/react-native/search) screen, with nothing saved, **Conne ### Attachments and media - Attachments staged in the composer tray (both the [Message Composer](/ui-kit/react-native/message-composer) and the [Compact Message Composer](/ui-kit/react-native/compact-message-composer)) survive leaving the chat and an app restart. Files that finished uploading stay done; interrupted files come back failed with a retry button. Nothing uploads by itself. +- A file picked in the tray uploads right away, which needs a connection. Picked while offline, its upload fails and the tile shows a retry button; the file is not queued and nothing is sent. Retry it once the connection returns, then send. A voice note, and a file sent with `enableMultipleAttachments={false}`, go out as a message straight away, so the SDK queues them like any other message (see [Send While Offline](/sdk/react-native/offline-send)). - Images, videos, audio and files come from the SDK's saved copy when it has one, with `mediaCaching` set to `AUTO` (the default). See [Media Caching](/sdk/react-native/offline-media-caching). - Media the device never downloaded shows **Available when online** while offline. Tapping it online asks the SDK to download and save it. - Download, "Download all" and Share in the media viewer use the saved file when there is one, without fetching it again. Offline with no saved copy, they show **Available when online**. +- Download and Share copy a file that is already on the device only from the Chat SDK's offline media folder. Any other local file a message points to is refused and nothing is copied. ### Edits, deletes and reactions Editing or deleting a sent message and adding or removing a reaction are not queued offline: they go to the server when the user acts and fail without a connection (see the [SDK's rules](/sdk/react-native/offline-send#edits-deletes-and-reactions-need-a-connection)). The UI Kit handles the failure for you: -- An edit that fails offline leaves the message with its old text. The composer clears and leaves edit mode when the edit is sent, as it does online. +- An edit that fails offline leaves the message with its old text. The composer clears and leaves edit mode when the edit is sent, as it does online, and the edited text is not put back. The error goes to the composer's `onError`. - A reaction that fails is rolled back; the message shows what it showed before the tap. - A failed edit, delete or reaction shows the UI Kit's "Something went wrong" notice. @@ -270,7 +274,7 @@ If the user was kicked, banned or removed from a group while the device was offl ### Logout and user switch -The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray, and the SDK deletes that user's cached data, cached media and queued messages. Logging in again as the same user keeps the cache. You don't need to clear anything yourself. See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). +The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray. On logout and a user switch, the SDK also deletes that user's cached data, cached media and queued messages. Restarting the app while the same user stays logged in keeps the cache. You don't need to clear anything yourself. A `CometChatUIKit.send*` call still waiting at that moment is settled quietly; see [Errors and Callbacks](#errors-and-callbacks). See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). ## Offline States and Texts @@ -295,8 +299,8 @@ These texts appear only with offline support running. Each one has a localizatio | File too large to send offline | `OFFLINE_FILE_TOO_LARGE` | Notice when a file cannot be queued | | Available when online | `OFFLINE_MEDIA_AVAILABLE_WHEN_ONLINE` | Media the device never downloaded, and Download or Share without a saved copy | | 1 unsent message was removed | `OFFLINE_UNSENT_MESSAGE_REMOVED` | Notice, with **Copy** for a text message, when an unsent message was removed | -| {count} message wasn't sent / {count} messages weren't sent | `OFFLINE_MESSAGES_NOT_SENT_ONE`, `OFFLINE_MESSAGES_NOT_SENT_OTHER` | Notice when queued messages failed | -| {count} unsent message couldn't be recovered / {count} unsent messages couldn't be recovered | `OFFLINE_UNSENT_MESSAGES_LOST_ONE`, `OFFLINE_UNSENT_MESSAGES_LOST_OTHER` | Notice after a cache reset lost queued messages | +| \{count\} message wasn't sent / \{count\} messages weren't sent | `OFFLINE_MESSAGES_NOT_SENT_ONE`, `OFFLINE_MESSAGES_NOT_SENT_OTHER` | Notice when queued messages failed | +| \{count\} unsent message couldn't be recovered / \{count\} unsent messages couldn't be recovered | `OFFLINE_UNSENT_MESSAGES_LOST_ONE`, `OFFLINE_UNSENT_MESSAGES_LOST_OTHER` | Notice after a cache reset lost queued messages | | Some unsent messages may not have been sent | `OFFLINE_UNSENT_MESSAGES_MAYBE_LOST` | Notice after a cache reset when the SDK could not count the lost messages | Keys with a count have `_ONE` and `_OTHER` forms; `{count}` is replaced with the number. @@ -484,6 +488,7 @@ If you don't set `offline`, none of the behavior on this page runs: no offline s - **Edits always update the right message.** Two messages without a `muid` could match each other before. - **Reconnect catch-up pages forward.** A full page is followed by the next one instead of fetching the same page again. - **Lists reload with your current request builder on reconnect,** not the one from their first render. +- **Download and Share copy a local file only from the Chat SDK's offline media folder.** When a message's attachment points to any other file on the device, nothing is copied (on Android the UI Kit shows **File download failed.**). - **Automation identifiers:** the composer input has the `testID` `cc-composer-input` and the send button `CometChatComposer.send`. View-snapshot tests that include them may change. ## Limitations and Known Issues From a1c73354cabd67de3fb09014b026790b9616339a Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 17:07:18 +0530 Subject: [PATCH 04/13] docs(ENG-57592): link offline support from the React Native UI Kit pages - methods: offline setting in UIKitSettings and Init (with an example), logout clears the offline cache, send* promise behaviour offline. - CLI and Expo integration: short note with requirements and a link. - overview: Offline Support card. - conversations and message list: hideOfflineNotices prop and a note. - message composer, compact composer, thread header: one-line notes. - events: ccMessageSendStateChanged and ccOfflineCacheReset. - localize: the offline string keys with their English texts. Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- .../react-native/compact-message-composer.mdx | 4 ++ ui-kit/react-native/conversations.mdx | 16 ++++++++ ui-kit/react-native/events.mdx | 4 +- ui-kit/react-native/expo-integration.mdx | 4 ++ ui-kit/react-native/localize.mdx | 30 ++++++++++++++ ui-kit/react-native/message-composer.mdx | 4 ++ ui-kit/react-native/message-list.mdx | 16 ++++++++ ui-kit/react-native/methods.mdx | 39 +++++++++++++++++++ ui-kit/react-native/overview.mdx | 3 ++ .../react-native-cli-integration.mdx | 4 ++ .../react-native/threaded-messages-header.mdx | 4 ++ 11 files changed, 127 insertions(+), 1 deletion(-) diff --git a/ui-kit/react-native/compact-message-composer.mdx b/ui-kit/react-native/compact-message-composer.mdx index 6e8929198..dee7323e8 100644 --- a/ui-kit/react-native/compact-message-composer.mdx +++ b/ui-kit/react-native/compact-message-composer.mdx @@ -52,6 +52,10 @@ function CompactComposerDemo() { export default CompactComposerDemo; ``` + +With [offline support](/ui-kit/react-native/offline-support) on, text messages and voice notes sent without a connection are queued and sent when the connection returns, and the tray survives leaving the chat and an app restart. A file picked into the tray while offline is not queued: its upload fails, and you retry it from the tile once the connection returns. Editing a sent message needs a connection; a failed edit goes to `onError`. See [Sending messages](/ui-kit/react-native/offline-support#sending-messages) and [Attachments and media](/ui-kit/react-native/offline-support#attachments-and-media). + + --- ## Actions and Events diff --git a/ui-kit/react-native/conversations.mdx b/ui-kit/react-native/conversations.mdx index 9992eafb7..4385cd5e7 100644 --- a/ui-kit/react-native/conversations.mdx +++ b/ui-kit/react-native/conversations.mdx @@ -42,6 +42,7 @@ description: "Display CometChat React Native UI Kit conversations with last mess "hideHeader": { "type": "boolean", "default": false }, "pinConversationOptionVisibility": { "type": "boolean", "default": true }, "hideError": { "type": "boolean", "default": false }, + "hideOfflineNotices": { "type": "boolean", "default": false, "note": "Offline support only" }, "receiptsVisibility": { "type": "boolean", "default": true }, "hideSubmitButton": { "type": "boolean", "default": true }, "usersStatusVisibility": { "type": "boolean", "default": true }, @@ -209,6 +210,10 @@ function ConversationsDemo() { export default ConversationsDemo; ``` + +With [offline support](/ui-kit/react-native/offline-support) on, the list shows saved conversations at once, shows **Connect to load chats** when it is offline with nothing saved, and marks a conversation whose last message is waiting to send or failed. See [Lists](/ui-kit/react-native/offline-support#lists). + + --- ## Filtering Conversations @@ -1150,6 +1155,17 @@ Hides the entire header bar. --- +### hideOfflineNotices + +With [offline support](/ui-kit/react-native/offline-support) running, hides the one-line offline notices the list shows for the whole session, such as unsent messages that were lost when the offline cache was rebuilt. Has no effect with offline support off. + +| | | +| --- | --- | +| Type | `boolean` | +| Default | `false` | + +--- + ### hideSubmitButton Hides the submit button when selection mode is enabled. diff --git a/ui-kit/react-native/events.mdx b/ui-kit/react-native/events.mdx index 67db8dc7d..9e2ac934a 100644 --- a/ui-kit/react-native/events.mdx +++ b/ui-kit/react-native/events.mdx @@ -12,7 +12,7 @@ description: "Listen to UI Kit events for conversations, users, groups, messages | Conversation events | `ccConversationDeleted`, `ccUpdateConversation` | | User events | `ccUserBlocked`, `ccUserUnBlocked` | | Group events | `ccGroupCreated`, `ccGroupDeleted`, `ccGroupLeft`, `ccGroupMemberScopeChanged`, `ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberUnBanned`, `ccGroupMemberJoined`, `ccGroupMemberAdded`, `ccOwnershipChanged` | -| Message events | `ccMessageSent`, `ccMessageEdited`, `ccMessageDeleted`, `ccMessageRead`, `ccActiveChatChanged`, plus SDK listener events | +| Message events | `ccMessageSent`, `ccMessageEdited`, `ccMessageDeleted`, `ccMessageRead`, `ccActiveChatChanged`, plus SDK listener events. Offline support adds `OfflineMessageEvents.ccMessageSendStateChanged` and `OfflineMessageEvents.ccOfflineCacheReset` | | Call events | `ccCallAccepted`, `ccCallRejected`, `ccCallEnded`, `ccOutgoingCall`, `ccCallFailed` | | UI events | `ccCardActionClicked` | | Purpose | Decoupled communication between UI Kit components — subscribe to events to react to changes without direct component references | @@ -79,6 +79,8 @@ It consists of the following events: | ccMessagePinned / ccMessageUnpinned | Triggers when the user pins or unpins a message from the message list or the Pinned Messages panel. Payload: `{ message }`. | | ccMessageSaved / ccMessageUnsaved | Triggers when the user saves or unsaves a message from the message list, Pinned Messages or Saved Messages. Payload: `{ message }`. | | ccThreadSubscriptionChanged | Triggers when the user subscribes to or unsubscribes from a thread: on the optimistic change, on the server reply, and on a revert. Payload: `{ parentMessageId, subscribed, inProgress }`. | +| ccMessageSendStateChanged | [Offline support](/ui-kit/react-native/offline-support) only (UI Kit 5.6.0): an own message's send state changed. Payload: `{ message, state, reason? }`, where `state` is `"sending"`, `"sent"`, `"failed"` or `"discarded"`. The name is on `OfflineMessageEvents`. Never emitted with offline support off. | +| ccOfflineCacheReset | [Offline support](/ui-kit/react-native/offline-support) only (UI Kit 5.6.0): the Chat SDK rebuilt its offline cache. Payload: `{ reason, pendingMessagesLost }`. The name is on `OfflineMessageEvents`. Never emitted with offline support off. | | onTextMessageReceived | This event is emitted when the CometChat SDK listener emits a text message. | | onMediaMessageReceived | This event is emitted when the CometChat SDK listener emits a media message. | | onCustomMessageReceived | This event is emitted when the CometChat SDK listener emits a custom message. | diff --git a/ui-kit/react-native/expo-integration.mdx b/ui-kit/react-native/expo-integration.mdx index b51f3b0fd..206e73a1d 100644 --- a/ui-kit/react-native/expo-integration.mdx +++ b/ui-kit/react-native/expo-integration.mdx @@ -210,6 +210,10 @@ CometChatUIKit.init(uiKitSettings) + +**Optional: offline support.** To show saved chats without a connection and queue messages sent offline, add `offline: { enabled: true }` to `uiKitSettings`. It needs UI Kit 5.6.0 and Chat SDK 4.2.0 or later and the `@op-engineering/op-sqlite` native module, so it runs in a development build or after `expo prebuild`, not in Expo Go. See [Offline Support](/ui-kit/react-native/offline-support). + + --- ## Step 4 — Login diff --git a/ui-kit/react-native/localize.mdx b/ui-kit/react-native/localize.mdx index 380ef6cd9..e33016c1e 100644 --- a/ui-kit/react-native/localize.mdx +++ b/ui-kit/react-native/localize.mdx @@ -213,6 +213,36 @@ const CustomComponent = () => { CometChat UI Kit provides a `useCometChatTranslation` hook to access translations within components, which can be used when developing custom components. +### Offline Strings + +UI Kit 5.6.0 adds the texts of [offline support](/ui-kit/react-native/offline-support), translated in all 18 languages. They appear only while offline support is running. Override them like any other key. Keys ending in `_ONE` and `_OTHER` are the singular and plural forms of one text, chosen from the count for the current language; `{count}` is replaced with the number, so override both forms. See [Offline States and Texts](/ui-kit/react-native/offline-support#offline-states-and-texts) for where each text appears. + +| Key | English text | +| --- | --- | +| `OFFLINE_MESSAGE_NOT_SENT_YET` | Not sent yet | +| `OFFLINE_MESSAGE_NOT_SENT_TAP_TO_RETRY` | Not sent. Tap to retry | +| `OFFLINE_UNSENT_MESSAGE_REMOVED` | 1 unsent message was removed | +| `OFFLINE_MESSAGES_NOT_SENT_ONE` | \{count\} message wasn't sent | +| `OFFLINE_MESSAGES_NOT_SENT_OTHER` | \{count\} messages weren't sent | +| `OFFLINE_UNSENT_MESSAGES_LOST_ONE` | \{count\} unsent message couldn't be recovered | +| `OFFLINE_UNSENT_MESSAGES_LOST_OTHER` | \{count\} unsent messages couldn't be recovered | +| `OFFLINE_UNSENT_MESSAGES_MAYBE_LOST` | Some unsent messages may not have been sent | +| `OFFLINE_QUEUE_FULL` | Too many messages waiting to send | +| `OFFLINE_FILE_TOO_LARGE` | File too large to send offline | +| `OFFLINE_CONNECT_TO_LOAD_MORE` | Connect to load more | +| `OFFLINE_CONNECT_TO_SEARCH` | Connect to search | +| `OFFLINE_CONNECT_TO_SEARCH_MESSAGES` | Connect to search | +| `OFFLINE_CONNECT_TO_SEARCH_SUBTITLE` | Search needs an internet connection. | +| `OFFLINE_CONNECT_TO_LOAD_USERS` | Connect to load users | +| `OFFLINE_CONNECT_TO_LOAD_GROUPS` | Connect to load groups | +| `OFFLINE_CONNECT_TO_LOAD_CHATS` | Connect to load chats | +| `OFFLINE_CONNECT_TO_LOAD_MEMBERS` | Connect to load members | +| `OFFLINE_CONNECT_TO_LOAD_MESSAGES` | Connect to load messages | +| `OFFLINE_CONNECT_TO_LOAD_REACTIONS` | Connect to load reactions | +| `OFFLINE_CONNECT_TO_LOAD_NOTIFICATIONS` | Connect to load notifications | +| `OFFLINE_MEDIA_AVAILABLE_WHEN_ONLINE` | Available when online | +| `OFFLINE_SEND_IN_FLIGHT` | Sending… try again in a moment | + --- ## Methods diff --git a/ui-kit/react-native/message-composer.mdx b/ui-kit/react-native/message-composer.mdx index 12ce4544a..8b96a8d4f 100644 --- a/ui-kit/react-native/message-composer.mdx +++ b/ui-kit/react-native/message-composer.mdx @@ -68,6 +68,10 @@ When `enableMultipleAttachments` is `true` (the default), picking files does **n **Failed** uploads are transient and can be retried; **rejected** files must be swapped out. + +With [offline support](/ui-kit/react-native/offline-support) on, text messages and voice notes sent without a connection are queued and sent when the connection returns, and the tray survives leaving the chat and an app restart. A file picked into the tray while offline is not queued: its upload fails, and you retry it from the tile once the connection returns. Editing a sent message needs a connection; a failed edit goes to `onError`. See [Sending messages](/ui-kit/react-native/offline-support#sending-messages) and [Attachments and media](/ui-kit/react-native/offline-support#attachments-and-media). + + ### Attachment limits - **Count** — a batch holds up to a server-configured maximum (default **10**, from the `file.count.max` app setting, resolved at runtime). The limit is **all-or-nothing**: if a pick would push the tray past the maximum, the **entire new selection is rejected** — nothing is staged — and a toast explains the limit. Already-staged files are untouched. diff --git a/ui-kit/react-native/message-list.mdx b/ui-kit/react-native/message-list.mdx index 7e874a3cb..f1a46e13c 100644 --- a/ui-kit/react-native/message-list.mdx +++ b/ui-kit/react-native/message-list.mdx @@ -40,6 +40,7 @@ description: "Display sent and received messages with text, media, reactions, re "receiptsVisibility": { "type": "boolean", "default": true }, "avatarVisibility": { "type": "boolean", "default": true }, "hideError": { "type": "boolean", "default": false }, + "hideOfflineNotices": { "type": "boolean", "default": false, "note": "Offline support only" }, "hideTimestamp": { "type": "boolean", "default": false }, "hideReplyOption": { "type": "boolean", "default": false }, "hideReplyInThreadOption": { "type": "boolean", "default": false }, @@ -193,6 +194,10 @@ export default MessageListDemo; Simply adding the `CometChatMessageList` component to the layout will result in an error. To fetch messages, you need to supplement it with `user` or `group` prop. + +With [offline support](/ui-kit/react-native/offline-support) on, the list shows saved messages at once, marks own messages that are waiting to send (**Not sent yet**) or failed (**Not sent. Tap to retry**, with Retry and Delete), and shows **Connect to load more** where older messages need a connection. See [Message list and threads](/ui-kit/react-native/offline-support#message-list-and-threads). + + --- ## Multi-Attachment Batch Grouping @@ -1193,6 +1198,17 @@ Hides group action messages (join, leave, kick, etc.). --- +### hideOfflineNotices + +With [offline support](/ui-kit/react-native/offline-support) running, hides the one-line offline notices: an unsent message was removed, the outbox is full, messages were not sent, and the cache was rebuilt or unsent messages were lost. The **Not sent** rows, the offline states and **Connect to load more** still show. Has no effect with offline support off. + +| | | +| --- | --- | +| Type | `boolean` | +| Default | `false` | + +--- + ### hideMessageInfoOption Hides the message info option. diff --git a/ui-kit/react-native/methods.mdx b/ui-kit/react-native/methods.mdx index 92fbe1d8c..8b1ee326b 100644 --- a/ui-kit/react-native/methods.mdx +++ b/ui-kit/react-native/methods.mdx @@ -11,6 +11,7 @@ description: "Use CometChat React Native UI Kit methods for initialization, logi | Package | `@cometchat/chat-uikit-react-native` | | Import | `import { CometChatUIKit, UIKitSettings } from "@cometchat/chat-uikit-react-native";` | | Init | `CometChatUIKit.init(UIKitSettings)` | +| Offline (optional) | `offline: { enabled: true }` in `UIKitSettings` — see [Offline Support](/ui-kit/react-native/offline-support) | | Login (dev) | `CometChatUIKit.login({ uid: "UID" })` | | Login (prod) | `CometChatUIKit.login({ authToken: "AUTH_TOKEN" })` | | Other methods | `CometChatUIKit.logout()`, `CometChatUIKit.createUser(user)`, `CometChatUIKit.updateUser(user)` | @@ -64,6 +65,35 @@ CometChatUIKit.init(uikitSettings) +#### Init with offline support + +Add the `offline` setting to keep chats and messages available without a connection and to queue messages sent while offline. It is off by default. It needs UI Kit 5.6.0 and Chat SDK 4.2.0 or later, with `@op-engineering/op-sqlite` installed in your app. See [Offline Support](/ui-kit/react-native/offline-support) for the requirements and the full behavior. + + + +```js +import { CometChatUIKit, UIKitSettings } from "@cometchat/chat-uikit-react-native"; + +const uikitSettings = new UIKitSettings({ + appId: "APP_ID", + region: "REGION", + authKey: "AUTH_KEY", + offline: { enabled: true }, // or `true`, or a CometChat.OfflineConfig +}); + +CometChatUIKit.init(uikitSettings) + .then(() => { + console.log("Initialization completed successfully"); + }) + .catch((error) => { + console.log("Initialization failed with exception:", error); + }); +``` + + + +The UI Kit hands `offline` to the Chat SDK. Offline support runs only after a user logs in; check `CometChat.isOfflineEnabled()` to see whether it is running. If you initialize with `CometChatUIKit.initFromSettings(settings, offline?)`, pass the same value as the second argument or set `chatSDK.offline` in the settings. + --- ### Login using Auth Key @@ -132,6 +162,10 @@ CometChatUIKit.logout(); + +With [offline support](/ui-kit/react-native/offline-support) running, logout also deletes the user's offline cache on the device: cached chats and messages, cached media and messages still waiting to be sent. The UI Kit clears its lists and composer trays. See [Logout and user switch](/ui-kit/react-native/offline-support#logout-and-user-switch). + + --- ### Create User @@ -196,6 +230,10 @@ CometChatUIKit.updateUser(user) ## Sending Messages + +With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). + + ### Text Message Sends a text message in a 1:1 or group chat. @@ -508,6 +546,7 @@ CometChatUIKit.sendCustomInteractiveMessage(customMessage) | `disableCalling` | `boolean` | Disable calling features | | `overrideAdminHost` | `string` | Used to set the admin host | | `overrideClientHost` | `string` | Used to set the client host | +| `offline` | `boolean \| UIKitOfflineSettings \| CometChat.OfflineConfig` | Turns on [offline support](/ui-kit/react-native/offline-support) (UI Kit 5.6.0 and Chat SDK 4.2.0 or later). Pass `true`, an options object with `enabled: true`, or a `CometChat.OfflineConfig`. Default: off. See [Init with offline support](#init-with-offline-support) | --- diff --git a/ui-kit/react-native/overview.mdx b/ui-kit/react-native/overview.mdx index 9f3722fd7..c9107b5c3 100644 --- a/ui-kit/react-native/overview.mdx +++ b/ui-kit/react-native/overview.mdx @@ -96,6 +96,9 @@ Pick your framework and follow the step-by-step integration guide: Initialize, authenticate, and send messages + + Saved chats without a connection and queued sends (opt-in) + Common issues and fixes diff --git a/ui-kit/react-native/react-native-cli-integration.mdx b/ui-kit/react-native/react-native-cli-integration.mdx index b61714ed3..8985f24ff 100644 --- a/ui-kit/react-native/react-native-cli-integration.mdx +++ b/ui-kit/react-native/react-native-cli-integration.mdx @@ -245,6 +245,10 @@ CometChatUIKit.init(uiKitSettings) + +**Optional: offline support.** To show saved chats without a connection and queue messages sent offline, add `offline: { enabled: true }` to `uiKitSettings`. It needs UI Kit 5.6.0 and Chat SDK 4.2.0 or later, the `@op-engineering/op-sqlite` native module in your app, and a native rebuild. See [Offline Support](/ui-kit/react-native/offline-support). + + --- ## Step 4 — Login diff --git a/ui-kit/react-native/threaded-messages-header.mdx b/ui-kit/react-native/threaded-messages-header.mdx index 90a54e77b..bd2850b1c 100644 --- a/ui-kit/react-native/threaded-messages-header.mdx +++ b/ui-kit/react-native/threaded-messages-header.mdx @@ -57,6 +57,10 @@ function ThreadHeaderDemo() { } ``` + +With [offline support](/ui-kit/react-native/offline-support) on, a reply the user sends without a connection is counted in the reply count once, when it is queued, and taken back if the reply is removed before it was sent. See [Message list and threads](/ui-kit/react-native/offline-support#message-list-and-threads). + + --- ## Styling From e2703e8faa795528b0da8394e403d0754f5f9a7e Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 17:37:40 +0530 Subject: [PATCH 05/13] docs(ENG-57592): tighten offline notices, discard and hideError details Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/message-list.mdx | 2 +- ui-kit/react-native/offline-support.mdx | 15 ++++++++++----- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/ui-kit/react-native/message-list.mdx b/ui-kit/react-native/message-list.mdx index f1a46e13c..9a3c20f29 100644 --- a/ui-kit/react-native/message-list.mdx +++ b/ui-kit/react-native/message-list.mdx @@ -1200,7 +1200,7 @@ Hides group action messages (join, leave, kick, etc.). ### hideOfflineNotices -With [offline support](/ui-kit/react-native/offline-support) running, hides the one-line offline notices: an unsent message was removed, the outbox is full, messages were not sent, and the cache was rebuilt or unsent messages were lost. The **Not sent** rows, the offline states and **Connect to load more** still show. Has no effect with offline support off. +With [offline support](/ui-kit/react-native/offline-support) running, hides all the one-line offline notices, such as an unsent message was removed, the outbox is full, a file is too large to send offline, **Sending… try again in a moment**, **Available when online**, and the cache was rebuilt or unsent messages were lost. The **Not sent** rows, the offline states and **Connect to load more** still show. Has no effect with offline support off. | | | | --- | --- | diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index 5ebb299fe..9851c253d 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -209,7 +209,7 @@ The same rule applies to [Conversations](/ui-kit/react-native/conversations), [U - **Saved rows show at once.** The server's page then merges into them in place, with no flicker or reload. - **Offline with rows on screen:** a load that fails because there is no connection leaves the rows on screen, with no error view. -- **Offline with nothing saved:** the list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, messages, reactions, notifications), with no Retry button. If you passed your own `ErrorView`, it shows instead. +- **Offline with nothing saved:** the list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, messages, reactions, notifications), with no Retry button. If you passed your own `ErrorView`, it shows instead. `hideError` hides it too. - **Online, the server returns nothing:** the empty view (yours, if you passed one). - **Online, a real error:** the error view with Retry when nothing is on screen, as before; rows already on screen stay. - **On reconnect:** rows update in place. A list reloads once by itself only if it was showing the offline state or an offline search. @@ -326,9 +326,10 @@ With offline support running, the promise returned by `CometChatUIKit.sendTextMe - **resolves** when the message reaches the server, also when it was queued first; - **rejects** on a final failure; - never rejects just because the message was queued; +- **rejects with the error code `DISCARDED`** when the SDK drops a queued message on its own (for example its conversation was purged, or the outbox overflowed) or the user deletes the unsent row; the error's `reason` says why; - **rejects once, quietly,** with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED` when the user logs out or switches user while the send is waiting, or when a cache reset loses the queued message. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. -If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` as "the send ended with the session", not as a failure to show the user. +If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` as "the send ended with the session", not as a failure to show the user. `DISCARDED` means the queued message is gone and was never sent. ```tsx import { CometChatUIKit } from "@cometchat/chat-uikit-react-native"; @@ -340,6 +341,10 @@ try { // The session ended before the message was sent. Nothing to show. return; } + if (error?.code === "DISCARDED") { + // The queued message was dropped and never sent. `error.reason` says why. + return; + } // A real failure. } ``` @@ -412,7 +417,7 @@ For the SDK's own listeners (sync progress, the outbox, cache resets), see [Stay ### Hide the offline notices -`CometChatMessageList` and `CometChatConversations` take `hideOfflineNotices` (default `false`). It hides the one-line notices: an unsent message removed, the outbox full, messages not sent, and the cache rebuilt or unsent messages lost. It has no effect with offline support off. The **Not sent** rows, the offline states and **Connect to load more** still show. +`CometChatMessageList` and `CometChatConversations` take `hideOfflineNotices` (default `false`). It hides all the one-line offline notices, such as an unsent message removed, the outbox full, a file too large to send offline, **Sending… try again in a moment**, **Available when online**, and the cache rebuilt or unsent messages lost. It has no effect with offline support off. The **Not sent** rows, the offline states and **Connect to load more** still show. ```tsx @@ -421,7 +426,7 @@ For the SDK's own listeners (sync progress, the outbox, cache resets), see [Stay ### Your own error and empty views -If you pass your own `ErrorView` to a list, it shows instead of the UI Kit's **Connect to load …** state. If you pass your own `EmptyView`, it shows instead of **Connect to search**. +If you pass your own `ErrorView` to a list, it shows instead of the UI Kit's **Connect to load …** state, and `hideError` hides that state. If you pass your own `EmptyView`, it shows instead of **Connect to search**. ### Style the offline states @@ -489,7 +494,7 @@ If you don't set `offline`, none of the behavior on this page runs: no offline s - **Reconnect catch-up pages forward.** A full page is followed by the next one instead of fetching the same page again. - **Lists reload with your current request builder on reconnect,** not the one from their first render. - **Download and Share copy a local file only from the Chat SDK's offline media folder.** When a message's attachment points to any other file on the device, nothing is copied (on Android the UI Kit shows **File download failed.**). -- **Automation identifiers:** the composer input has the `testID` `cc-composer-input` and the send button `CometChatComposer.send`. View-snapshot tests that include them may change. +- **Automation identifiers:** the composer input has the `testID` `cc-composer-input`. View-snapshot tests that include it may change. ## Limitations and Known Issues From ef3bb5cefe3e99abcca6227ba0ab2047d2284cba Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 17:51:23 +0530 Subject: [PATCH 06/13] docs(ENG-57592): scope hideError note and DISCARDED reason Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/methods.mdx | 2 +- ui-kit/react-native/offline-support.mdx | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/ui-kit/react-native/methods.mdx b/ui-kit/react-native/methods.mdx index 8b1ee326b..06801eaa9 100644 --- a/ui-kit/react-native/methods.mdx +++ b/ui-kit/react-native/methods.mdx @@ -231,7 +231,7 @@ CometChatUIKit.updateUser(user) ## Sending Messages -With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). +With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. A queued message that the SDK drops or the user deletes rejects with `DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). ### Text Message diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index 9851c253d..1dfd8177c 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -209,7 +209,7 @@ The same rule applies to [Conversations](/ui-kit/react-native/conversations), [U - **Saved rows show at once.** The server's page then merges into them in place, with no flicker or reload. - **Offline with rows on screen:** a load that fails because there is no connection leaves the rows on screen, with no error view. -- **Offline with nothing saved:** the list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, messages, reactions, notifications), with no Retry button. If you passed your own `ErrorView`, it shows instead. `hideError` hides it too. +- **Offline with nothing saved:** the list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, messages, reactions, notifications), with no Retry button. If you passed your own `ErrorView`, it shows instead. On lists that take `hideError` (Conversations, Users, Groups, Group Members, Message List), `hideError` hides it too. - **Online, the server returns nothing:** the empty view (yours, if you passed one). - **Online, a real error:** the error view with Retry when nothing is on screen, as before; rows already on screen stay. - **On reconnect:** rows update in place. A list reloads once by itself only if it was showing the offline state or an offline search. @@ -326,7 +326,7 @@ With offline support running, the promise returned by `CometChatUIKit.sendTextMe - **resolves** when the message reaches the server, also when it was queued first; - **rejects** on a final failure; - never rejects just because the message was queued; -- **rejects with the error code `DISCARDED`** when the SDK drops a queued message on its own (for example its conversation was purged, or the outbox overflowed) or the user deletes the unsent row; the error's `reason` says why; +- **rejects with the error code `DISCARDED`** when the SDK drops a queued message on its own (for example its conversation was purged, or the outbox overflowed) or the user deletes the unsent row; the error's `reason` is `DISCARDED` for a user delete, and the SDK's failure reason (for example `QUEUE_OVERFLOW`) for an SDK drop; - **rejects once, quietly,** with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED` when the user logs out or switches user while the send is waiting, or when a cache reset loses the queued message. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` as "the send ended with the session", not as a failure to show the user. `DISCARDED` means the queued message is gone and was never sent. @@ -426,7 +426,7 @@ For the SDK's own listeners (sync progress, the outbox, cache resets), see [Stay ### Your own error and empty views -If you pass your own `ErrorView` to a list, it shows instead of the UI Kit's **Connect to load …** state, and `hideError` hides that state. If you pass your own `EmptyView`, it shows instead of **Connect to search**. +If you pass your own `ErrorView` to a list, it shows instead of the UI Kit's **Connect to load …** state, and, on lists that take `hideError` (Conversations, Users, Groups, Group Members, Message List), `hideError` hides that state. If you pass your own `EmptyView`, it shows instead of **Connect to search**. ### Style the offline states From a2076ffccb865990337cc87eb27a48b04fe897a4 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 18:03:36 +0530 Subject: [PATCH 07/13] docs(ENG-57592): correct send promise rejection codes Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/methods.mdx | 2 +- ui-kit/react-native/offline-support.mdx | 17 +++++++---------- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/ui-kit/react-native/methods.mdx b/ui-kit/react-native/methods.mdx index 06801eaa9..6b128490b 100644 --- a/ui-kit/react-native/methods.mdx +++ b/ui-kit/react-native/methods.mdx @@ -231,7 +231,7 @@ CometChatUIKit.updateUser(user) ## Sending Messages -With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. A queued message that the SDK drops or the user deletes rejects with `DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). +With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. A queued message the user deletes rejects with `DISCARDED`, and one whose conversation was removed rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). ### Text Message diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index 1dfd8177c..cae8b21e8 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -324,12 +324,12 @@ The reactions list, Pinned and Saved have no `onError` prop, so they show the st With offline support running, the promise returned by `CometChatUIKit.sendTextMessage`, `sendMediaMessage` and `sendCustomMessage`: - **resolves** when the message reaches the server, also when it was queued first; -- **rejects** on a final failure; +- **rejects** on a final failure, with the SDK's error as it is: `error.code`, and `error.reason` with the failure reason when there is one. For example, a message evicted because the outbox overflowed rejects with `ERROR_PENDING_QUEUE_LIMIT` and the reason `QUEUE_OVERFLOW`; - never rejects just because the message was queued; -- **rejects with the error code `DISCARDED`** when the SDK drops a queued message on its own (for example its conversation was purged, or the outbox overflowed) or the user deletes the unsent row; the error's `reason` is `DISCARDED` for a user delete, and the SDK's failure reason (for example `QUEUE_OVERFLOW`) for an SDK drop; -- **rejects once, quietly,** with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED` when the user logs out or switches user while the send is waiting, or when a cache reset loses the queued message. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. +- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting, when a cache reset loses the queued message, or when the message's conversation was removed from the device. For a session end or a cache reset there is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable; +- **rejects with the error code `DISCARDED`** when the user deletes the unsent row; the error's `reason` is `DISCARDED`. -If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` as "the send ended with the session", not as a failure to show the user. `DISCARDED` means the queued message is gone and was never sent. +If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` and `DISCARDED` as "the message was never sent and there is nothing to show", not as a failure to show the user. Any other code is a real failure. ```tsx import { CometChatUIKit } from "@cometchat/chat-uikit-react-native"; @@ -337,12 +337,9 @@ import { CometChatUIKit } from "@cometchat/chat-uikit-react-native"; try { await CometChatUIKit.sendTextMessage(textMessage); } catch (error: any) { - if (error?.code === "ERROR_OFFLINE_MESSAGE_DISCARDED") { - // The session ended before the message was sent. Nothing to show. - return; - } - if (error?.code === "DISCARDED") { - // The queued message was dropped and never sent. `error.reason` says why. + if (error?.code === "ERROR_OFFLINE_MESSAGE_DISCARDED" || error?.code === "DISCARDED") { + // The message was never sent (session ended, cache reset, conversation removed, or the user + // deleted it). Nothing to show. return; } // A real failure. From 8bd0e5121983f97c4b66ace9e723d991c85403af Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 18:12:52 +0530 Subject: [PATCH 08/13] docs(ENG-57592): describe cache reset outcome of queued sends Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/offline-support.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index cae8b21e8..8d25faf1b 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -274,7 +274,7 @@ If the user was kicked, banned or removed from a group while the device was offl ### Logout and user switch -The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray. On logout and a user switch, the SDK also deletes that user's cached data, cached media and queued messages. Restarting the app while the same user stays logged in keeps the cache. You don't need to clear anything yourself. A `CometChatUIKit.send*` call still waiting at that moment is settled quietly; see [Errors and Callbacks](#errors-and-callbacks). See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). +The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray. On logout and a user switch, the SDK also deletes that user's cached data, cached media and queued messages. Restarting the app while the same user stays logged in keeps the cache. You don't need to clear anything yourself. A `CometChatUIKit.send*` call still waiting at that moment is rejected with `ERROR_OFFLINE_MESSAGE_DISCARDED`; see [Errors and Callbacks](#errors-and-callbacks) and [`CometChatUIKit.send*` promises](#cometchatuikitsend-promises). See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). ## Offline States and Texts @@ -326,7 +326,7 @@ With offline support running, the promise returned by `CometChatUIKit.sendTextMe - **resolves** when the message reaches the server, also when it was queued first; - **rejects** on a final failure, with the SDK's error as it is: `error.code`, and `error.reason` with the failure reason when there is one. For example, a message evicted because the outbox overflowed rejects with `ERROR_PENDING_QUEUE_LIMIT` and the reason `QUEUE_OVERFLOW`; - never rejects just because the message was queued; -- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting, when a cache reset loses the queued message, or when the message's conversation was removed from the device. For a session end or a cache reset there is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable; +- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting, when a cache reset loses the queued message, or when the message's conversation was removed from the device. For a session end there is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. For a cache reset, the UI Kit first handles the lost message like an unsent message that was removed: the row goes, `ccMessageSent` fires with the `error` status, `ccMessageSendStateChanged` fires with `"discarded"` and the "unsent message was removed" notice shows. The reset then adds its own notice, except for `ENCRYPTION_CHANGED`. `onError` is not called in either case; - **rejects with the error code `DISCARDED`** when the user deletes the unsent row; the error's `reason` is `DISCARDED`. If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` and `DISCARDED` as "the message was never sent and there is nothing to show", not as a failure to show the user. Any other code is a real failure. From abf290599897f358c0b4ea49d8d30eac235348f8 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 18:22:50 +0530 Subject: [PATCH 09/13] docs(ENG-57592): fix send promise rejection codes for dropped queued messages Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/methods.mdx | 2 +- ui-kit/react-native/offline-support.mdx | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/ui-kit/react-native/methods.mdx b/ui-kit/react-native/methods.mdx index 6b128490b..abde220f0 100644 --- a/ui-kit/react-native/methods.mdx +++ b/ui-kit/react-native/methods.mdx @@ -231,7 +231,7 @@ CometChatUIKit.updateUser(user) ## Sending Messages -With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. A queued message the user deletes rejects with `DISCARDED`, and one whose conversation was removed rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). +With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. A queued message that is later dropped (deleted by the user, evicted by an outbox overflow, removed with its conversation or lost in a cache reset) rejects with `DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). ### Text Message diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index 8d25faf1b..da309f317 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -274,7 +274,7 @@ If the user was kicked, banned or removed from a group while the device was offl ### Logout and user switch -The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray. On logout and a user switch, the SDK also deletes that user's cached data, cached media and queued messages. Restarting the app while the same user stays logged in keeps the cache. You don't need to clear anything yourself. A `CometChatUIKit.send*` call still waiting at that moment is rejected with `ERROR_OFFLINE_MESSAGE_DISCARDED`; see [Errors and Callbacks](#errors-and-callbacks) and [`CometChatUIKit.send*` promises](#cometchatuikitsend-promises). See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). +The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray. On logout and a user switch, the SDK also deletes that user's cached data, cached media and queued messages. Restarting the app while the same user stays logged in keeps the cache. You don't need to clear anything yourself. On logout and a user switch, a `CometChatUIKit.send*` call still waiting is rejected quietly with `ERROR_OFFLINE_MESSAGE_DISCARDED`; for a cache reset, see [`CometChatUIKit.send*` promises](#cometchatuikitsend-promises). See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). ## Offline States and Texts @@ -324,10 +324,10 @@ The reactions list, Pinned and Saved have no `onError` prop, so they show the st With offline support running, the promise returned by `CometChatUIKit.sendTextMessage`, `sendMediaMessage` and `sendCustomMessage`: - **resolves** when the message reaches the server, also when it was queued first; -- **rejects** on a final failure, with the SDK's error as it is: `error.code`, and `error.reason` with the failure reason when there is one. For example, a message evicted because the outbox overflowed rejects with `ERROR_PENDING_QUEUE_LIMIT` and the reason `QUEUE_OVERFLOW`; +- **rejects** on a final failure, with the SDK's error as it is: `error.code`, and `error.reason` with the failure reason when there is one. For example, a message refused because the outbox is full rejects with `ERROR_PENDING_QUEUE_LIMIT` and the reason `QUEUE_FULL`; - never rejects just because the message was queued; -- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting, when a cache reset loses the queued message, or when the message's conversation was removed from the device. For a session end there is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. For a cache reset, the UI Kit first handles the lost message like an unsent message that was removed: the row goes, `ccMessageSent` fires with the `error` status, `ccMessageSendStateChanged` fires with `"discarded"` and the "unsent message was removed" notice shows. The reset then adds its own notice, except for `ENCRYPTION_CHANGED`. `onError` is not called in either case; -- **rejects with the error code `DISCARDED`** when the user deletes the unsent row; the error's `reason` is `DISCARDED`. +- **rejects with the error code `DISCARDED`** when a message that was already queued is dropped: the user deletes the unsent row, an outbox overflow evicts it, its conversation is removed from the device, or a cache reset loses it. The error's `reason` is `QUEUE_OVERFLOW` for an eviction and `DISCARDED` otherwise. For the cases the SDK drives (eviction, conversation removal, cache reset), the UI Kit also handles the message like an unsent message that was removed: the row goes, `ccMessageSent` fires with the `error` status, `ccMessageSendStateChanged` fires with `"discarded"` and the "unsent message was removed" notice shows. A cache reset then adds its own notice when it lost messages, except for `ENCRYPTION_CHANGED`. `onError` is not called; +- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. A cache reset that hits a send the SDK had not queued yet gives the same code. If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` and `DISCARDED` as "the message was never sent and there is nothing to show", not as a failure to show the user. Any other code is a real failure. @@ -338,8 +338,7 @@ try { await CometChatUIKit.sendTextMessage(textMessage); } catch (error: any) { if (error?.code === "ERROR_OFFLINE_MESSAGE_DISCARDED" || error?.code === "DISCARDED") { - // The message was never sent (session ended, cache reset, conversation removed, or the user - // deleted it). Nothing to show. + // The message was never sent (logged out, switched user, or a queued message was dropped). Nothing to show. return; } // A real failure. From 69c504b3834d81459d493050f93aade805d9dfe2 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 18:33:16 +0530 Subject: [PATCH 10/13] docs(ENG-57592): qualify reset and onError notes for send promises Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/methods.mdx | 2 +- ui-kit/react-native/offline-support.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ui-kit/react-native/methods.mdx b/ui-kit/react-native/methods.mdx index abde220f0..ac82f8524 100644 --- a/ui-kit/react-native/methods.mdx +++ b/ui-kit/react-native/methods.mdx @@ -231,7 +231,7 @@ CometChatUIKit.updateUser(user) ## Sending Messages -With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. A queued message that is later dropped (deleted by the user, evicted by an outbox overflow, removed with its conversation or lost in a cache reset) rejects with `DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). +With [offline support](/ui-kit/react-native/offline-support) running, a message sent without a connection is queued on the device and sent when the connection returns. The promise returned by `sendTextMessage`, `sendMediaMessage` and `sendCustomMessage` resolves when the message reaches the server, also after it was queued, and never rejects just because the message was queued. If the user logs out or switches user before a queued message is sent, it rejects once with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. A queued message that is later dropped (deleted by the user, evicted by an outbox overflow, removed with its conversation or lost in a cache reset the SDK can count) rejects with `DISCARDED`. See [Errors and Callbacks](/ui-kit/react-native/offline-support#errors-and-callbacks). ### Text Message diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index da309f317..958ceb10a 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -326,8 +326,8 @@ With offline support running, the promise returned by `CometChatUIKit.sendTextMe - **resolves** when the message reaches the server, also when it was queued first; - **rejects** on a final failure, with the SDK's error as it is: `error.code`, and `error.reason` with the failure reason when there is one. For example, a message refused because the outbox is full rejects with `ERROR_PENDING_QUEUE_LIMIT` and the reason `QUEUE_FULL`; - never rejects just because the message was queued; -- **rejects with the error code `DISCARDED`** when a message that was already queued is dropped: the user deletes the unsent row, an outbox overflow evicts it, its conversation is removed from the device, or a cache reset loses it. The error's `reason` is `QUEUE_OVERFLOW` for an eviction and `DISCARDED` otherwise. For the cases the SDK drives (eviction, conversation removal, cache reset), the UI Kit also handles the message like an unsent message that was removed: the row goes, `ccMessageSent` fires with the `error` status, `ccMessageSendStateChanged` fires with `"discarded"` and the "unsent message was removed" notice shows. A cache reset then adds its own notice when it lost messages, except for `ENCRYPTION_CHANGED`. `onError` is not called; -- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. A cache reset that hits a send the SDK had not queued yet gives the same code. +- **rejects with the error code `DISCARDED`** when a message that was already queued is dropped: the user deletes the unsent row, an outbox overflow evicts it, its conversation is removed from the device, or a cache reset the SDK can count loses it. The error's `reason` is `QUEUE_OVERFLOW` for an eviction and `DISCARDED` otherwise. For the cases the SDK drives (eviction, conversation removal, cache reset), the UI Kit also handles the message like an unsent message that was removed: the row goes, `ccMessageSent` fires with the `error` status, `ccMessageSendStateChanged` fires with `"discarded"` and the "unsent message was removed" notice shows. A cache reset then adds its own notice when it lost messages, except for `ENCRYPTION_CHANGED`. The composer's `onError` is not called for a removed conversation, a cache reset or a user delete; for an eviction it receives the SDK's `ERROR_PENDING_QUEUE_LIMIT` error; +- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. A cache reset whose lost messages the SDK cannot count (for example when the encryption key was lost) also rejects a waiting queued send with this code, quietly: the only thing shown is the reset's "Some unsent messages may not have been sent" notice. If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` and `DISCARDED` as "the message was never sent and there is nothing to show", not as a failure to show the user. Any other code is a real failure. From 7db996e63472f4fbbe3cf9da074b37fff568b0c6 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 18:41:18 +0530 Subject: [PATCH 11/13] docs(ENG-57592): note no notice for an encryption-change reset Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index 958ceb10a..07443ece0 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -327,7 +327,7 @@ With offline support running, the promise returned by `CometChatUIKit.sendTextMe - **rejects** on a final failure, with the SDK's error as it is: `error.code`, and `error.reason` with the failure reason when there is one. For example, a message refused because the outbox is full rejects with `ERROR_PENDING_QUEUE_LIMIT` and the reason `QUEUE_FULL`; - never rejects just because the message was queued; - **rejects with the error code `DISCARDED`** when a message that was already queued is dropped: the user deletes the unsent row, an outbox overflow evicts it, its conversation is removed from the device, or a cache reset the SDK can count loses it. The error's `reason` is `QUEUE_OVERFLOW` for an eviction and `DISCARDED` otherwise. For the cases the SDK drives (eviction, conversation removal, cache reset), the UI Kit also handles the message like an unsent message that was removed: the row goes, `ccMessageSent` fires with the `error` status, `ccMessageSendStateChanged` fires with `"discarded"` and the "unsent message was removed" notice shows. A cache reset then adds its own notice when it lost messages, except for `ENCRYPTION_CHANGED`. The composer's `onError` is not called for a removed conversation, a cache reset or a user delete; for an eviction it receives the SDK's `ERROR_PENDING_QUEUE_LIMIT` error; -- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. A cache reset whose lost messages the SDK cannot count (for example when the encryption key was lost) also rejects a waiting queued send with this code, quietly: the only thing shown is the reset's "Some unsent messages may not have been sent" notice. +- **rejects with `ERROR_OFFLINE_MESSAGE_DISCARDED`** when the user logs out or switches user while the send is waiting. There is no failed row, no notice, no `ccMessageSent` error event and no `onError`, and the composer stays usable. A cache reset whose lost messages the SDK cannot count (for example when the encryption key was lost) also rejects a waiting queued send with this code, quietly: the only thing shown is the reset's "Some unsent messages may not have been sent" notice, except for an `ENCRYPTION_CHANGED` reset, which shows no notice at all. If your code awaits these methods, treat `ERROR_OFFLINE_MESSAGE_DISCARDED` and `DISCARDED` as "the message was never sent and there is nothing to show", not as a failure to show the user. Any other code is a real failure. From b9933f132f081281cdf609e76cfe5b834db0c614 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 19:03:01 +0530 Subject: [PATCH 12/13] docs(ENG-57592): don't promise queueing for files picked offline Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index 07443ece0..963c33c14 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -244,7 +244,7 @@ On the [Search](/ui-kit/react-native/search) screen, with nothing saved, **Conne ### Attachments and media - Attachments staged in the composer tray (both the [Message Composer](/ui-kit/react-native/message-composer) and the [Compact Message Composer](/ui-kit/react-native/compact-message-composer)) survive leaving the chat and an app restart. Files that finished uploading stay done; interrupted files come back failed with a retry button. Nothing uploads by itself. -- A file picked in the tray uploads right away, which needs a connection. Picked while offline, its upload fails and the tile shows a retry button; the file is not queued and nothing is sent. Retry it once the connection returns, then send. A voice note, and a file sent with `enableMultipleAttachments={false}`, go out as a message straight away, so the SDK queues them like any other message (see [Send While Offline](/sdk/react-native/offline-send)). +- A file picked in the tray uploads right away, which needs a connection. Picked while offline, its upload fails and the tile shows a retry button; the file is not queued and nothing is sent. Retry it once the connection returns, then send. A voice note goes out as a message straight away, so the SDK queues it like any other message (see [Send While Offline](/sdk/react-native/offline-send)). - Images, videos, audio and files come from the SDK's saved copy when it has one, with `mediaCaching` set to `AUTO` (the default). See [Media Caching](/sdk/react-native/offline-media-caching). - Media the device never downloaded shows **Available when online** while offline. Tapping it online asks the SDK to download and save it. - Download, "Download all" and Share in the media viewer use the saved file when there is one, without fetching it again. Offline with no saved copy, they show **Available when online**. From 66bc2d396179864e3e4a9483ef868d2a083d378e Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 19:26:50 +0530 Subject: [PATCH 13/13] docs(ENG-57592): fix the send promises anchor link Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/react-native/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ui-kit/react-native/offline-support.mdx b/ui-kit/react-native/offline-support.mdx index 963c33c14..292bae4f7 100644 --- a/ui-kit/react-native/offline-support.mdx +++ b/ui-kit/react-native/offline-support.mdx @@ -274,7 +274,7 @@ If the user was kicked, banned or removed from a group while the device was offl ### Logout and user switch -The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray. On logout and a user switch, the SDK also deletes that user's cached data, cached media and queued messages. Restarting the app while the same user stays logged in keeps the cache. You don't need to clear anything yourself. On logout and a user switch, a `CometChatUIKit.send*` call still waiting is rejected quietly with `ERROR_OFFLINE_MESSAGE_DISCARDED`; for a cache reset, see [`CometChatUIKit.send*` promises](#cometchatuikitsend-promises). See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). +The SDK keeps one cache per user. On logout, a user switch or a cache reset, the UI Kit clears every list and composer tray. On logout and a user switch, the SDK also deletes that user's cached data, cached media and queued messages. Restarting the app while the same user stays logged in keeps the cache. You don't need to clear anything yourself. On logout and a user switch, a `CometChatUIKit.send*` call still waiting is rejected quietly with `ERROR_OFFLINE_MESSAGE_DISCARDED`; for a cache reset, see [`CometChatUIKit.send*` promises](#cometchatuikit-send-promises). See [One cache per user](/sdk/react-native/offline-overview#one-cache-per-user). ## Offline States and Texts