[adityagokula2210]

Summary

Public docs for offline support in the Android SDK v5.1.0 (SDK only, no UI Kit). Draft for review; the 5.1.0 changelog entry is still to come.

New: Offline Support group (SDKs → Android → v5, after Messaging), 8 pages:

• offline-overview: what it does and how the cached-then-server flow works
• offline-enable: OfflineConfig setup and options
• offline-cached-data: two-phase listeners (onCached… → onServer… → onError) for every list and single-item fetch, plus which filters are server-only
• offline-send: MessageSentListener (onMessagePending → onMessageSent), the outbox, and failure/retry behaviour
• offline-sync: catching up on reconnect
• offline-media-caching: media cache modes and limits
• offline-encryption: an encrypted local store
• offline-reference: config, callbacks, error codes, and old→new overload mapping

Updated: 24 existing v5 pages. These now use the two-phase listeners and MessageSentListener in Java and Kotlin. Each page carries one "deprecated from 5.1.0" callout (two shared snippets in snippets/sdk/), and the affected pages get an Offline Behaviour table and notes on server-only filters.

Also: the nav entry in docs.json and the pages listed in sdk/android/v5/llms-android-v5.mdx.

Review notes

• Source of truth: the SDK release-v5-v5.1.0 branch. Every cached vs server-only claim and every callback name was checked against that code.
• v4 pages are not touched: that's everything directly under sdk/android/.
• Local preview needs a workaround: six React UI Kit pages on main have an unescaped <21 (e.g. react >=18 <21), which breaks mint dev / mint broken-links locally. Skipping them in .mintignore works; that change is not in this PR.

How to review

Open the Mintlify preview from the checks below, start at Android → v5 → Offline Support → Overview, then spot-check the changed Messaging, Conversations, Users and Groups pages.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Nov 2, 2026, 12:10 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[ketanyekale]

Thanks for this — the structure is genuinely good, and the mechanical side is clean (details at the bottom). The issues below are all content-consistency ones, and four of them would change what an integrator builds, so I'd like them settled before this merges.

Blocking

1. onMessagePending is documented as unconditional in 36 places, contradicting the page that defines it.

36 code comments across three pages say it fires on every send:

• sdk/android/v5/send-message.mdx:119 and 31 more in that file, ai-moderation.mdx:88, :113, upload-files.mdx:432, :494:
  // Fires on every send while offline support is enabled; message.getStatus() == MessageStatus.PENDING

But offline-send.mdx says it does not:

• :53 — "If the message cannot be queued at all, for example because its media could not be copied (code ERROR_OFFLINE_MEDIA_COPY_FAILED, reason PERMANENT), only onError fires."
• :355 — "A refused send (QUEUE_FULL / BYTE_OVERFLOW) is never queued, so it fires no onMessagePending".

send-message.mdx is the page most readers land on. Someone who builds their optimistic-UI row in onMessagePending and treats it as the guaranteed first event will silently drop refused and un-copyable-media sends — the row never appears and the only signal is onError. This is the most-replicated wrong statement in the PR.

2. Three mutually incompatible Kotlin signatures for the same callback.

onCachedMessages / onServerMessages appear in three Kotlin forms; at most one compiles:

• messages: List<BaseMessage> — 9 occurrences, e.g. offline-cached-data.mdx:103, save-message.mdx, pin-message.mdx
• messages: List<BaseMessage?> — 8 occurrences, all in receive-messages.mdx (:281, :285, :366, :370, :452, :456, :526, :530, …)
• messages: List<BaseMessage?>? — threaded-messages.mdx:200, :204, :260, :264

offline-reference.mdx:102 declares only onCachedMessages(List<BaseMessage>), and every Java tab on these same pages uses the non-null form — so this is also a Java/Kotlin parity break within receive-messages.mdx and threaded-messages.mdx. A Kotlin reader copying from either gets "nothing overrides" / type-mismatch errors with no way to tell which form is right.

3. retryAllFailedMessages scope is stated two ways.

• offline-reference.mdx:69 — "Retry every failed message in the outbox."
• offline-send.mdx:288 — "retries transient failures only; permanent ones are skipped." (same at :28)

