{
  "generatedFrom": "cometchat.com/docs — sdk/android/v5 (setup, authentication-overview, send-message, receive-messages, real-time-listeners, additional-message-filtering) verified 2026-08-20; symbols cross-checked against test-suite/catalogs/sdk-android-v5.json (curated from the INSTALLED com.cometchat:chat-sdk-android:5.0.5 AAR). Android adaptation of the web-react contracts.json 'sdk-chat-surface' entry — same capability NAMES where the principle is shared, Android/Kotlin recipes.",
  "family": "android-sdk",
  "major": "v5",
  "contracts": [
    {
      "for": "sdk-chat-surface",
      "kind": "feature",
      "consumption": "sdk",
      "min_capabilities": ["init-before-anything", "init-then-login-ordering", "credentials-via-settings-file", "prod-auth-token-guidance", "send-message", "receive-via-listener", "listener-register-with-id", "listener-remove-on-teardown", "sdk-error-handling", "pagination-via-request-builder", "production-ready-design-system", "sized-shell-no-overflow", "conversations-users-groups-lists", "list-search", "delete-conversation", "message-actions-working", "thread-panel", "user-group-detail-with-actions", "optimistic-ui-mutations", "loading-empty-error-states"],
      "docs_topic": "https://www.cometchat.com/docs/sdk/android/v5/overview",
      "notes": "HEADLESS (build-your-own-UI) FLOOR for the Android Chat SDK v5 skill — the SDK analogue of core-chat-surface. Capabilities are behaviours the emitted code MUST include, mapped to the Android SDK (FETCH exact signatures from the sdk/android/v5 pages — bake the map, fetch the manual): init-before-anything = CometChat.initFromSettings(context, CallbackListener<String>) resolves (onSuccess) BEFORE any other SDK call — it reads the GITIGNORED app/src/main/assets/cometchat-settings.json (appId, region, credentials.authKey, chatSDK section) and persists integrationSource=\"ai-agent\" for telemetry (AUDIT-084; signature verified vs the installed 5.0.5 AAR — javap: initFromSettings(Context, CallbackListener<String>)). Do NOT use the classic CometChat.init(context, appId, AppSettings) as the default; it loses attribution. init-then-login-ordering = CometChat.login(uid, authKey/authToken, CallbackListener) runs AFTER init and BEFORE send/fetch/listeners; skip login if getLoggedInUser() != null (re-login of the same user throws). credentials-via-settings-file = appId/region/authKey live in the gitignored assets/cometchat-settings.json read by initFromSettings — never hardcoded in source; build-time extras go local.properties → buildConfigField → BuildConfig. prod-auth-token-guidance = server-minted auth token login for prod; Auth Key dev-only. send-message = build TextMessage(receiverId, text, receiverType) + CometChat.sendMessage(msg, CallbackListener<TextMessage>). receive-via-listener = a registered CometChat.MessageListener delivers incoming messages (onTextMessageReceived/onMediaMessageReceived), not polling. listener-register-with-id = CometChat.addMessageListener(UNIQUE_ID, listener). listener-remove-on-teardown = CometChat.removeMessageListener(UNIQUE_ID) in the lifecycle teardown (onDestroy / DisposableEffect onDispose / ViewModel onCleared) — register AND remove; a leaked listener FAILS this contract. sdk-error-handling = every CallbackListener implements onError(CometChatException) and surfaces e.message — never an empty catch. pagination-via-request-builder = MessagesRequest.MessagesRequestBuilder().setLimit(n).build() + fetchPrevious/fetchNext (same builder pattern for Users/Groups/Conversations/GroupMembers requests), not one unbounded call. BECAUSE THE SDK HAS NO UI, the emitted app must ALSO be production-ready UI, deterministically: production-ready-design-system = reuse the app's existing theme (Material3/Compose theme or XML styles) or establish a small token-based one — never ad-hoc one-off styling. sized-shell-no-overflow = the chat screen fills the viewport (match_parent / fillMaxSize), the message list scrolls internally (RecyclerView / LazyColumn with reverseLayout as appropriate), insets + IME handled (adjustResize / imePadding). conversations-users-groups-lists + list-search = all three lists, each searchable via the request builder's search-keyword setter — TWO real traps to emit correctly: (1) casing differs per builder — UsersRequestBuilder.setSearchKeyword / ConversationsRequestBuilder.setSearchKeyword are lowercase but GroupsRequestBuilder.setSearchKeyWord has a CAPITAL W (SDK inconsistency; setSearchKeyword on GroupsRequest = Unresolved reference); (2) Conversations search (and setUnread) is PLAN-GATED — requires the 'Conversation & Advanced Search' feature (Advanced/Custom plan + a dashboard toggle) and OFF-PLAN silently returns the FULL unfiltered list with no error, so gate the conversations-search UI behind an 'Advanced plan' hint or a labelled local filter — never present an unfiltered list as a search result. Users/Groups search are NOT plan-gated. presence-in-header = the header/users presence (onUserOnline/onUserOffline via addUserListener) only fires when the settings asset opts in with chatSDK.presenceSubscription (ALL_USERS/FRIENDS/ROLES; absent ⇒ no realtime presence — getUser().status is a snapshot only). delete-conversation = CometChat.deleteConversation per row. message-actions-working = reply-in-thread / react / edit / delete each wired to the SDK AND reflected in the UI (own-message gating for edit/delete via sender uid). thread-panel = setParentMessageId(...) scoped MessagesRequest + a thread composer. user-group-detail-with-actions = user detail (blockUsers/unblockUsers) + group detail (addMembersToGroup / kickGroupMember / banGroupMember / updateGroupMemberScope / leaveGroup), scope-gated. optimistic-ui-mutations = send/edit/delete/react update the UI immediately (temp 'sending' state, e.g. via the muid) then reconcile in onSuccess/onError (roll back + surface the error). loading-empty-error-states = loading/empty/error on every surface, never blank. This is the full default for a generic 'build chat with the Android SDK' prompt; bare bubbles UNDER-DELIVER. All symbols named here exist in the sdk-android-v5 catalog (curated+members, AUDIT-021 class)."
    }
  ]
}