A reader who builds a "Retry all" button from the reference expects every FAILED row to clear. PERMANENT ones stay stuck with no callback explaining why, and the only documented way out is discardLocalMessage per id.

4. The per-builder filter matrix the cached-data page promises isn't on the reference page.

• offline-cached-data.mdx:337 — "The full per-builder matrix of what the cache answers lives in the [Offline Configuration & API Reference]"
• offline-cached-data.mdx:240 — "per-builder details live on each request's own page and in the [Offline Configuration & API Reference]"

offline-reference.mdx has no such matrix (zero hits for searchKeyword or "Server only"). The matrices this PR adds actually live on the individual request pages — retrieve-conversations.mdx, retrieve-users.mdx:558, retrieve-group-members.mdx:199, thread-subscription.mdx, mentions.mdx. So :337 raises exactly the right alarm ("one innocuous builder flag can silently disable the cached phase for a whole screen") and then sends the reader to a page that can't answer it. Either add the matrix to the reference or point at the per-request pages.

Worth fixing in the same pass

5. autoSendPendingOnReconnect(false) — queued-then-failed, or failed immediately?

• offline-reference.mdx:49 — "Gates only the outbox flush"
• offline-send.mdx:340 — "a send that gets no answer becomes FAILED (TRANSIENT)" (so it was queued)
• offline-send.mdx:136 — "an offline send becomes FAILED (TRANSIENT) right away" (so it never was)

This decides whether the reader's outbox UI needs a queued state at all.

6. Wrong recovery API named for queued messages. offline-sync.mdx:188 says forceSyncNow "does not send queued messages (use retryMessage or retryAllFailedMessages for those)". But per offline-send.mdx:288 retryAllFailedMessages acts on FAILED only — it does nothing for the PENDING messages that sentence is about. Only retryMessage applies.

7. Listener type qualification is inconsistent, so imports can't be derived. MessageFetchListener, MessageSentListener, SyncListener and OfflineMessageListener are always shown nested (CometChat.SyncListener, offline-sync.mdx:65), but OfflineCacheResetListener (offline-sync.mdx:271, :283, offline-encryption.mdx:156), MediaCallbackListener and MediaDownloadListener (offline-media-caching.mdx:157, :177, :210) are top-level. The Kotlin forms also disagree on kind: object : OfflineCacheResetListener() vs object : MediaCallbackListener {. The registration table at offline-reference.mdx:84-92 doesn't disambiguate.

8. getPendingMessages return type stated two ways. offline-reference.mdx:28 annotates it // List<BaseMessage>; the table at :67 correctly says void, delivering via CallbackListener. Minor, but it's in the block that gets copied.

9. onError nullability differs. offline-send.mdx:98 uses onError(e: CometChatException?); send-message.mdx:152 and ai-moderation.mdx:99 use non-null onError(e: CometChatException). One won't compile.

Nit. offline-send.mdx:143 "Offer the user a manual retry (see below)" sits ~140 lines above "Retry and Discard" — a named link would resolve it.

What I checked that's clean

• Build safety: 0 unresolved nav refs; Mintlify Deployment and link-rot both pass.
• Redirects: purely additive (0 removed, 0 renamed), so the +0 redirect delta is correct, not an omission.
• Links: 0 broken internal links across 72 scanned files, and none pre-existing in sdk/android/v5/.
• Snippet variables: all 26 <OfflineDeprecated*> call sites pass method=, and every Listener site passes replacement= — nothing renders a literal {method}.
• Numeric defaults and limits: every figure agrees across pages — 100 conversations / 500 messages per conversation / 250 MB / 500 MB media / 50 pending / 5 reconnect attempts / 1000-change sync page / SQLCipher 4.13.0 / minSdk 21.
• Enums and error codes: MessageStatus, MessageFailureReason, OfflineCacheResetReason, SyncOutcome, PendingMessageOverflowPolicy, UploadFileItemStatus.State all agree between offline-reference.mdx:126-138 and the guides.
• Listener-to-request pairing: all 11 two-phase listeners pair with the right request type and callback names on every modified page.
• Version pins: consistent at 5.1.0 throughout. No images in the new pages, so no stale screenshots.
• Cross-checked against #593: all 15 OfflineConfig options match the Flutter PR field-for-field with identical defaults and correct per-platform casing (REJECT_NEWEST/rejectNewest, AUTO/auto). That part is carefully done.

One cross-PR discrepancy: the media re-sign path lists HTTP 401, 403 or 410 here (offline-media-caching.mdx:152) but only 403 or 410 in #593 (sdk/flutter/offline-media-caching.mdx:107). Real platform difference, or is one incomplete?

Scope of this review

I could not verify API names, signatures or defaults against SDK source — the release-v5-v5.1.0 branch this PR cites isn't in the public cometchat/chat-sdk-android repo (that repo holds maven artifacts only). Everything above is internal-consistency and reader-experience review. Someone with access to the release branch should still confirm the callback names and the List<BaseMessage> nullability independently.

Not merging, per your note that 5.1.0 isn't published yet — the install steps correctly pin 5.1.0 everywhere, which is exactly why this has to wait for the release.

[adityagokula2210]

Thanks for the thorough review, Ketan. I checked every point against the SDK's 5.1.0 release branch and pushed the fixes in 681e853.

Fixed

1. onMessagePending: you're right. Refused sends and media-copy failures get only onError. All 36 comments now say "Fires once the message is queued…".
2. Kotlin onCachedMessages / onServerMessages now use List<BaseMessage> everywhere, matching Java and the reference. The Java parameters have no nullability annotations, so all three forms did compile, but one form is clearer.
3. retryAllFailedMessages: the reference now says it retries transient failures only and permanent ones are skipped (discard them with discardLocalMessage).
4. The cached-data page now links to the Offline Behaviour table on each request's own page instead of a matrix on the reference page.
5. autoSendPendingOnReconnect(false): the send is queued first (onMessagePending fires), then the immediate attempt fails TRANSIENT. offline-send now says that. The reference line was already correct.
6. forceSyncNow now points only to retryMessage for queued messages.
7. Listener types: the snippets match the SDK, so they stay as they are. OfflineCacheResetListener is a top-level abstract class, and the media listeners are top-level interfaces. The reference now has a note giving each listener's kind and package.
8. The getPendingMessages comment now says it returns void and delivers the list to the listener.
9. Kotlin onError is non-null on every changed page. Both forms compiled, so this is only for consistency.

• Nit: "see below" is now a link to Retry and Discard.

Media re-sign (401 vs 403/410): Android does re-sign on 401, 403 and 410, so this page is right. The Flutter page correctly describes what the Flutter SDK does today. The gap is in the Flutter SDK, not in the docs, and we'll handle it on the SDK side.

Please keep this unmerged until 5.1.0 is published.

[ketanyekale]

Approving. I re-checked every point against 681e853c rather than taking the summary on trust, and all ten are genuinely fixed.

Verified fixed

1. onMessagePending — all 36 comments now read "Fires once the message is queued…" (32 in send-message.mdx, 2 in ai-moderation.mdx, 2 in upload-files.mdx). No "on every send" remains anywhere, so the page most readers land on no longer contradicts offline-send.mdx:53/:355.
2. Kotlin signatures — collapsed to a single form: 19 × messages: List<BaseMessage>, matching the 18 Java tabs and the reference row at offline-reference.mdx:102. The nullable-element and nullable-list variants are gone.
3. retryAllFailedMessages — offline-reference.mdx:69 now reads "Retry the failed messages whose failure was transient; permanent failures are skipped — discard them with discardLocalMessage", which agrees with offline-send.mdx:288 and also answers the "how do I clear a PERMANENT one" gap.
4. Filter matrix — both pointers fixed, not just the one I quoted. :240 and :337 now link to the per-request Offline Behaviour tables by name.
5. autoSendPendingOnReconnect(false) — :136 and :340 now tell the same story (queued first, onMessagePending fires, then the immediate attempt fails TRANSIENT), and offline-reference.mdx:49 is consistent with it.
6. forceSyncNow — offline-sync.mdx:188 now names only retryMessage for queued messages.
7. Listener qualification — offline-reference.mdx:95 now states the kind and package of each: nested abstract classes on CometChat, OfflineCacheResetListener as a top-level abstract class in com.cometchat.chat.core, the media listeners as top-level interfaces in com.cometchat.chat.models. That resolves the imports question without churning the snippets.
8. getPendingMessages — :28 and :67 both say void, delivering to the listener.
9. onError nullability — non-null on every page this PR changes. The two remaining nullable forms are in flag-message.mdx, which this PR doesn't touch, so they're out of scope here.
10. Nit — "see below" is now [Retry and Discard](#retry-and-discard), and that anchor resolves to the ## Retry and Discard heading at :283.

Re-ran the mechanical checks after the fixes, since the change added a lot of new cross-links: 0 unresolved navigation refs, 0 broken internal links across 72 scanned files, 0 pre-existing broken links in sdk/android/v5/, still purely additive so no redirects needed, and both new anchors resolve. Mintlify Deployment and link-rot remain green.

On the 401/403/410 difference — thanks for running that down. Taking your answer that Android re-signs on all three and the Flutter page describes current Flutter behaviour, this page is correct and the divergence belongs in the Flutter SDK. Nothing to change here.

Scope of this review, unchanged: this covers docs integrity and internal consistency, not the documented API surface against SDK source — the release-v5-v5.1.0 branch isn't in the public cometchat/chat-sdk-android repo, and nothing was built or run. Your check against the release branch is what that rests on.

Not merging — holding until 5.1.0 is published, as you asked.

[jitvarpatil]

🤖 Review Buddy (review-docs-pr)

Recommendation: request changes. Automated review; the final decision stays with a maintainer.

TL;DR: The docs are structurally safe, and the API reference matches the SDK source. The one blocker is timing: this PR must not merge until 5.1.0 is published, because the main install snippets pin a version that can't be downloaded yet. No content edit is needed for that. The P2s are small wording gaps and shouldn't hold the release.

Reviewed at 681e853c. This adds what the earlier reviews couldn't check: the documented API compared with the SDK's release-v5-v5.1.0 branch (5da06754).

P1: should fix before merge

• The install snippets point to an unpublished version: sdk/android/v5/setup.mdx:50, sdk/android/v5/overview.mdx:70, sdk/android/v5/upgrading-from-v4.mdx:15 and sdk/android/v5/offline-enable.mdx:42,47. The 5.1.0 AAR returns 404 on the documented Maven repo, while 5.0.7 is served and is still the latest GitHub release. If this merges first, new integrators following Setup get a dependency resolution failure. The author and Ketan have already agreed to hold, so this finding just records that as a merge condition. Re-check that the artifact resolves before merging.

P2: nits and wording

• sdk/android/v5/offline-reference.mdx:177: "The old overloads keep working: ... the server result arrives in the onServer… / onMessageSent callback instead of onSuccess" describes the new listeners, not the old overloads. Deprecated overloads still receive onSuccess. Read literally, this tells people they have to migrate their callbacks anyway.
• sdk/android/v5/offline-reference.mdx:166-167: the error table is incomplete.
  • ERROR_PENDING_QUEUE_LIMIT lists only refused sends, but DROP_OLDEST eviction also raises it with QUEUE_OVERFLOW (offline-send.mdx:351, Outbox.java:818).
  • ERROR_OFFLINE_MESSAGE_PERSIST_FAILED omits the send path. A send that can't be saved fails with this code and reason PERMANENT (Outbox.java:531).
• sdk/android/v5/offline-send.mdx:143: the table says to offer a manual retry for any FAILED message. But :192 says retry won't help for PERMANENT, and :359 says refused or evicted messages fail with ERROR_OFFLINE_MESSAGE_NOT_FOUND. It should tell readers to check getFailureReason() first.
• sdk/android/v5/offline-media-caching.mdx:59: "Sending media always works in both modes" conflicts with the BYTE_OVERFLOW refusal at offline-send.mdx:353. Something like "Both modes support sending media" would avoid the absolute.
• sdk/android/v5/offline-reference.mdx:35: the page calls itself "the full surface", but it leaves out MessageSource / getSource(), which offline-sync.mdx:151 uses, and the debugTracing(boolean) builder option. Add them, or soften the claim if debugTracing is meant to stay undocumented.
• sdk/android/v5/offline-encryption.mdx:46: this doesn't mention that adding SQLCipher pulls in androidx.sqlite:sqlite:2.2.0, which requires compileSdk 31 or higher according to the SDK's build.gradle comments. Apps on a lower compileSdk would hit a build error with no hint in the docs. I took this from those comments and didn't reproduce it.
• offline-send.mdx (7 places) and offline-enable.mdx (1 place): Kotlin samples declare e: CometChatException as non-null and then use e?.code / e?.message. This compiles with a warning. offline-cached-data.mdx already uses e.code.

What passed

• Build and links: 0 unresolved navigation refs, 0 orphans, 0 removed or renamed URLs (redirects unchanged at 926), and no new images. Mintlify Deployment and link-rot checks are green.
• Broken links: none in sdk/android/v5/. The analyzer found two in v4 pages this PR doesn't change: sdk/android/upgrading-from-v3-guide.mdx → /sdk/android/calling-setup, and sdk/android/real-time-listeners.mdx → /sdk/android/default-calling.
• Checked against SDK source:
  • OfflineConfig setters, defaults and clamps
  • public CometChat offline methods and listener registration
  • two-phase and offline listener callback signatures (List<BaseMessage> is correct)
  • enum values and error codes
  • the deprecated-overload table
  • the 401/403/410 re-sign rule, the 5-attempt cap and the 1000-change sync page
  • FIELD_AES_GCM and SOFTWARE are correctly left out, because Android never reports them
• Earlier review: spot checks of Ketan's fixes still hold (for example, the onMessagePending wording and retryAllFailedMessages scope).

Not checked

• Nothing was built or run: the code samples weren't compiled, and no behaviour was exercised on a device.
• Behaviour claims: I traced a sample of them to source, not all of them.
• Modified pages: I reviewed setup, overview, upgrading-from-v4, real-time-listeners, connection-status and authentication-overview by diff. The other changed v5 pages got only pattern checks for stale callbacks, version pins and snippet use, not a line-by-line read.
• Flagged code examples: campaigns.mdx:387,408 still uses CallbackListener, but on categoriesRequest, which isn't in the deprecation table, so I didn't count it as a finding.

[jitvarpatil]

Suggested changelog. No changelog entry was found in this PR, so this draft was generated from its commits and diff. Version v5.1.0 is proposed (based on the version this PR pins and libraryVersion in the SDK's build.gradle). Please verify, then copy it into the changelog.

v5.1.0

New

• Added opt-in offline support, which caches conversations and messages on the device and catches up on reconnect. Enable it with OfflineConfig.Builder().enabled(true) and AppSettingsBuilder.setOfflineConfig(), or with the offline(true) shorthand; it is off by default.
• Added two-phase fetch listeners, such as MessageFetchListener, ConversationFetchListener and UserFetchListener, which deliver the cached result first and the server result next.
• Added MessageSentListener and a durable send outbox, so messages sent without a connection are queued and sent automatically on reconnect. getPendingMessages(), retryMessage(), retryAllFailedMessages() and discardLocalMessage() inspect and recover queued messages.
• Added catch-up sync controls, including SyncListener, forceSyncNow(), getSyncState() and MessageListener.onMessagesSynced(), along with OfflineCacheResetListener for cache rebuilds.
• Added media caching through MediaCachingMode, downloadMedia(), getCachedMediaPath() and MediaDownloadListener, so cached attachments stay viewable offline.
• Added optional encryption of the offline message database with OfflineConfig.Builder.encryption(true), which requires adding net.zetetic:sqlcipher-android to the app. Downloaded media files are not encrypted.

Enhancements

• None

Fixes

• None

Deprecations

• Deprecated the CallbackListener overloads of the list fetch methods, getMessageDetails() and getConversation(). Use the matching two-phase listeners instead; the old overloads keep working and receive only the server result.
• Deprecated the CallbackListener overloads of sendMessage(), sendMediaMessage(), sendCustomMessage() and sendInteractiveMessage(). Use MessageSentListener instead; the old overloads keep working but never queue a message.