From fde8d3161e43c270acf1ee4d56bac89cda5d5497 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Tue, 11 Aug 2026 17:33:40 +0530 Subject: [PATCH 01/63] Added AI Integration references --- sdk/javascript/ai-agents.mdx | 17 ++++ sdk/javascript/all-real-time-listeners.mdx | 17 ++++ sdk/javascript/authentication-overview.mdx | 17 ++++ sdk/javascript/block-users.mdx | 17 ++++ sdk/javascript/campaigns.mdx | 17 ++++ sdk/javascript/card-messages.mdx | 17 ++++ sdk/javascript/delivery-read-receipts.mdx | 17 ++++ sdk/javascript/group-kick-ban-members.mdx | 18 ++++ sdk/javascript/llms-javascript-v4.mdx | 113 +++++++++++++++++++++ sdk/javascript/mentions.mdx | 17 ++++ sdk/javascript/message-filtering.mdx | 16 +++ sdk/javascript/reactions.mdx | 17 ++++ sdk/javascript/receive-message.mdx | 17 ++++ sdk/javascript/retrieve-conversations.mdx | 17 ++++ sdk/javascript/retrieve-group-members.mdx | 16 +++ sdk/javascript/retrieve-groups.mdx | 17 ++++ sdk/javascript/retrieve-users.mdx | 17 ++++ sdk/javascript/send-message.mdx | 18 ++++ sdk/javascript/threaded-messages.mdx | 17 ++++ sdk/javascript/upload-files.mdx | 17 ++++ 20 files changed, 436 insertions(+) create mode 100644 sdk/javascript/llms-javascript-v4.mdx diff --git a/sdk/javascript/ai-agents.mdx b/sdk/javascript/ai-agents.mdx index 04056763f..df69e8c8d 100644 --- a/sdk/javascript/ai-agents.mdx +++ b/sdk/javascript/ai-agents.mdx @@ -3,6 +3,23 @@ title: "AI Agents" description: "Handle CometChat AI Agent events, tool calls, and agent messages in JavaScript apps." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.addAIAssistantListener(listenerId, ...)` · `CometChat.removeAIAssistantListener(listenerId)` · `CometChat.addMessageListener(listenerId, ...)` · `CometChat.removeMessageListener(listenerId)` | +| Key classes | `CometChat.AIAssistantBaseEvent` · `CometChat.AIAssistantMessage` · `CometChat.AIToolResultMessage` · `CometChat.AIToolArgumentMessage` · `CometChat.AIToolCall` | +| Primary output | Real-time run events are delivered as `CometChat.AIAssistantBaseEvent` objects to the `onAIAssistantEventReceived` callback; after the run completes, persisted `AIAssistantMessage` / `AIToolResultMessage` / `AIToolArgumentMessage` objects arrive on the `MessageListener` | +| Listeners registered | `AIAssistantListener` via `addAIAssistantListener` / `removeAIAssistantListener` (callback `onAIAssistantEventReceived`); `CometChat.MessageListener` via `addMessageListener` / `removeMessageListener` (callbacks `onAIAssistantMessageReceived`, `onAIToolResultReceived`, `onAIToolArgumentsReceived`) | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | Agents only respond to text messages. `Run Start` and `Run Finished` events are always emitted; Tool Call events only appear when tools are invoked | +| Related | [AI Moderation](/sdk/javascript/ai-moderation) · [AI User Copilot](/sdk/javascript/ai-user-copilot-overview) · [Card Messages](/sdk/javascript/card-messages) · [Send a Message](/sdk/javascript/send-message) | +| Full reference | [`AIAssistantBaseEvent`](/sdk/reference/messages#aiassistantbaseevent) · [`AIAssistantMessage`](/sdk/reference/messages#aiassistantmessage) · [`AIToolResultMessage`](/sdk/reference/messages#aitoolresultmessage) · [`AIToolArgumentMessage`](/sdk/reference/messages#aitoolargumentmessage) | + + + ## AI Agents Overview AI Agents enable intelligent, automated interactions within your application. They can process user messages, trigger tools, and respond with contextually relevant information. For a broader introduction, see the [AI Agents section](/ai-agents). diff --git a/sdk/javascript/all-real-time-listeners.mdx b/sdk/javascript/all-real-time-listeners.mdx index bd78c0c1e..0c7e3bad9 100644 --- a/sdk/javascript/all-real-time-listeners.mdx +++ b/sdk/javascript/all-real-time-listeners.mdx @@ -3,6 +3,23 @@ title: "All Real Time Listeners" description: "Use CometChat real-time listeners for user presence, groups, messages, calls, AI assistant events, and ongoing calls." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.addUserListener(id, new CometChat.UserListener({...}))` · `CometChat.addGroupListener(id, new CometChat.GroupListener({...}))` · `CometChat.addMessageListener(id, new CometChat.MessageListener({...}))` · `CometChat.addCallListener(id, new CometChat.CallListener({...}))` · `CometChat.addAIAssistantListener(id, new CometChat.AIAssistantListener({...}))` · `CometChat.addLoginListener(id, new CometChat.LoginListener({...}))` · `CometChat.addConnectionListener(id, new CometChat.ConnectionListener({...}))` | +| Key classes | `CometChat.UserListener` · `CometChat.GroupListener` · `CometChat.MessageListener` · `CometChat.CallListener` · `CometChat.AIAssistantListener` · `CometChat.LoginListener` · `CometChat.ConnectionListener` | +| Primary output | Each listener fires typed callbacks — e.g. `onUserOnline(user)`, `onGroupMemberJoined(action, user, group)`, `onTextMessageReceived(message)`, `onMessagesDelivered(receipt)`, `onIncomingCallReceived(call)`, `onAIAssistantEventReceived(event)`, `loginSuccess(user)`, `onConnected()` | +| Listeners registered | `UserListener` (`onUserOnline` · `onUserOffline`); `GroupListener` (`onGroupMemberJoined` · `onGroupMemberLeft` · `onGroupMemberKicked` · `onGroupMemberBanned` · `onGroupMemberUnbanned` · `onGroupMemberScopeChanged` · `onMemberAddedToGroup`); `MessageListener` (`onTextMessageReceived` · `onMediaMessageReceived` · `onCustomMessageReceived` · `onTypingStarted` · `onTypingEnded` · `onMessagesDelivered` · `onMessagesRead` · `onMessageEdited` · `onMessageDeleted` · `onMessageReactionAdded` · `onCardMessageReceived` · `onAIAssistantMessageReceived`); `CallListener` (`onIncomingCallReceived` · `onOutgoingCallAccepted` · `onOutgoingCallRejected` · `onIncomingCallCancelled` · `onCallEndedMessageReceived`); `AIAssistantListener` (`onAIAssistantEventReceived`); `LoginListener` (`loginSuccess` · `loginFailure` · `logoutSuccess` · `logoutFailure`); `ConnectionListener` (`onConnected` · `inConnecting` · `onDisconnected` · `onFeatureThrottled`). Remove each with the matching `remove*Listener(id)` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | Listener IDs must be unique per listener; use the same ID to remove it. Always call the matching `remove*Listener(id)` on unmount to avoid memory leaks and duplicate handling. `OngoingCallListener` belongs to the **Calls SDK** (not the Chat SDK) and is used via `CometChatCalls.addCallEventListener()` | +| Related | [Receive a Message](/sdk/javascript/receive-message) · [Delivery & Read Receipts](/sdk/javascript/delivery-read-receipts) · [Typing Indicators](/sdk/javascript/typing-indicators) · [User Presence](/sdk/javascript/user-presence) | +| Full reference | [`User`](/sdk/reference/entities#user) · [`MessageReceipt`](/sdk/reference/auxiliary#messagereceipt) · [`AIAssistantBaseEvent`](/sdk/reference/messages#aiassistantbaseevent) · [`CometChatException`](/sdk/reference/auxiliary#cometchatexception) | + + + CometChat provides 4 listeners viz. 1. [User Listener](/sdk/javascript/all-real-time-listeners#user-listener) diff --git a/sdk/javascript/authentication-overview.mdx b/sdk/javascript/authentication-overview.mdx index 1b5fc8728..07c417761 100644 --- a/sdk/javascript/authentication-overview.mdx +++ b/sdk/javascript/authentication-overview.mdx @@ -4,6 +4,23 @@ sidebarTitle: "Authentication" description: "Create users and authenticate them securely with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.login(UID, authKey)` · `CometChat.login(authToken)` · `CometChat.getLoggedinUser()` · `CometChat.logout()` · `CometChat.createUser(user, authKey)` | +| Key classes | `CometChat.User` · `CometChat.CometChatException` | +| Primary output | `login()` resolves to a `CometChat.User`; `getLoggedinUser()` resolves to the `CometChat.User` or `null` when no session exists; `logout()` resolves on success; all reject with `CometChat.CometChatException` | +| Listeners registered | `CometChat.LoginListener` via `CometChat.addLoginListener(listenerID, ...)` / `CometChat.removeLoginListener(listenerID)`; key callbacks `loginSuccess`, `loginFailure`, `logoutSuccess`, `logoutFailure` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk), and the user must already exist (create via the [Dashboard](https://app.cometchat.com) or the [Create User API](https://api-explorer.cometchat.com/reference/creates-user)) | +| Constraints | Auth Key login and `createUser()` with an Auth Key are for development/testing only — never ship an Auth Key in client code. For production, generate an [Auth Token](https://api-explorer.cometchat.com/reference/create-authtoken) server-side and pass it to `login(authToken)` | +| Related | [User Management](/sdk/javascript/user-management) · [Connection Status](/sdk/javascript/connection-status) · [All Real-Time Listeners](/sdk/javascript/all-real-time-listeners) · [Send a Message](/sdk/javascript/send-message) | +| Full reference | [`User`](/sdk/reference/entities#user) · [`CometChatException`](/sdk/reference/auxiliary#cometchatexception) | + + + ## Create User Before you log in a user, you must add the user to CometChat. diff --git a/sdk/javascript/block-users.mdx b/sdk/javascript/block-users.mdx index c6295b621..b6a7d4713 100644 --- a/sdk/javascript/block-users.mdx +++ b/sdk/javascript/block-users.mdx @@ -3,6 +3,23 @@ title: "Block Users" description: "Block and unblock users in chat apps with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.blockUsers(usersList)` · `CometChat.unblockUsers(usersList)` · `blockedUsersRequest.fetchNext()` (build via `BlockedUsersRequestBuilder`) | +| Request builder | `CometChat.BlockedUsersRequestBuilder` — configure with `.setLimit()` · `.setSearchKeyword()` · `.setDirection()`; then `.build()` → `.fetchNext()` | +| Key classes | `CometChat.User` (access via `getBlockedByMe()`, `getHasBlockedMe()`); direction via `CometChat.BlockedUsersRequest.directions.BLOCKED_BY_ME` / `.HAS_BLOCKED_ME` / `.BOTH` | +| Primary output | `blockUsers()` / `unblockUsers()` resolve to a `{ uid: "success" \| "fail" }` object (each UID processed independently); `fetchNext()` resolves to `Promise`; all reject with `CometChat.CometChatException` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | `setDirection()` default is `BOTH`; `blockUsers()` / `unblockUsers()` take an array of UIDs | +| Related | [Retrieve Users](/sdk/javascript/retrieve-users) · [User Presence](/sdk/javascript/user-presence) · [User Management](/sdk/javascript/user-management) · [Flag a Message](/sdk/javascript/flag-message) | +| Full reference | [`User`](/sdk/reference/entities#user) | + + + ## Block Users Block users to prevent all communication with them. Use `blockUsers()` with an array of UIDs. diff --git a/sdk/javascript/campaigns.mdx b/sdk/javascript/campaigns.mdx index 20253d779..fc5ef04b4 100644 --- a/sdk/javascript/campaigns.mdx +++ b/sdk/javascript/campaigns.mdx @@ -3,6 +3,23 @@ title: "Campaigns" description: "Fetch notification feed items, listen for real-time delivery, mark items as read/delivered, report engagement, and track push notifications using the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.markFeedItemAsRead(feedItem)` · `CometChat.markFeedItemAsDelivered(feedItem)` · `CometChat.markFeedItemsAsDelivered(feedItems)` · `CometChat.reportFeedEngagement(feedItem, interactionString)` · `CometChat.getNotificationFeedUnreadCount()` · `CometChat.getNotificationFeedItem(id)` · `CometChat.markPushNotificationDelivered(pushNotification)` · `CometChat.markPushNotificationClicked(pushNotification)` | +| Request builder | `new CometChat.NotificationFeedRequestBuilder().setLimit(limit).setReadState(state).setCategory(category).setChannelId(channelId).setTags(tags).build()` → `.fetchNext()` · also `NotificationCategoriesRequestBuilder().setLimit(limit).build()` → `.fetchNext()` | +| Key classes | `CometChat.NotificationFeedItem` · `CometChat.NotificationCategory` · `CometChat.PushNotification` · `CometChat.CardMessage` | +| Primary output | `NotificationFeedRequest.fetchNext()` resolves to `CometChat.NotificationFeedItem[]` (empty array when exhausted); `getNotificationFeedUnreadCount()` resolves to `{ count: number }`; mark/report methods resolve on success; all reject with `CometChat.CometChatException` | +| Listeners registered | Notification feed listener via `CometChat.addNotificationFeedListener("feedListener", ...)` / `CometChat.removeNotificationFeedListener("feedListener")`; key callback `onFeedItemReceived`. Card chat messages arrive on `CometChat.MessageListener`'s `onCardMessageReceived` callback | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview); channels, categories, templates, and campaigns configured in the [Dashboard](/campaigns#setup-flow). Render cards with `@cometchat/cards-react` | +| Constraints | Card messages are **receive-only** — created and sent exclusively via the Platform (REST) API or Dashboard Bubble Builder; the SDK exposes the raw Card Schema JSON via `getCard()`. The Cards library is a pure renderer and does not execute card actions — your app must handle action callbacks | +| Related | [Card Messages](/sdk/javascript/card-messages) · [Receive a Message](/sdk/javascript/receive-message) · [All Real-Time Listeners](/sdk/javascript/all-real-time-listeners) · [Send a Message](/sdk/javascript/send-message) | + + + CometChat Campaigns lets you deliver targeted, rich notifications to users via an in-app notification feed. Each notification is a **Card Schema JSON** — a structured layout rendered natively by the CometChat Cards library. The SDK provides APIs to fetch feed items, listen for real-time delivery, mark items as read/delivered, report engagement, and retrieve unread counts. diff --git a/sdk/javascript/card-messages.mdx b/sdk/javascript/card-messages.mdx index 91d4ccc2b..f1a108059 100644 --- a/sdk/javascript/card-messages.mdx +++ b/sdk/javascript/card-messages.mdx @@ -3,6 +3,23 @@ title: "Card Messages" description: "Receive and render rich card messages with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.addMessageListener(listenerID, new CometChat.MessageListener({...}))` · `CometChat.addAIAssistantListener(listenerID, new CometChat.AIAssistantListener({...}))` · `cardMessage.getCard()` · `message.getElements()` · `element.getType()` / `element.getData()` | +| Key classes | `CometChat.CardMessage` · `CometChat.MessageListener` · `CometChat.AIAssistantMessage` · `CometChat.AIAssistantElement` · `CometChat.AIAssistantListener` · `CometChat.AIAssistantBaseEvent` (`AIAssistantCardStartedEvent` · `AIAssistantCardReceivedEvent` · `AIAssistantCardEndedEvent`) | +| Primary output | Cards are receive-only. Standalone cards arrive as a `CardMessage` (`getCard()` returns the raw Card Schema JSON, or `undefined`); inline cards arrive as elements on an `AIAssistantMessage` (`getElements()` returns `AIAssistantElement[]`); streaming cards arrive as `card_start` / `card` / `card_end` events (`getCard()` on the `card` event) | +| Listeners registered | `MessageListener` — `onCardMessageReceived(cardMessage: CometChat.CardMessage)` and `onAIAssistantMessageReceived(message: CometChat.AIAssistantMessage)`; `AIAssistantListener` — `onAIAssistantEventReceived(event: CometChat.AIAssistantBaseEvent)` for `card_start` / `card` / `card_end`. Remove with `CometChat.removeMessageListener(id)` / `CometChat.removeAIAssistantListener(id)` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | Card support is **receive-only** — cards cannot be composed or sent from the SDK (they are authored server-side via the Platform REST API or Dashboard). Branch on `getCategory() === "card"` (a card's `getType()` returns `"text"`). The SDK never interprets the card body; rendering is your app's responsibility. Streaming and persisted cards for the same card share a `cardId` — correlate to avoid rendering twice. Always remove listeners on unmount | +| Related | [Receive a Message](/sdk/javascript/receive-message) · [AI Agents](/sdk/javascript/ai-agents) · [All Real Time Listeners](/sdk/javascript/all-real-time-listeners) · [Send a Message](/sdk/javascript/send-message) | +| Full reference | [`CardMessage`](/sdk/reference/messages#cardmessage) · [`AIAssistantMessage`](/sdk/reference/messages#aiassistantmessage) · [`AIAssistantElement`](/sdk/reference/messages#aiassistantelement) · [`AIAssistantBaseEvent`](/sdk/reference/messages#aiassistantbaseevent) | + + + Card messages let your app display rich, structured content — such as product cards, confirmations, or AI-generated summaries — inside a conversation. In the JavaScript SDK, card support is **receive-only**: the SDK deserializes incoming cards and hands you their raw payload through typed accessors, and your app is responsible for turning that payload into UI. The body of a card is **Card Schema JSON** — the same structured layout used by [Campaigns notification feeds](/sdk/javascript/campaigns). Cards are authored server-side (they cannot be composed or sent from the SDK) via the [Platform (REST) API](/rest-api/messages/send-message) or the **Dashboard Bubble Builder**, and delivered to clients like any other message. diff --git a/sdk/javascript/delivery-read-receipts.mdx b/sdk/javascript/delivery-read-receipts.mdx index aa076ccb5..3e44da187 100644 --- a/sdk/javascript/delivery-read-receipts.mdx +++ b/sdk/javascript/delivery-read-receipts.mdx @@ -3,6 +3,23 @@ title: "Delivery & Read Receipts" description: "Mark messages as delivered or read and handle receipts with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.markAsDelivered(message)` · `CometChat.markAsRead(message)` · `CometChat.markConversationAsDelivered(conversationWith, conversationType)` · `CometChat.markConversationAsRead(conversationWith, conversationType)` · `CometChat.markAsUnread(message)` · `CometChat.getMessageReceipts(messageId)` | +| Key classes | `CometChat.MessageListener` · `CometChat.MessageReceipt` · `CometChat.BaseMessage` | +| Primary output | `markAsDelivered()` / `markAsRead()` are fire-and-forget (they resolve but do **not** return a `MessageReceipt`); `markConversationAsDelivered()` / `markConversationAsRead()` resolve with a `string`; `markAsUnread()` resolves with a `string`; `getMessageReceipts()` resolves to `Promise`; all reject with `CometChat.CometChatException` | +| Listeners registered | `MessageListener` via `CometChat.addMessageListener(listenerID, ...)` / `CometChat.removeMessageListener(listenerID)` — receipt callbacks: `onMessagesDelivered`, `onMessagesRead`, `onMessagesDeliveredToAll` (groups), `onMessagesReadByAll` (groups), each receiving a `CometChat.MessageReceipt` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | `onMessagesDeliveredToAll`, `onMessagesReadByAll`, group `deliveredAt` / `readAt`, and `markAsUnread()` require the **Enhanced Messaging Status** feature. Always remove listeners on unmount to avoid memory leaks | +| Related | [Receive a Message](/sdk/javascript/receive-message) · [Typing Indicators](/sdk/javascript/typing-indicators) · [Retrieve Conversations](/sdk/javascript/retrieve-conversations) · [All Real Time Listeners](/sdk/javascript/all-real-time-listeners) | +| Full reference | [`MessageReceipt`](/sdk/reference/auxiliary#messagereceipt) · [`User`](/sdk/reference/entities#user) · [`BaseMessage`](/sdk/reference/messages#basemessage) | + + + ## Mark Messages as Delivered _In other words, as a recipient, how do I inform the sender that I've received a message?_ diff --git a/sdk/javascript/group-kick-ban-members.mdx b/sdk/javascript/group-kick-ban-members.mdx index 8fd34655d..46c090bb5 100644 --- a/sdk/javascript/group-kick-ban-members.mdx +++ b/sdk/javascript/group-kick-ban-members.mdx @@ -3,6 +3,24 @@ title: "Ban Or Kick Member From A Group" description: "Kick, ban, and unban CometChat group members in JavaScript apps when the logged-in user is an admin or moderator." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.kickGroupMember(GUID, UID)` · `CometChat.banGroupMember(GUID, UID)` · `CometChat.unbanGroupMember(GUID, UID)` | +| Request builder | `new CometChat.BannedMembersRequestBuilder(GUID).setLimit(limit).setSearchKeyword(keyword).build()` → `.fetchNext()` | +| Key classes | `CometChat.GroupMember` · `CometChat.User` · `CometChat.Group` · `CometChat.Action` | +| Primary output | `kickGroupMember()` / `banGroupMember()` / `unbanGroupMember()` resolve to `boolean` (`true`) · `BannedMembersRequest.fetchNext()` resolves to `CometChat.GroupMember[]` · all reject with `CometChat.CometChatException` | +| Listeners registered | `CometChat.GroupListener` via `CometChat.addGroupListener(listenerID, ...)` / `CometChat.removeGroupListener(listenerID)`; key callbacks `onGroupMemberKicked`, `onGroupMemberBanned`, `onGroupMemberUnbanned` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | Kick, ban, and unban can only be performed by the group **Admin** or **Moderator**. A kicked user can rejoin; a banned user cannot rejoin until unbanned | +| Related | [Add Members](/sdk/javascript/group-add-members) · [Change Member Scope](/sdk/javascript/group-change-member-scope) · [Retrieve Group Members](/sdk/javascript/retrieve-group-members) · [Leave a Group](/sdk/javascript/leave-group) | +| Full reference | [`GroupMember`](/sdk/reference/entities#groupmember) · [`User`](/sdk/reference/entities#user) · [`Group`](/sdk/reference/entities#group) · [`Action`](/sdk/reference/messages#action) | + + + There are certain actions that can be performed on the group members: 1. Kick a member from the group diff --git a/sdk/javascript/llms-javascript-v4.mdx b/sdk/javascript/llms-javascript-v4.mdx new file mode 100644 index 000000000..48c32d3f3 --- /dev/null +++ b/sdk/javascript/llms-javascript-v4.mdx @@ -0,0 +1,113 @@ +--- +title: "JavaScript Chat SDK v4 — LLM docs index" +description: "Machine-readable, JavaScript-SDK-v4-scoped index of every SDK page as a clean .md twin. Built for AI coding agents; kept out of the human sidebar." +--- + +{/* + SCOPED LLM INDEX for the JavaScript Chat SDK v4. + - UNLISTED, NOT hidden: intentionally omitted from docs.json navigation so it never shows in + the human sidebar — but it IS built, served as a clean .md twin, and INDEXED for search + + AI assistants (so AI tools, and this pack's skill via its docs-map, can discover and read it). + - We deliberately do NOT use `hidden: true`/`noindex` here: in Mintlify `hidden` auto-applies + noindex, which would drop this page from search AND the auto global llms.txt / AI context. + We want it discoverable, so it stays indexable. + - Fetch this file's own .md twin as a lightweight, JS-SDK-only routing index instead of the + site-wide /docs/llms.txt (which spans every product and is far larger). +*/} + +# JavaScript Chat SDK v4 — LLM docs index (Latest) + +> Low-level JavaScript/TypeScript chat + calling client. Package +> `@cometchat/chat-sdk-javascript@4`. This page is a **JavaScript-SDK-v4-only** routing index for +> AI agents — a scoped alternative to the site-wide `/docs/llms.txt`. + +## How to use this index +Each link below is already a **`.md` twin** (clean Markdown: verbatim code + method signatures, +parameters, and listener contracts). Pick the page for the intent, fetch its `.md`, read the API +there. +- Convention: any docs page URL + `.md` → raw Markdown. +- Fallback: if a `.md` twin 404s, fetch the same URL **without** `.md` (HTML). Never read a + package `.d.ts` and never answer APIs from memory. + +## Hot path — usually no fetch needed +For a plain "add chat" the install, `init → login`, and the core `sendMessage` / `receive-message` +listener flow are stable; a well-built agent skill bakes them. Fetch below only for exhaustive +parameters, long-tail methods, group/user management, calling, or edge-case listeners. +- Setup: [Integration / Setup](setup-sdk.md) +- Auth/lifecycle: [Authentication](authentication-overview.md) +- Core send/receive: [Send a Message](send-message.md) · [Receive a Message](receive-message.md) · [Real-time Listeners](all-real-time-listeners.md) + +## Getting started / integration +- [Overview](overview.md) +- [Integration / Setup](setup-sdk.md) +- [Authentication](authentication-overview.md) + +## Messaging +- [Send a Message](send-message.md) +- [Media & File Messages](upload-files.md) +- [Receive a Message](receive-message.md) +- [Interactive / Card Messages](card-messages.md) +- [Message Filtering](message-filtering.md) +- [Retrieve Conversations](retrieve-conversations.md) +- [Threaded Messages](threaded-messages.md) +- [Edit a Message](edit-message.md) +- [Delete a Message](delete-message.md) +- [Flag a Message](flag-message.md) +- [Delete a Conversation](delete-conversation.md) +- [Typing Indicators](typing-indicators.md) +- [Transient Messages](transient-messages.md) +- [Delivery & Read Receipts](delivery-read-receipts.md) +- [Mentions](mentions.md) +- [Reactions](reactions.md) + +## Calling +- [Calling — Overview](calling-overview.md) + +## Users +- [Users — Overview](users-overview.md) +- [Retrieve Users](retrieve-users.md) +- [User Management](user-management.md) +- [Block Users](block-users.md) +- [User Presence](user-presence.md) + +## Groups +- [Groups — Overview](groups-overview.md) +- [Retrieve Groups](retrieve-groups.md) +- [Create a Group](create-group.md) +- [Update a Group](update-group.md) +- [Join a Group](join-group.md) +- [Leave a Group](leave-group.md) +- [Delete a Group](delete-group.md) +- [Retrieve Group Members](retrieve-group-members.md) +- [Add Group Members](group-add-members.md) +- [Kick / Ban Members](group-kick-ban-members.md) +- [Change Member Scope](group-change-member-scope.md) +- [Transfer Group Ownership](transfer-group-ownership.md) + +## AI, campaigns & webhooks +- [AI Moderation](ai-moderation.md) +- [AI Agents](ai-agents.md) +- [AI Copilot](ai-copilot.md) +- [Campaigns](campaigns.md) +- [Webhooks](webhooks.md) + +## Resources +- [Key Concepts](key-concepts.md) +- [Message Structure & Hierarchy](message-structure-and-hierarchy.md) +- [All Real-time Listeners](all-real-time-listeners.md) +- [Rate Limits](rate-limits.md) +- [Connection Status](connection-status.md) +- [Managing WebSocket Connections Manually](managing-web-sockets-connections-manually.md) + +## Best practices & troubleshooting +- [Best Practices](best-practices.md) +- [Error Codes](error-codes.md) +- [Troubleshooting](troubleshooting.md) + +## Migration & overviews +- [Upgrading from v3](upgrading-from-v3.md) +- [Extensions — Overview](extensions-overview.md) +- [AI User Copilot — Overview](ai-user-copilot-overview.md) +- [AI Chatbots — Overview](ai-chatbots-overview.md) +- [Webhooks — Overview](webhooks-overview.md) +- [Changelog](changelog.md) diff --git a/sdk/javascript/mentions.mdx b/sdk/javascript/mentions.mdx index fc0accb02..0ce740378 100644 --- a/sdk/javascript/mentions.mdx +++ b/sdk/javascript/mentions.mdx @@ -3,6 +3,23 @@ title: "Mentions" description: "Add user mentions to CometChat messages in one-on-one and group chats using UID-based mention syntax." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.sendMessage(textMessage)` (mention with `<@uid:UID>` syntax in the text) · `messagesRequest.fetchPrevious()` (build via `MessagesRequestBuilder`) · `message.getMentionedUsers()` | +| Request builder | `CometChat.MessagesRequestBuilder` — scope with `.setUID()` / `.setGUID()`, add `.setLimit()`, then `.mentionsWithTagInfo(true)` or `.mentionsWithBlockedInfo(true)`; `.build()` → `.fetchPrevious()` / `.fetchNext()` | +| Key classes | `CometChat.TextMessage` (send), `CometChat.BaseMessage` (fetched results), `CometChat.User` (mentioned users, via `getTags()` / `getBlockedByMe()` / `getHasBlockedMe()`) | +| Primary output | `sendMessage()` resolves to the sent `CometChat.TextMessage`; `fetchPrevious()` resolves to `Promise`; `getMentionedUsers()` returns `CometChat.User[]` (empty when none); async calls reject with `CometChat.CometChatException` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | Mention format is `<@uid:UID>`; mentions are supported in text messages and media message captions; `mentionsWithTagInfo()` and `mentionsWithBlockedInfo()` default to `false` | +| Related | [Send a Message](/sdk/javascript/send-message) · [Additional Message Filtering](/sdk/javascript/message-filtering) · [Reactions](/sdk/javascript/reactions) · [Threaded Messages](/sdk/javascript/threaded-messages) | +| Full reference | [`TextMessage`](/sdk/reference/messages#textmessage) · [`BaseMessage`](/sdk/reference/messages#basemessage) · [`User`](/sdk/reference/entities#user) | + + + Mentions in messages enable users to refer to specific individual within a conversation. This is done by using the `<@uid:UID>` format, where `UID` represents the user’s unique identification. Mentions are a powerful tool for enhancing communication in messaging platforms. They streamline interaction by allowing users to easily engage and collaborate with particular individuals, especially in group conversations. diff --git a/sdk/javascript/message-filtering.mdx b/sdk/javascript/message-filtering.mdx index 595b6964c..b5d155c72 100644 --- a/sdk/javascript/message-filtering.mdx +++ b/sdk/javascript/message-filtering.mdx @@ -3,6 +3,22 @@ title: "Additional Message Filtering" description: "Filter and paginate CometChat messages by user, group, type, category, tags, timestamps, and unread status." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `messagesRequest.fetchNext()` · `messagesRequest.fetchPrevious()` (build via `MessagesRequestBuilder`) | +| Request builder | `CometChat.MessagesRequestBuilder` — scope with `.setUID(uid)` / `.setGUID(guid)`; filter with `.setLimit()` · `.setMessageId()` · `.setTimestamp()` · `.setCategories()` · `.setTypes()` · `.setTags()` · `.setParentMessageId()`; then `.build()` → `.fetchNext()` (newer) / `.fetchPrevious()` (older) | +| Primary output | `Promise` — resolves to an array of message objects; rejects with `CometChat.CometChatException` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview); `.setGUID()` requires the logged-in user to be a group member | +| Constraints | `.setLimit()` max is 100 messages per iteration; `hasLinks()`, `hasAttachments()`, `hasReactions()`, `hasMentions()`, `setMentionedUIDs()`, and `setAttachmentTypes()` require the Conversation & Advanced Search add-on (Advanced/Custom plans) | +| Related | [Send a Message](/sdk/javascript/send-message) · [Receive a Message](/sdk/javascript/receive-message) · [Message Structure & Hierarchy](/sdk/javascript/message-structure-and-hierarchy) · [Threaded Messages](/sdk/javascript/threaded-messages) | +| Full reference | [`BaseMessage`](/sdk/reference/messages#basemessage) · [`TextMessage`](/sdk/reference/messages#textmessage) | + + + The `MessagesRequest` class as you must be familiar with helps you to fetch messages based on the various parameters provided to it. This document will help you understand better the various options that are available using the `MessagesRequest` class. The `MessagesRequest` class is designed using the `Builder design pattern`. In order to obtain an object of the `MessagesRequest` class, you will have to make use of the `MessagesRequestBuilder` class in the `MessagesRequest` class. diff --git a/sdk/javascript/reactions.mdx b/sdk/javascript/reactions.mdx index 0f42c7834..9e60b6b80 100644 --- a/sdk/javascript/reactions.mdx +++ b/sdk/javascript/reactions.mdx @@ -3,6 +3,23 @@ title: "Reactions" description: "Add, remove, fetch, and listen for message reactions with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.addReaction(messageId, emoji)` · `CometChat.removeReaction(messageId, emoji)` · `message.getReactions()` · `reactionCount.getReactedByMe()` · `CometChat.CometChatHelper.updateMessageWithReactionInfo(message, messageReaction, action)` | +| Request builder | `new CometChat.ReactionRequestBuilder().setMessageId(messageId).setReaction(emoji).setLimit(limit).build()` → `.fetchNext()` / `.fetchPrevious()` (max 100 per request) | +| Key classes | `CometChat.BaseMessage` · `CometChat.Reaction` · `CometChat.ReactionCount` · `CometChat.MessageReaction` · `CometChat.REACTION_ACTION` | +| Primary output | `addReaction()` / `removeReaction()` resolve to a `CometChat.BaseMessage` with updated reactions · `fetchNext()` / `fetchPrevious()` resolve to `CometChat.Reaction[]` · all reject with `CometChat.CometChatException` | +| Listeners registered | `CometChat.MessageListener` via `CometChat.addMessageListener(listenerID, ...)` / `CometChat.removeMessageListener(listenerID)`; key callbacks `onMessageReactionAdded` and `onMessageReactionRemoved` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Related | [Send a Message](/sdk/javascript/send-message) · [Receive a Message](/sdk/javascript/receive-message) · [Mentions](/sdk/javascript/mentions) · [Threaded Messages](/sdk/javascript/threaded-messages) | +| Full reference | [`BaseMessage`](/sdk/reference/messages#basemessage) · [`Reaction`](/sdk/reference/auxiliary#reaction) · [`ReactionCount`](/sdk/reference/auxiliary#reactioncount) · [`ReactionEvent`](/sdk/reference/auxiliary#reactionevent) | + + + Enhance user engagement in your chat application with message reactions. Users can express their emotions using reactions to messages. This feature allows users to add or remove reactions, and to fetch all reactions on a message. You can also listen to reaction events in real-time. Let's see how to work with reactions in CometChat's SDK. ## Add a Reaction diff --git a/sdk/javascript/receive-message.mdx b/sdk/javascript/receive-message.mdx index 3ecb4256b..7e10973ab 100644 --- a/sdk/javascript/receive-message.mdx +++ b/sdk/javascript/receive-message.mdx @@ -3,6 +3,23 @@ title: "Receive A Message" description: "Receive real-time, unread, and historical messages with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.addMessageListener(listenerID, new CometChat.MessageListener({...}))` · `new CometChat.MessagesRequestBuilder().setUID(UID).setLimit(limit).build()` · `messagesRequest.fetchPrevious()` · `CometChat.getUnreadMessageCount()` · `CometChat.getMessageDetails(messageId)` | +| Key classes | `CometChat.MessageListener` · `CometChat.MessagesRequestBuilder` · `CometChat.MessagesRequest` · `CometChat.BaseMessage` (`TextMessage` · `MediaMessage` · `CustomMessage`) | +| Primary output | Real-time callbacks deliver the specific message subclass (`TextMessage` / `MediaMessage` / `CustomMessage`); `fetchPrevious()` resolves to `Promise`; `getMessageDetails()` resolves to `Promise`; unread-count methods resolve to a `Promise` of an ID→count object; all reject with `CometChat.CometChatException` | +| Listeners registered | `MessageListener` via `CometChat.addMessageListener(listenerID, ...)` / `CometChat.removeMessageListener(listenerID)` — callbacks shown: `onTextMessageReceived`, `onMediaMessageReceived`, `onCustomMessageReceived` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | As a sender you do not receive your own message in a real-time event (though other devices of the same logged-in user do). Always remove listeners on unmount to avoid memory leaks and duplicate handling. Advanced search (file name, mentions, MIME type) requires the `Conversation & Advanced Search` feature | +| Related | [Send a Message](/sdk/javascript/send-message) · [Delivery & Read Receipts](/sdk/javascript/delivery-read-receipts) · [All Real Time Listeners](/sdk/javascript/all-real-time-listeners) · [Retrieve Conversations](/sdk/javascript/retrieve-conversations) | +| Full reference | [`BaseMessage`](/sdk/reference/messages#basemessage) · [`TextMessage`](/sdk/reference/messages#textmessage) · [`MediaMessage`](/sdk/reference/messages#mediamessage) · [`CustomMessage`](/sdk/reference/messages#custommessage) | + + + Receiving messages with CometChat has two parts: 1. Adding a [real-time listener](#real-time-messages) to receive messages while your app is running diff --git a/sdk/javascript/retrieve-conversations.mdx b/sdk/javascript/retrieve-conversations.mdx index b014834de..63374ed5f 100644 --- a/sdk/javascript/retrieve-conversations.mdx +++ b/sdk/javascript/retrieve-conversations.mdx @@ -3,6 +3,23 @@ title: "Retrieve Conversations" description: "Fetch recent CometChat conversations for chat lists, with support for one-on-one and group conversation filters." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `conversationsRequest.fetchNext()` (build via `ConversationsRequestBuilder`) · `CometChat.getConversation(conversationWith, conversationType)` · `CometChat.tagConversation(conversationWith, conversationType, tags)` · `CometChat.CometChatHelper.getConversationFromMessage(message)` | +| Request builder | `CometChat.ConversationsRequestBuilder` — configure with `.setLimit()` · `.setConversationType()` · `.setUserTags()` · `.setGroupTags()` · `.setTags()` · `.setSearchKeyword()` · `.setUnread()`; then `.build()` → `.fetchNext()` (call repeatedly to paginate) | +| Key classes | `CometChat.Conversation` (access peer via `getConversationWith()`, tags via `getTags()`) | +| Primary output | `Promise` from `fetchNext()`; `getConversation()` / `tagConversation()` resolve to a single `CometChat.Conversation`; all reject with `CometChat.CometChatException` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | `setLimit()` default is 30, max is 50; `setSearchKeyword()` and `setUnread()` require the Conversation & Advanced Search add-on (Advanced/Custom plans); `setHideAgentic()` and `setOnlyAgentic()` are mutually exclusive | +| Related | [Delete a Conversation](/sdk/javascript/delete-conversation) · [Receive a Message](/sdk/javascript/receive-message) · [Typing Indicators](/sdk/javascript/typing-indicators) · [Delivery & Read Receipts](/sdk/javascript/delivery-read-receipts) | +| Full reference | [`Conversation`](/sdk/reference/entities#conversation) | + + + Conversations provide the last messages for every one-on-one and group conversation the logged-in user is a part of. This makes it easy for you to build a **Recent Chat** list. ## Retrieve List of Conversations diff --git a/sdk/javascript/retrieve-group-members.mdx b/sdk/javascript/retrieve-group-members.mdx index 0c1d34d5f..87ab6a857 100644 --- a/sdk/javascript/retrieve-group-members.mdx +++ b/sdk/javascript/retrieve-group-members.mdx @@ -3,6 +3,22 @@ title: "Retrieve Group Members" description: "Fetch and paginate group members using the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `groupMembersRequest.fetchNext()` (build via `GroupMembersRequestBuilder`) | +| Request builder | `CometChat.GroupMembersRequestBuilder(GUID)` — GUID is passed to the constructor; configure with `.setLimit()` · `.setSearchKeyword()` · `.setScopes()` · `.setStatus()`; then `.build()` → `.fetchNext()` (call repeatedly to paginate) | +| Key classes | `CometChat.GroupMember` extends `CometChat.User`; access scope via `getScope()` (`"admin"` / `"moderator"` / `"participant"`); status via `CometChat.USER_STATUS.ONLINE` / `.OFFLINE` | +| Primary output | `Promise` — resolves to an array of members; rejects with `CometChat.CometChatException` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview); a valid GUID must be supplied to the builder constructor | +| Related | [Retrieve Groups](/sdk/javascript/retrieve-groups) · [Add Members to a Group](/sdk/javascript/group-add-members) · [Kick & Ban Members](/sdk/javascript/group-kick-ban-members) · [Create a Group](/sdk/javascript/create-group) | +| Full reference | [`GroupMember`](/sdk/reference/entities#groupmember) · [`User`](/sdk/reference/entities#user) | + + + ## Retrieve the List of Group Members Use `GroupMembersRequestBuilder` to fetch members of a [Group](/sdk/reference/entities#group). The GUID must be specified in the constructor. diff --git a/sdk/javascript/retrieve-groups.mdx b/sdk/javascript/retrieve-groups.mdx index bc79702f6..e8f1017c9 100644 --- a/sdk/javascript/retrieve-groups.mdx +++ b/sdk/javascript/retrieve-groups.mdx @@ -3,6 +3,23 @@ title: "Retrieve Groups" description: "Fetch, search, filter, and paginate groups using the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `groupsRequest.fetchNext()` (build via `GroupsRequestBuilder`) · `CometChat.getGroup(guid)` · `CometChat.getOnlineGroupMemberCount(guids)` | +| Request builder | `CometChat.GroupsRequestBuilder` — configure with `.setLimit()` · `.setSearchKeyword()` · `.joinedOnly()` · `.setTags()` · `.withTags()`; then `.build()` → `.fetchNext()` (call repeatedly to paginate) | +| Key classes | `CometChat.Group` (access tags via `getTags()`) | +| Primary output | `Promise` from `fetchNext()`; `getGroup()` resolves to a single `CometChat.Group`; `getOnlineGroupMemberCount()` resolves to a `{ guid: count }` object; all reject with `CometChat.CometChatException` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | The list returns only public and password-protected groups; private groups appear only when the logged-in user is a member | +| Related | [Create a Group](/sdk/javascript/create-group) · [Retrieve Group Members](/sdk/javascript/retrieve-group-members) · [Add Members to a Group](/sdk/javascript/group-add-members) · [Retrieve Conversations](/sdk/javascript/retrieve-conversations) | +| Full reference | [`Group`](/sdk/reference/entities#group) | + + + ## Retrieve List of Groups _In other words, as a logged-in user, how do I retrieve the list of groups I've joined and groups that are available?_ diff --git a/sdk/javascript/retrieve-users.mdx b/sdk/javascript/retrieve-users.mdx index e3c05c4fc..03c856596 100644 --- a/sdk/javascript/retrieve-users.mdx +++ b/sdk/javascript/retrieve-users.mdx @@ -3,6 +3,23 @@ title: "Retrieve Users" description: "Retrieve users, logged-in user details, and online counts with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `usersRequest.fetchNext()` (build via `UsersRequestBuilder`) · `CometChat.getLoggedinUser()` · `CometChat.getUser(uid)` · `CometChat.getOnlineUserCount()` | +| Request builder | `CometChat.UsersRequestBuilder` — configure with `.setLimit()` · `.setSearchKeyword()` · `.searchIn()` · `.setStatus()` · `.hideBlockedUsers()` · `.setRoles()` · `.friendsOnly()` · `.setTags()` · `.withTags()` · `.setUIDs()` · `.sortBy()` · `.sortByOrder()`; then `.build()` → `.fetchNext()` (call repeatedly to paginate) | +| Key classes | `CometChat.User` (access via `getUid()`, `getName()`, `getStatus()`, `getRole()`, `getTags()`); status via `CometChat.USER_STATUS.ONLINE` / `.OFFLINE` | +| Primary output | `Promise` from `fetchNext()`; `getLoggedinUser()` / `getUser()` resolve to a single `CometChat.User`; `getOnlineUserCount()` resolves to a `number`; all reject with `CometChat.CometChatException` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | `setUIDs()` fetches a maximum of 25 users per request; `searchIn()` defaults to both `uid` and `name`; default sort order is `status → name → UID`, ascending | +| Related | [User Presence](/sdk/javascript/user-presence) · [Block Users](/sdk/javascript/block-users) · [User Management](/sdk/javascript/user-management) · [Retrieve Conversations](/sdk/javascript/retrieve-conversations) | +| Full reference | [`User`](/sdk/reference/entities#user) | + + + ## Retrieve Logged In User Details You can get the details of the logged-in user using the `getLoggedInUser()` method. This method can also be used to check if the user is logged in or not. If the method returns `Promise` with reject callback, it indicates that the user is not logged in and you need to log the user into CometChat SDK. diff --git a/sdk/javascript/send-message.mdx b/sdk/javascript/send-message.mdx index b644b02c0..14cc60cd4 100644 --- a/sdk/javascript/send-message.mdx +++ b/sdk/javascript/send-message.mdx @@ -3,6 +3,24 @@ title: "Send A Message" description: "Send text, media, custom, and interactive chat messages with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.sendMessage(textMessage)` · `CometChat.sendMediaMessage(mediaMessage)` · `CometChat.sendCustomMessage(customMessage)` | +| Message classes | `CometChat.TextMessage`, `CometChat.MediaMessage`, `CometChat.CustomMessage` (use `CometChat.Attachment` for hosted-URL media) | +| Primary output | `Promise` — resolves to the sent `TextMessage` / `MediaMessage` / `CustomMessage`; rejects with `CometChat.CometChatException` | +| Receiver targeting | `receiverType`: `CometChat.RECEIVER_TYPE.USER` (pass a UID) or `CometChat.RECEIVER_TYPE.GROUP` (pass a GUID) | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview) | +| Constraints | Card messages are **receive-only** (no `sendCardMessage()`). Media messages carry ≤ `file.count.max` attachments (default 10) or reject with `ERR_FILE_COUNT_EXCEEDED`; read the limit at runtime with `CometChat.getMaxAttachmentCount()` | +| Receive counterpart | Sent messages reach peers through `MessageListener` — see [Receive a Message](/sdk/javascript/receive-message) | +| Related | [Upload Files](/sdk/javascript/upload-files) · [Threaded Messages](/sdk/javascript/threaded-messages) · [Edit a Message](/sdk/javascript/edit-message) · [Delete a Message](/sdk/javascript/delete-message) | +| Full reference | [`TextMessage`](/sdk/reference/messages#textmessage) · [`MediaMessage`](/sdk/reference/messages#mediamessage) · [`CustomMessage`](/sdk/reference/messages#custommessage) | + + + Using CometChat, you can send three types of messages: 1. [Text Message](/sdk/javascript/send-message#text-message) is the most common and standard message type. diff --git a/sdk/javascript/threaded-messages.mdx b/sdk/javascript/threaded-messages.mdx index 1d6af168f..9025ac95b 100644 --- a/sdk/javascript/threaded-messages.mdx +++ b/sdk/javascript/threaded-messages.mdx @@ -3,6 +3,23 @@ title: "Threaded Messages" description: "Send, receive, and fetch threaded messages with the CometChat JavaScript SDK." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `textMessage.setParentMessageId(messageId)` · `CometChat.sendMessage(textMessage)` · `CometChat.addMessageListener(listenerID, new CometChat.MessageListener({...}))` · `message.getParentMessageId()` · `new CometChat.MessagesRequestBuilder().setParentMessageId(parentMessageId).setLimit(limit).build()` · `messagesRequest.fetchPrevious()` · `.hideReplies(true)` | +| Key classes | `CometChat.MessageListener` · `CometChat.MessagesRequestBuilder` · `CometChat.MessagesRequest` · `CometChat.TextMessage` · `CometChat.MediaMessage` · `CometChat.CustomMessage` · `CometChat.BaseMessage` | +| Primary output | `sendMessage()` resolves to the sent message (e.g. `TextMessage`); `fetchPrevious()` resolves to `Promise` (thread replies, or top-level messages when `hideReplies(true)` is set); real-time thread messages arrive on the `MessageListener`; all reject with `CometChat.CometChatException` | +| Listeners registered | `MessageListener` via `CometChat.addMessageListener(listenerID, ...)` / `CometChat.removeMessageListener(listenerID)` — callbacks: `onTextMessageReceived`, `onMediaMessageReceived`, `onCustomMessageReceived`; filter to the active thread with `getParentMessageId()` | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview); a parent message ID to thread under | +| Constraints | `fetchPrevious()` returns at most 100 messages per request. Use `hideReplies(true)` on the builder to exclude thread replies and return only top-level messages. Always remove listeners on unmount to avoid memory leaks and duplicate handling | +| Related | [Send a Message](/sdk/javascript/send-message) · [Receive a Message](/sdk/javascript/receive-message) · [Message Filtering](/sdk/javascript/message-filtering) · [Reactions](/sdk/javascript/reactions) | +| Full reference | [`BaseMessage`](/sdk/reference/messages#basemessage) · [`TextMessage`](/sdk/reference/messages#textmessage) · [`MediaMessage`](/sdk/reference/messages#mediamessage) · [`CustomMessage`](/sdk/reference/messages#custommessage) | + + + Messages that are started from a particular message are called Threaded messages or simply threads. Each Thread is attached to a message which is the Parent message for that thread. ## Send Message in a Thread diff --git a/sdk/javascript/upload-files.mdx b/sdk/javascript/upload-files.mdx index 531bbd496..ce4153c54 100644 --- a/sdk/javascript/upload-files.mdx +++ b/sdk/javascript/upload-files.mdx @@ -4,6 +4,23 @@ sidebarTitle: "Upload Files" description: "Upload files directly to storage with per-file progress, remove, and retry through an UploadFileRequest — then send them as one or more media messages with multiple attachments." --- + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Import | `import { CometChat } from "@cometchat/chat-sdk-javascript";` | +| Key methods | `CometChat.createUploadFileRequest(receiverId, receiverType)` · `request.uploadAttachments([{ fileId, file }], listener)` · `request.uploadAttachment(fileId, file, listener)` · `request.getAttachments()` / `request.getAttachmentsByType(type)` · `request.removeAttachment(fileId)` · `request.retryAttachment(fileId)` · `request.clearAll()` · `CometChat.sendMediaMessage(mediaMessage)` · `CometChat.getMaxAttachmentCount()` | +| Key classes | `CometChat.UploadFileRequest` · `CometChat.UploadFileListener` · `CometChat.Attachment` · `CometChat.MediaMessage` · `CometChat.UploadResult` | +| Primary output | `createUploadFileRequest()` returns an `UploadFileRequest` (upload is decoupled from send). Progress and outcomes arrive on the `UploadFileListener` callbacks; each success yields a ready-to-send `Attachment` (with a hosted `url`). `sendMediaMessage()` resolves to `Promise` and rejects with `CometChat.CometChatException` | +| Listeners registered | `UploadFileListener` (per-call, or global via `request.addUploadListener(listener)` / `request.removeUploadListener()`) — callbacks: `onFileProgress(fileId, loaded, total, percent)`, `onFileUploaded(fileId, attachment)`, `onFileError(fileId, error)` (rejected, not retryable), `onFileFailure(fileId, error)` (failed, retryable), `onComplete(result)`. Not registered globally with a string id — it lives for the upload batch | +| Prerequisites | SDK initialized via [`CometChat.init()`](/sdk/javascript/setup-sdk) and a logged-in user via [`CometChat.login()`](/sdk/javascript/authentication-overview); the request `receiverId` / `receiverType` must match the `MediaMessage` you eventually send | +| Constraints | `fileId` is caller-supplied and required (dedup: a repeated `fileId` is silently skipped). Per-file size limit `file.size.max` (default 100 MB) is enforced at upload → `ERR_FILE_SIZE_EXCEEDED` via `onFileError`; attachments-per-message limit `file.count.max` (default 10) is enforced by `sendMediaMessage()` → `ERR_FILE_COUNT_EXCEEDED`. Send from an explicit button, **not** from `onComplete` (which fires on every batch drain). Call `clearAll()` after a successful send | +| Related | [Send a Message](/sdk/javascript/send-message) · [Receive a Message](/sdk/javascript/receive-message) · [Threaded Messages](/sdk/javascript/threaded-messages) · [Error Codes](/sdk/javascript/error-codes) | +| Full reference | [`Attachment`](/sdk/reference/auxiliary#attachment) · [`MediaMessage`](/sdk/reference/messages#mediamessage) · [`CometChatException`](/sdk/reference/auxiliary#cometchatexception) | + + + `CometChat.createUploadFileRequest(receiverId, receiverType)` returns an **`UploadFileRequest`** — the entry point for uploading files **directly to storage** with **per-file progress, success, and failure**. Upload is **decoupled from sending**: each uploaded file yields an [`Attachment`](/sdk/reference/auxiliary#attachment) (carrying a hosted `url`), which you then attach to a [`MediaMessage`](/sdk/reference/messages#mediamessage) and send with [`sendMediaMessage()`](/sdk/javascript/send-message#media-message). A request object is scoped to **one destination** (`receiverId` / `receiverType`) and **one upload batch**. This is the recommended way to build a **multi-attachment composer**: create a request, upload a batch of files, show a progress bar per file, let the user remove or retry individual files, then send them as a single media message with multiple attachments (or split across several). From 6f9b5dc33880393c96d4b7bce10c9e389b305621 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 13 Aug 2026 15:25:49 +0530 Subject: [PATCH 02/63] fixed conflicts --- REST_API_DOCS_AUDIT_REPORT.md | 148 ----------------- flutter-sdk-changes-review.md | 134 --------------- ui-kit/react/campaigns.mdx | 8 + ui-kit/react/components/ai-assistant-chat.mdx | 6 + ui-kit/react/components/call-bubble.mdx | 6 +- ui-kit/react/components/call-buttons.mdx | 2 +- .../collaborative-document-bubble.mdx | 7 + .../collaborative-whiteboard-bubble.mdx | 7 + ui-kit/react/components/conversations.mdx | 152 ++++-------------- .../react/components/flag-message-dialog.mdx | 4 + ui-kit/react/components/group-members.mdx | 14 +- ui-kit/react/components/groups.mdx | 8 +- ui-kit/react/components/message-composer.mdx | 39 ++--- ui-kit/react/components/message-header.mdx | 10 +- ui-kit/react/components/message-list.mdx | 40 ++++- ui-kit/react/components/notification-feed.mdx | 8 + ui-kit/react/components/poll-bubble.mdx | 7 + ui-kit/react/components/reaction-list.mdx | 15 ++ ui-kit/react/components/reactions.mdx | 4 + ui-kit/react/components/search.mdx | 4 + ui-kit/react/components/sticker-bubble.mdx | 7 + ui-kit/react/components/users.mdx | 8 +- ui-kit/react/components/video-bubble.mdx | 4 + ui-kit/react/core-features.mdx | 14 +- ui-kit/react/event-system.mdx | 6 + ui-kit/react/guide-block-unblock-user.mdx | 5 + ui-kit/react/guide-group-chat-setup.mdx | 5 + ui-kit/react/guide-message-privately.mdx | 5 + ui-kit/react/guide-threaded-messages.mdx | 5 + ui-kit/react/plugins/custom-plugin.mdx | 4 +- ui-kit/react/plugins/overview.mdx | 14 +- ui-kit/react/plugins/text-formatters.mdx | 10 +- 32 files changed, 263 insertions(+), 447 deletions(-) delete mode 100644 REST_API_DOCS_AUDIT_REPORT.md delete mode 100644 flutter-sdk-changes-review.md diff --git a/REST_API_DOCS_AUDIT_REPORT.md b/REST_API_DOCS_AUDIT_REPORT.md deleted file mode 100644 index 85a96fd1c..000000000 --- a/REST_API_DOCS_AUDIT_REPORT.md +++ /dev/null @@ -1,148 +0,0 @@ -# CometChat REST API Documentation Audit Report - -**Date:** 2026-04-24 -**Branch:** `docs/restapi-chatapi-ENG-30061-ketan` -**Preview URL:** https://cometchat-22654f5b-docs-restapi-chatapi-eng-30061-ketan.mintlify.app/ -**Pages Scanned:** 3,090 MDX files across 10 product directories -**OAS Files Scanned:** 5 files with 345 total endpoints - ---- - -## Executive Summary - -| Dimension | Score | -| ---------------------- | ---------- | -| Enterprise Readiness | 7.5/10 | -| AI-Agent Friendliness | 7.0/10 | -| AEO Friendliness | 8.5/10 | -| Link Hygiene | 8.0/10 | -| Completeness | 7.5/10 | -| Consistency | 7.0/10 | -| **Overall (weighted)** | **7.5/10** | - -The REST API docs are well-structured with zero orphan pages, zero ghost nav entries, and 100% frontmatter description coverage. The main gaps are in the OAS response schemas (52 untyped `data: object` responses in chat-apis.json), 4 broken redirect destinations, and cross-product consistency in overview page structure. - ---- - -## Product Coverage - -| Product | OAS File | Endpoints | MDX Pages | Guide Pages | Status | -| --------------------- | --------------------- | --------- | --------- | ------------------ | ------ | -| Chat & Messaging | chat-apis.json | 130 | 404 | 26 (notifications) | Active | -| Voice & Video Calling | calls.json | 2 | 207 | — | Active | -| AI Agents | ai-agent-service.json | 68 | 86 | — | Active | -| Moderation | management-apis.json | 141 | 12 | — | Active | -| Data Import | data-import-apis.json | 4 | — | — | Active | - ---- - -## Score Breakdown - -### Enterprise Readiness: 7.5/10 - -All 345 endpoints have operationIds and zero empty example values. Authentication is documented per-product (apikey for Chat, Basic Auth for Management). The main gap is 52 endpoints in chat-apis.json returning `data` as a generic untyped `object` — enterprise SDK codegen and type-safe clients can't infer response structure. 14 endpoints have completely empty response schemas. - -### AI-Agent Friendliness: 7.0/10 - -100% operationId coverage is excellent for AI agent consumption. The `llms.txt` file is published and accessible. However, 35 list endpoints across 3 OAS files lack pagination metadata in response schemas, making it harder for agents to handle paginated results programmatically. The 52 untyped response objects in chat-apis.json are the biggest blocker for AI agent integration. - -### AEO Friendliness: 8.5/10 - -Every REST API MDX file has a frontmatter `description`. The `llms.txt` is published with clear page descriptions. Heading hierarchy is clean across all scanned pages. Overview pages have structured endpoint tables (except AI Agents overview which uses prose instead). No debug markers in REST API pages. - -### Link Hygiene: 8.0/10 - -Zero broken internal links in REST API pages. Zero legacy domain references. Zero orphan or ghost pages. However, 4 redirect destinations point to non-existent files (`/ai-chatbots/ai-bots/bots`, `/ai-chatbots/ai-bots/instructions`, `/widget/wordpress/legacy`, `/widget/html/legacy`). The `flutter-sdk-changes-review.md` file (286 `
` tags fixed in this branch) and 13 files with invalid `mintlify` imports were cleaned up. - -### Completeness: 7.5/10 - -REST API overview pages for Calls and Moderation are comprehensive with endpoint tables, property tables, error handling, and pagination examples. AI Agents overview is lighter — missing a structured endpoint table. The iOS APNs push notification page renders as code-only with no prose introduction. 11 TODO markers remain in iOS UI Kit and React Native notification pages (screenshots and code snippets needed). - -### Consistency: 7.0/10 - -Overview page structure varies across products — Calls and Moderation have full endpoint tables while AI Agents uses prose. Pagination parameter naming varies across OAS files (`perPage`/`count`/`limit`) — this is an API-contract issue, not a docs issue. Code fence formatting was inconsistent (3 vs 4 backtick closings) across 10 JavaScript SDK files — fixed in this branch. Duplicate frontmatter keys were found in 2 files — fixed in this branch. - ---- - -## Issues Found - -### CRITICAL (P0) - -| # | Issue | File/Product | Dimension | Suggested Fix | -| --- | ------------------------------------------------------ | -------------- | ------------------------------ | ------------------------------------------------------------ | -| 1 | 52 endpoints return `data` as untyped generic `object` | chat-apis.json | Enterprise Readiness, AI-Agent | Add typed response schemas with properties for each endpoint | - -### HIGH (P1) - -| # | Issue | File/Product | Dimension | Suggested Fix | -| --- | ---------------------------------------------------------------- | -------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| 2 | 35 list endpoints missing pagination metadata in response schema | chat-apis.json, management-apis.json, ai-agent-service.json | AI-Agent Friendliness | Add `meta`/`pagination` object to list endpoint response schemas | -| 3 | 23 endpoints with empty response schemas | chat-apis.json (14), calls.json (2), ai-agent-service.json (7) | Enterprise Readiness | Define response properties or document as 204 No Content | -| 4 | 4 broken redirect destinations | docs.json redirects | Link Hygiene | Remove or update redirects for `/ai-chatbots/ai-bots/bots`, `/ai-chatbots/ai-bots/instructions`, `/widget/wordpress/legacy`, `/widget/html/legacy` | - -### MEDIUM (P2) - -| # | Issue | File/Product | Dimension | Suggested Fix | -| --- | ------------------------------------------------------- | -------------------------------------------------- | ------------------------- | ------------------------------------------------------------ | -| 5 | AI Agents API overview lacks structured endpoint table | rest-api/ai-agents-apis/overview | Completeness, Consistency | Add endpoint table matching Calls/Moderation overview format | -| 6 | iOS APNs push notification page is code-only | notifications/ios-apns-push-notifications.mdx | Completeness | Add introductory prose, setup steps, and section headers | -| 7 | 11 TODO markers in iOS UI Kit and RN notification pages | ui-kit/ios/_.mdx, notifications/react-native-_.mdx | Completeness | Add missing screenshots and code snippets | - -### LOW (P3) - -| # | Issue | File/Product | Dimension | Suggested Fix | -| --- | -------------------------------------------------------------- | ------------ | -------------------- | ------------------------------------- | -| 8 | `AWSCLIV2.pkg` in repo root (skipped by Mintlify as too large) | Root | Link Hygiene | Add to .gitignore or remove from repo | -| 9 | Calls OAS has only 2 endpoints with empty 400 error schemas | calls.json | Enterprise Readiness | Add error response properties | - ---- - -## Fixes Applied in This Branch - -The following issues were discovered and fixed during this audit session: - -| Fix | Files | Change | -| -------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| Duplicate redirect source | docs.json | Removed duplicate `/notifications/push-notification-extension-overview`, kept assets.cometchat.io destination | -| `
` → `
` | flutter-sdk-changes-review.md | 286 self-closing HTML tags for MDX compatibility | -| Mismatched code fences | 10 MDX files (ios-apns, ios-fcm, 8 JS SDK files) | Fixed ``````` closings to match ` `` ` openings | -| Inline code fences | sdk/javascript/retrieve-users.mdx, send-message.mdx | Expanded single-line code fences to proper multi-line blocks | -| Escaped comment syntax | sdk/javascript/send-message.mdx | Fixed `{/\*` → `{/*` and `\*/}` → `*/}` | -| Duplicate frontmatter keys | sdk/android/changelog.mdx, sdk/flutter/ai-chatbots-overview.mdx | Removed duplicate `description` keys | -| Invalid mintlify imports | 13 MDX files across calls, widget, ai-agents | Removed `import { ... } from 'mintlify'` (components are globally available) | - ---- - -## Prioritized Fix List - -### P0 — Must fix (blocks SDK codegen / AI agent consumption) - -1. Add typed response schemas to 52 chat-apis.json endpoints returning generic `data: object` - -### P1 — Should fix (degrades developer experience) - -1. Add pagination metadata to 35 list endpoint response schemas -2. Define response properties for 23 empty response schemas -3. Fix or remove 4 broken redirect destinations in docs.json - -### P2 — Nice to fix (polish) - -1. Add structured endpoint table to AI Agents API overview page -2. Add prose introduction to iOS APNs push notification page -3. Resolve 11 TODO markers (screenshots, code snippets) - -### P3 — Backlog - -1. Remove `AWSCLIV2.pkg` from repo -2. Add error response schemas to calls.json - ---- - -## Appendix - -- **Total issues:** 9 -- **By severity:** 1 critical, 3 high, 3 medium, 2 low -- **By product:** Chat 3, Calls 1, AI Agents 1, Cross-product 4 -- **Pages with zero issues:** 3,070+ of 3,090 -- **OAS files scanned:** chat-apis.json (130), calls.json (2), data-import-apis.json (4), management-apis.json (141), ai-agent-service.json (68) -- **Branch fixes applied:** 3 commits fixing 27 files total diff --git a/flutter-sdk-changes-review.md b/flutter-sdk-changes-review.md deleted file mode 100644 index 93fd6ab90..000000000 --- a/flutter-sdk-changes-review.md +++ /dev/null @@ -1,134 +0,0 @@ -# Flutter SDK (`sdk/flutter/`) Changes Review - -> **Base:** commit `5e4976de` (state before the improvements branch) -> **Target:** commit `9feb900b` (tip of `docs/flutter-sdk-improvments`) -> **Scope:** `sdk/flutter/*.mdx` only, `sdk/flutter/3.0/` excluded -> **Total:** 62 files modified (+8,176 lines, −16 lines) -> **Commits:** -> - `659f8839` — "feat: made docs more agentic and developer friendly" (added Quick Reference `` blocks, `description` frontmatter, `` blocks, `` blocks, and Next Steps `` navigation to all files) -> - `beb0cc1c` — "docs(flutter): add response and error accordions to SDK docs" (added `` and `` sections after every SDK method call across all files except presenter-mode) -> - `9feb900b` — "docs(flutter): add response and error accordions to presenter mode" (added response/error accordions to the final remaining file) - ---- - -## What Changed Across All Files — Pattern Summary - -Every file received some combination of these five additions: - -### 1. `description` frontmatter (all 62 files) -A one-line SEO description was added to the YAML frontmatter of every file. Example: -```yaml -description: "Get started with the CometChat Flutter SDK to add real-time chat and calling features to your Flutter application." -``` - -### 2. AI Agent Quick Reference `` blocks (all 62 files) -A hidden comment `{/* TL;DR for Agents and Quick Reference */}` followed by an `` block containing copy-paste-ready Dart/YAML code snippets was added at the top of every page, right after the frontmatter. These blocks are designed for both AI agents and developers to quickly understand the page's core functionality without reading the full content. Example from `overview.mdx`: -```dart -// Initialize (run once at app start) -AppSettings appSettings = (AppSettingsBuilder() - ..subscriptionType = CometChatSubscriptionType.allUsers - ..region = "REGION" - ..autoEstablishSocketConnection = true -).build(); - -CometChat.init("APP_ID", appSettings, - onSuccess: (msg) => debugPrint("Init success"), - onError: (e) => debugPrint("Init failed: ${e.message}"), -); -``` - -### 3. Response/Error Accordions (most files — wherever SDK methods exist) -After every SDK method call on the page, two expandable `` sections were added: -- **``** — Documents the success callback return type with a table of fields including Parameter, Type, Description, and Sample Value. For complex objects (User, Group, BaseMessage, Call), every field is listed with realistic sample values. -- **``** — Documents the error callback with `code`, `message`, and `details` fields and sample error values. - -Example Response table fields for `sendMessage()`: -`id`, `metadata`, `receiver`, `editedBy`, `conversationId`, `sentAt`, `receiverUid`, `type`, `readAt`, `deletedBy`, `deliveredAt`, `deletedAt`, `replyCount`, `sender`, `receiverType`, `editedAt`, `parentMessageId`, `readByMeAt`, `category`, `deliveredToMeAt`, `updatedAt`, `text`, `tags`, `unreadRepliesCount`, `mentionedUsers`, `hasMentionedMe`, `reactions`, `moderationStatus`, `quotedMessageId` — plus nested Sender and Receiver User object tables. - -Example Error table: -| Parameter | Type | Description | Sample Value | -|-----------|------|-------------|--------------| -| `code` | string | Error code identifier | `"ERR_CHAT_API_FAILURE"` | -| `message` | string | Human-readable error message | `"SDK initialization failed."` | -| `details` | string | Additional technical details | `"Please verify your App ID and region, then try again."` | - -### 4. `` blocks (select files — where common pitfalls exist) -Warning callouts were added for critical developer pitfalls. Examples: -- `overview.mdx` / `setup.mdx`: *"`CometChat.init()` must be called before any other SDK method. Calling `login()`, `sendMessage()`, or registering listeners before `init()` will fail."* -- `authentication-overview.mdx`: *"Auth Key is for development/testing only. In production, generate Auth Tokens server-side."* -- `delete-message.mdx` / `delete-conversation.mdx` / `delete-group.mdx`: Warnings about permanent/irreversible deletion -- `default-call.mdx`: *"Generate a call token before starting a session"* -- `ai-agents.mdx`: *"Always remove AI Assistant listeners when they're no longer needed (e.g., on widget dispose or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling."* -- `receive-messages.mdx`: Warning about removing message listeners on dispose - -### 5. Next Steps `` navigation (all 62 files) -A `---` horizontal rule followed by a `## Next Steps` heading and a `` with 2–4 `` links was added at the bottom of every page. Each card has a title, icon, href, and description pointing to logically related pages. - ---- - -## Detailed File-by-File Changes - -| File Name | Changes List | Description | -|-----------|-------------|-------------| -| `overview.mdx` | 1. Added `description: "Get started with the CometChat Flutter SDK to add real-time chat and calling features to your Flutter application."`
2. Added Quick Reference `` block containing: `cometchat_sdk: ^4.0.33` install yaml, `CometChat.init()` with `AppSettingsBuilder` code, `CometChat.login()` with Auth Key code, commented `loginWithAuthToken()` alternative, credential source note pointing to Dashboard
3. Added ``: "CometChat.init() must be called before any other SDK method. Calling login(), sendMessage(), or registering listeners before init() will fail."
4. Added Response accordion after `CometChat.init()` — success returns a `String` message: `"Initialization completed successfully"`
5. Added Error accordion after `CometChat.init()` — error fields: `code` (`"ERR_CHAT_API_FAILURE"`), `message` (`"SDK initialization failed."`), `details` (`"Please verify your App ID and region, then try again."`)
6. Added Response accordion after `CometChat.createUser()` — returns a `User` object with 12 fields: `uid`, `name`, `link`, `avatar`, `metadata`, `status` (`"offline"`), `role` (`"default"`), `statusMessage`, `tags`, `hasBlockedMe`, `blockedByMe`, `lastActiveAt`
7. Added Error accordion after `CometChat.createUser()` — error fields: `code` (`"ERR_UID_NOT_FOUND"`), `message`, `details`
8. Added Response accordion after `CometChat.login()` — returns a `User` object with same 12 fields, sample `status` is `"online"`, sample `lastActiveAt` is `1745554700`
9. Added Error accordion after `CometChat.login()` — same error structure
10. Added Next Steps CardGroup with 4 cards: "Setup SDK" (icon: gear, href: `/sdk/flutter/setup`), "Key Concepts" (icon: lightbulb, href: `/sdk/flutter/key-concepts`), "Authentication" (icon: key, href: `/sdk/flutter/authentication-overview`), "Send Messages" (icon: paper-plane, href: `/sdk/flutter/send-message`) | This is the main entry point for the Flutter SDK docs. The Quick Reference block gives developers the complete install → init → login flow in one glance. The `` prevents the #1 integration mistake (calling SDK methods before init). Response accordions document the exact shape of `User` objects returned by `createUser()` and `login()`, including all 12 fields with realistic sample values. Error accordions show the standard `CometChatException` structure (`code`/`message`/`details`) that is consistent across all SDK methods. The Next Steps cards create a guided learning path from overview → setup → auth → messaging. | -| `setup.mdx` | 1. Added `description: "Install and initialize the CometChat Flutter SDK in your application"`
2. Added Quick Reference `` block — same install + init + login code as overview, plus credential source note
3. Added ``: same init-before-other-methods warning
4. Added Response accordion after `CometChat.init()` — `String` success message
5. Added Error accordion after `CometChat.init()` — `code`/`message`/`details`
6. Added Next Steps CardGroup with 2 cards: "Authentication" (icon: key), "Send Messages" (icon: paper-plane) | The setup page is the detailed installation guide (pubspec.yaml, podfile, minSdkVersion, etc.). The Quick Reference duplicates the overview's code block intentionally — developers may land on either page first. Response/Error accordions document what `init()` returns on success/failure so developers know what to expect in their callbacks. | -| `authentication-overview.mdx` | 1. Added `description: "Learn how to authenticate users in your Flutter app using CometChat SDK with Auth Key for development or Auth Token for production."`
2. Added Quick Reference `` block with: `CometChat.login(UID, authKey)` code, `CometChat.loginWithAuthToken(authToken)` code, `CometChat.logout()` code, note about `getLoggedInUser()` to check existing session
3. Added ``: "Auth Key is intended for development/testing only. For production, generate Auth Tokens server-side via the REST API and use loginWithAuthToken()."
4. Added Response accordion after `login()` with Auth Key — `User` object with 12 fields (uid, name, avatar, status=`"online"`, role=`"default"`, lastActiveAt, etc.)
5. Added Error accordion after `login()` with Auth Key — `code` (`"ERR_UID_NOT_FOUND"`), `message`, `details`
6. Added Response accordion after `loginWithAuthToken()` — same `User` object structure
7. Added Error accordion after `loginWithAuthToken()` — same error structure
8. Added Response accordion after `logout()` — `String` success message: `"User logged out successfully"`
9. Added Error accordion after `logout()` — `code`/`message`/`details`
10. Added Next Steps CardGroup with 4 cards: "Send Messages", "Receive Messages", "Key Concepts", "Users" | The auth page now clearly distinguishes between Auth Key (dev) and Auth Token (prod) flows. The `` is a critical security note — shipping Auth Keys in production client code is a common mistake. Each of the three auth methods (login with key, login with token, logout) has its own response/error accordion so developers can see exactly what each returns. | -| `key-concepts.mdx` | 1. Added `description: "Understand the core concepts of CometChat including Dashboard, API keys, users, groups, messages, and conversations."`
2. Added Quick Reference `` block summarizing: CometChat Dashboard purpose, Auth Key vs REST API Key differences (Auth Key = client-side dev, REST API Key = server-side), Users/UID/Auth Token concepts, Groups (GUID, public/private/password types), Messages (text/media/custom/interactive), Conversations (user/group)
3. Added Next Steps CardGroup with 4 cards: "Setup", "Authentication", "Send Messages", "Groups" | The Quick Reference block condenses the entire key-concepts page into a scannable summary. This is especially useful for AI agents that need to understand CometChat's data model quickly. No response/error accordions here since this is a conceptual page with no SDK method calls. | -| `send-message.mdx` | 1. Added `description: "Learn how to send text, media, and custom messages to users and groups using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.sendMessage(textMessage)` code, `CometChat.sendMediaMessage(mediaMessage)` code, `CometChat.sendCustomMessage(customMessage)` code
3. Added ``: "Available via: SDK \| REST API \| UI Kits \| Dashboard"
4. Added ``: "CometChat.init() and CometChat.login() must complete before sending messages."
5. Added Response accordion after `sendMessage()` for text — `BaseMessage` object with 28 fields: `id` (401), `metadata`, `receiver` (nested User object), `editedBy`, `conversationId` (`"cometchat-uid-1_user_cometchat-uid-2"`), `sentAt` (epoch), `receiverUid`, `type` (`"text"`), `readAt`, `deletedBy`, `deliveredAt`, `deletedAt`, `replyCount`, `sender` (nested User object with uid/name/avatar/status/role/tags/etc.), `receiverType` (`"user"`), `editedAt`, `parentMessageId`, `readByMeAt`, `category` (`"message"`), `deliveredToMeAt`, `updatedAt`, `text` (`"messageText"`), `tags`, `unreadRepliesCount`, `mentionedUsers`, `hasMentionedMe`, `reactions`, `moderationStatus`, `quotedMessageId` — plus full nested Sender User object (12 fields) and Receiver User object (12 fields)
6. Added Error accordion after `sendMessage()` for text
7. Added Response accordion after `sendMediaMessage()` — similar `BaseMessage` structure with additional `attachment` field containing `url`, `extension`, `size`, `mimeType`
8. Added Error accordion after `sendMediaMessage()`
9. Added Response accordion after `sendCustomMessage()` — `BaseMessage` with `customData` map field
10. Added Error accordion after `sendCustomMessage()`
11. Added Next Steps CardGroup with 4 cards: "Receive Messages", "Edit Message", "Delete Message", "Threaded Messages" | This is one of the most heavily documented files (+559 lines). The `BaseMessage` response table is the most comprehensive object documentation in the entire SDK docs — 28 top-level fields plus two nested User objects (Sender and Receiver) each with 12 fields. This gives developers complete visibility into what the `onSuccess` callback returns. The nested object tables use anchor links (`#send-text-sender-object`, `#send-text-receiver-object`) for easy navigation. Media message response adds attachment metadata. Custom message response shows the `customData` map structure. | -| `receive-messages.mdx` | 1. Added `description: "Learn how to receive real-time messages and fetch message history using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.addMessageListener()` code showing `onTextMessageReceived`, `onMediaMessageReceived`, `onCustomMessageReceived` callbacks; `MessagesRequestBuilder` with `fetchPrevious()`/`fetchNext()` code; `CometChat.removeMessageListener()` cleanup code
3. Added ``: "Always remove message listeners when they're no longer needed (e.g., on widget dispose). Failing to remove listeners can cause memory leaks and duplicate event handling."
4. Added Response accordion after `fetchPrevious()` — `List` with full BaseMessage object table (28 fields per message, same structure as send-message)
5. Added Error accordion after `fetchPrevious()`
6. Added Response accordion after `fetchNext()` — same `List` structure
7. Added Error accordion after `fetchNext()`
8. Added Response accordions for each real-time listener callback: `onTextMessageReceived` (TextMessage object), `onMediaMessageReceived` (MediaMessage with attachment), `onCustomMessageReceived` (CustomMessage with customData), `onTypingStarted`, `onTypingEnded`, `onMessagesDelivered`, `onMessagesRead`, `onMessageEdited`, `onMessageDeleted`
9. Added Error accordions for listener callbacks
10. Added Next Steps CardGroup with 4 cards: "Send Messages", "Threaded Messages", "Message Filtering", "Delivery Receipts" | The largest change after `default-call.mdx` (+767 lines). Every real-time listener callback now has its own Response accordion documenting the exact object shape that arrives in the callback. This is critical for developers building custom UIs — they need to know exactly which fields are available on `TextMessage` vs `MediaMessage` vs `CustomMessage`. The memory leak warning about removing listeners is a common Flutter pitfall. | -| `edit-message.mdx` | 1. Added `description: "Learn how to edit sent messages in your Flutter app using the CometChat SDK."`
2. Added Quick Reference `` block with: `CometChat.editMessage(textMessage)` code for text, `CometChat.editMessage(mediaMessage)` code for media
3. Added Response accordion after `editMessage()` for text — `BaseMessage` object with `editedAt` populated (non-zero epoch), `editedBy` populated with editor's UID
4. Added Error accordion after `editMessage()` for text
5. Added Response accordion after `editMessage()` for media — same structure with attachment metadata
6. Added Error accordion after `editMessage()` for media
7. Added Next Steps CardGroup with 3 cards: "Delete Message", "Send Messages", "Threaded Messages" | The response accordions specifically highlight the `editedAt` and `editedBy` fields that change when a message is edited — this helps developers understand which fields to check in their UI to show "edited" indicators. | -| `delete-message.mdx` | 1. Added `description: "Learn how to delete messages and handle real-time deletion events in your Flutter app using CometChat SDK."`
2. Added Quick Reference `` block with: `CometChat.deleteMessage(messageId)` code, `onMessageDeleted` listener callback code
3. Added ``: "Deleting a message is permanent and cannot be undone. The message will be removed for all participants in the conversation."
4. Added Response accordion after `deleteMessage()` — `BaseMessage` object with `deletedAt` populated (non-zero epoch), `deletedBy` populated with deleter's UID
5. Added Error accordion after `deleteMessage()`
6. Added Next Steps CardGroup with 3 cards: "Edit Message", "Send Messages", "Receive Messages" | The permanence warning is important — unlike some chat platforms, CometChat's delete is not soft-delete by default. Response accordion highlights `deletedAt` and `deletedBy` fields. | -| `delivery-read-receipts.mdx` | 1. Added `description: "Learn how to implement message delivery and read receipts in your Flutter app using CometChat SDK."`
2. Added Quick Reference `` block with: `CometChat.markAsDelivered(message)` code, `CometChat.markAsRead(message)` code, `CometChat.markAsUnread(message)` code, listener callbacks for `onMessagesDelivered`/`onMessagesRead`
3. Added Response accordion after `markAsDelivered()` — void success (no return value)
4. Added Error accordion after `markAsDelivered()`
5. Added Response accordion after `markAsRead()` — void success
6. Added Error accordion after `markAsRead()`
7. Added Response accordion after `markAsUnread()` — void success
8. Added Error accordion after `markAsUnread()`
9. Added Next Steps CardGroup with 3 cards: "Receive Messages", "Send Messages", "Typing Indicators" | Receipt methods return void on success (no object), so the Response accordions simply confirm "void — no return value". The Error accordions still document the `CometChatException` structure. | -| `typing-indicators.mdx` | 1. Added `description: "Learn how to send and receive typing indicators in your Flutter app using CometChat SDK."`
2. Added Quick Reference `` block with: `CometChat.startTyping(typingIndicator)` code, `CometChat.endTyping(typingIndicator)` code, `onTypingStarted`/`onTypingEnded` listener callbacks
3. Added Next Steps CardGroup with 3 cards: "Send Messages", "Receive Messages", "Delivery Receipts" | No response/error accordions — typing indicator methods are fire-and-forget with no success/error callbacks. Quick reference shows both sending and receiving sides. | -| `threaded-messages.mdx` | 1. Added `description: "Learn how to send, receive, and fetch messages within a thread attached to a parent message in CometChat Flutter SDK."`
2. Added Quick Reference `` block with: send-in-thread code (`textMessage.parentMessageId = 103`), fetch-thread code (`MessagesRequestBuilder()..parentMessageId = 103`), hide-replies code (`..hideReplies = true`)
3. Added Response accordion after `sendMessage()` in thread — `BaseMessage` with `parentMessageId` populated (103)
4. Added Error accordion after `sendMessage()` in thread
5. Added Response accordion after `fetchPrevious()` for thread — `List` with `parentMessageId` on each message
6. Added Error accordion after `fetchPrevious()`
7. Added Response accordion after `fetchNext()` for thread — same structure
8. Added Error accordion after `fetchNext()`
9. Added Next Steps CardGroup with 3 cards: "Send Messages", "Receive Messages", "Message Filtering" | The Quick Reference block shows the three key thread operations in one place: sending into a thread, fetching a thread's messages, and excluding thread replies from the main conversation. Response accordions highlight the `parentMessageId` field that links messages to their thread. | -| `mentions.mdx` | 1. Added `description: "Learn how to mention users in messages and fetch mentioned messages using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: mention in text message code (setting `mentionedUsers` on `TextMessage`), fetch mentioned messages code (`MessagesRequestBuilder()..mentionsWithType`)
3. Added Response accordion after sending message with mentions — `BaseMessage` with `mentionedUsers` array populated, `hasMentionedMe` boolean
4. Added Error accordion
5. Added Response accordion after fetching mentioned messages — `List` with mention metadata
6. Added Error accordion
7. Added Next Steps CardGroup with 3 cards: "Send Messages", "Receive Messages", "Message Filtering" | Response accordions specifically show how `mentionedUsers` array and `hasMentionedMe` boolean appear in the response — developers need this to render @mention UI elements. | -| `reactions.mdx` | 1. Added `description: "Learn how to add, remove, and fetch reactions on messages using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.addReaction(messageId, emoji)` code, `CometChat.removeReaction(messageId, emoji)` code, `CometChat.fetchMessageReactions(messageId)` code
3. Added Response accordion after `addReaction()` — `BaseMessage` with `reactions` array populated
4. Added Error accordion after `addReaction()`
5. Added Response accordion after `removeReaction()` — `BaseMessage` with updated `reactions` array
6. Added Error accordion after `removeReaction()`
7. Added Response accordion after `fetchMessageReactions()` — `List` with fields: `reaction` (emoji string), `count` (number), `reactedByMe` (boolean)
8. Added Error accordion after `fetchMessageReactions()`
9. Added Next Steps CardGroup with 3 cards: "Send Messages", "Receive Messages", "Interactive Messages" | The `fetchMessageReactions()` response introduces a new object type (`ReactionCount`) not seen in other pages — it has `reaction`, `count`, and `reactedByMe` fields. | -| `interactive-messages.mdx` | 1. Added `description: "Learn how to send interactive messages (Form, Card, Scheduler) using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `FormMessage` construction code, `CardMessage` construction code, `SchedulerMessage` construction code
3. Added Response accordion after sending `FormMessage` — `BaseMessage` with `interactiveData` map containing form fields
4. Added Error accordion
5. Added Response accordion after sending `CardMessage` — `BaseMessage` with `interactiveData` containing card layout
6. Added Error accordion
7. Added Next Steps CardGroup with 3 cards: "Send Messages", "Reactions", "Message Filtering" | Interactive messages have a unique `interactiveData` field in the response that contains the form/card/scheduler structure. | -| `transient-messages.mdx` | 1. Added `description: "Learn how to send and receive transient (ephemeral) messages that are not stored in CometChat's database."`
2. Added Quick Reference `` block with: `CometChat.sendTransientMessage(transientMessage)` code, `onTransientMessageReceived` listener callback
3. Added Next Steps CardGroup with 3 cards: "Send Messages", "Typing Indicators", "Real-Time Listeners" | No response/error accordions — transient messages are fire-and-forget. The Quick Reference clarifies that these messages are not persisted. | -| `flag-message.mdx` | 1. Added `description: "Learn how to flag or report messages for moderation in your Flutter app using CometChat SDK."`
2. Added Quick Reference `` block with: `CometChat.flagMessage(message)` code
3. Added Response accordion after `flagMessage()` — success confirmation
4. Added Error accordion after `flagMessage()`
5. Added Next Steps CardGroup with 3 cards: "Delete Message", "AI Moderation", "Extensions" | Flag message is a simple method with a straightforward response. | -| `additional-message-filtering.mdx` | 1. Added `description: "Learn how to use MessagesRequestBuilder to filter and fetch messages with various parameters including pagination, categories, types, tags, and advanced search options in Flutter."`
2. Added Quick Reference `` block with: `MessagesRequestBuilder` examples showing filters by `..categories`, `..types`, `..tags`, `..uid`, `..guid`, `..limit`, `..searchKeyword`, `..hideReplies`, `..hideDeletedMessages`
3. Added Next Steps CardGroup with 4 cards: "Receive Messages", "Send Messages", "Threaded Messages", "Message Structure" | No response/error accordions — this page documents the request builder configuration, not the fetch methods themselves (those are on `receive-messages.mdx`). The Quick Reference is a comprehensive filter cheat sheet. | -| `message-structure-and-hierarchy.mdx` | 1. Added `description: "Understand the message class hierarchy in CometChat Flutter SDK — BaseMessage, TextMessage, MediaMessage, CustomMessage, and InteractiveMessage."`
2. Added Quick Reference `` block summarizing the class hierarchy: `BaseMessage` (parent) → `TextMessage`, `MediaMessage`, `CustomMessage`, `InteractiveMessage` (children), with key fields for each
3. Added Next Steps CardGroup with 4 cards: "Send Messages", "Receive Messages", "Interactive Messages", "Message Filtering" | Conceptual page — no SDK method calls, so no response/error accordions. The Quick Reference gives a class hierarchy overview. | -| `messaging-overview.mdx` | 1. Added `description: "Overview of CometChat's messaging capabilities for Flutter including text, media, custom, and interactive messages."`
2. Added Quick Reference `` block listing all messaging features with links: Send Messages, Receive Messages, Edit/Delete, Threaded Messages, Typing Indicators, Delivery/Read Receipts, Mentions, Reactions, Interactive Messages, Transient Messages, Flag Message
3. Added Next Steps CardGroup with 4 cards: "Send Messages", "Receive Messages", "Threaded Messages", "Reactions" | Index page — the Quick Reference serves as a complete table of contents for the messaging section. | -| `retrieve-conversations.mdx` | 1. Added `description: "Learn how to fetch and paginate through conversations using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `ConversationsRequestBuilder` code showing `..limit`, `..conversationType`, `..withTags`, `..tags` filters; `fetchNext()`/`fetchPrevious()` pagination code
3. Added Response accordion after `fetchNext()` — `List` with fields: `conversationId`, `conversationType` (`"user"`/`"group"`), `lastMessage` (nested BaseMessage), `conversationWith` (nested User or Group object), `unreadMessageCount`, `updatedAt`, `tags`, `lastReadMessageId`
4. Added Error accordion after `fetchNext()`
5. Added Response accordion after `fetchPrevious()` — same structure
6. Added Error accordion after `fetchPrevious()`
7. Added Next Steps CardGroup with 4 cards: "Delete Conversation", "Send Messages", "Retrieve Users", "Retrieve Groups" | The `Conversation` object is a complex nested type — it contains a `lastMessage` (full BaseMessage) and a `conversationWith` (User or Group depending on type). The response tables document all these nested structures. | -| `delete-conversation.mdx` | 1. Added `description: "Learn how to delete user and group conversations from the logged-in user's conversation list using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.deleteConversation(conversationWith, conversationType)` code
3. Added ``: "Deleting a conversation removes it only from the logged-in user's list. The other participant's conversation is not affected. This action cannot be undone."
4. Added Response accordion after `deleteConversation()` — `String` success message
5. Added Error accordion after `deleteConversation()`
6. Added Next Steps CardGroup with 2 cards: "Retrieve Conversations", "Send Messages" | The warning clarifies that conversation deletion is one-sided (only affects the current user) and irreversible. | -| `retrieve-users.mdx` | 1. Added `description: "Learn how to fetch and paginate through users using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `UsersRequestBuilder` code showing `..limit`, `..searchKeyword`, `..status`, `..hideBlockedUsers`, `..roles`, `..tags`, `..uids` filters; `fetchNext()` pagination code
3. Added Response accordion after `fetchNext()` — `List` with 12 fields per user: `uid`, `name`, `link`, `avatar`, `metadata`, `status`, `role`, `statusMessage`, `tags`, `hasBlockedMe`, `blockedByMe`, `lastActiveAt`
4. Added Error accordion after `fetchNext()`
5. Added Next Steps CardGroup with 3 cards: "Block Users", "User Presence", "User Management" | The User object table is reused across many pages (login, send-message, etc.) but this is the canonical reference for the full User object shape. | -| `user-management.mdx` | 1. Added `description: "Learn how to create and update users using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.createUser(user, authKey)` code, `CometChat.updateUser(user)` code
3. Added Response accordion after `createUser()` — `User` object (12 fields)
4. Added Error accordion after `createUser()`
5. Added Response accordion after `updateUser()` — `User` object (12 fields)
6. Added Error accordion after `updateUser()`
7. Added Next Steps CardGroup with 3 cards: "Retrieve Users", "Block Users", "User Presence" | Both user management methods return the full User object on success. | -| `user-presence.mdx` | 1. Added `description: "Learn how to track user online/offline status in real-time using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.addUserListener()` code showing `onUserOnline`/`onUserOffline` callbacks
3. Added Next Steps CardGroup with 3 cards: "Retrieve Users", "User Management", "Real-Time Listeners" | No response/error accordions — presence is received via listeners, not method calls. | -| `users-overview.mdx` | 1. Added `description: "Overview of CometChat's user management capabilities for Flutter."`
2. Added Quick Reference `` block listing: Retrieve Users, User Management, Block Users, User Presence with links
3. Added Next Steps CardGroup with 4 cards | Index page for the Users section. | -| `block-users.mdx` | 1. Added `description: "Learn how to block and unblock users in your Flutter app using the CometChat SDK to manage user interactions and privacy."`
2. Added Quick Reference `` block with: `CometChat.blockUsers(uids)` code, `CometChat.unblockUsers(uids)` code, `BlockedUsersRequestBuilder` with `fetchNext()` code
3. Added Response accordion after `blockUsers()` — `Map` showing success/failure per UID
4. Added Error accordion after `blockUsers()`
5. Added Response accordion after `unblockUsers()` — same Map structure
6. Added Error accordion after `unblockUsers()`
7. Added Response accordion after `fetchNext()` for blocked users — `List` (12 fields per user)
8. Added Error accordion after `fetchNext()`
9. Added Next Steps CardGroup with 3 cards: "Retrieve Users", "User Management", "User Presence" | The `blockUsers()`/`unblockUsers()` methods return a `Map` (not a simple success string) — the response accordion documents this unique return type. | -| `create-group.mdx` | 1. Added `description: "Learn how to create public, private, and password-protected groups using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `Group` constructor code for public/private/password types, `CometChat.createGroup(group)` code
3. Added Response accordion after `createGroup()` — `Group` object with 15+ fields: `guid`, `name`, `type` (`"public"`/`"private"`/`"password"`), `icon`, `description`, `owner`, `metadata`, `tags`, `membersCount`, `createdAt`, `updatedAt`, `hasJoined`, `scope`, `joinedAt`, `conversationId`
4. Added Error accordion after `createGroup()`
5. Added Next Steps CardGroup with 3 cards: "Join Group", "Retrieve Groups", "Group Members" | The Group object table is the canonical reference for group data — 15+ fields including `membersCount`, `hasJoined`, `scope`, and `conversationId`. | -| `join-group.mdx` | 1. Added `description: "Learn how to join public and password-protected groups using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.joinGroup(guid, groupType, password)` code
3. Added Response accordion after `joinGroup()` — `Group` object (same 15+ fields)
4. Added Error accordion after `joinGroup()`
5. Added Next Steps CardGroup with 3 cards: "Leave Group", "Retrieve Group Members", "Create Group" | Response shows the Group object with `hasJoined` now `true` and `scope` set to `"participant"`. | -| `leave-group.mdx` | 1. Added `description: "Learn how to leave a group using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.leaveGroup(guid)` code
3. Added Response accordion after `leaveGroup()` — `String` success message
4. Added Error accordion after `leaveGroup()`
5. Added Next Steps CardGroup with 3 cards: "Join Group", "Delete Group", "Retrieve Groups" | Simple method — returns success string on leave. | -| `delete-group.mdx` | 1. Added `description: "Learn how to permanently delete a group in CometChat using the Flutter SDK. Only group admins can delete groups."`
2. Added Quick Reference `` block with: `CometChat.deleteGroup(guid)` code
3. Added ``: "Only the group admin can delete a group. Deleting a group is permanent and removes all messages and members."
4. Added Response accordion after `deleteGroup()` — `String` success message
5. Added Error accordion after `deleteGroup()`
6. Added Next Steps CardGroup with 3 cards: "Create Group", "Retrieve Groups", "Leave Group" | The admin-only + permanent deletion warning is critical context for developers. | -| `update-group.mdx` | 1. Added `description: "Learn how to update group details using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.updateGroup(group)` code
3. Added Response accordion after `updateGroup()` — `Group` object (15+ fields) with updated values
4. Added Error accordion after `updateGroup()`
5. Added Next Steps CardGroup with 3 cards: "Create Group", "Retrieve Groups", "Group Members" | Response shows the updated Group object. | -| `transfer-group-ownership.mdx` | 1. Added `description: "Learn how to transfer group ownership to another member using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.transferOwnership(guid, uid)` code
3. Added Response accordion after `transferOwnership()` — `String` success message
4. Added Error accordion after `transferOwnership()`
5. Added Next Steps CardGroup with 3 cards: "Group Members", "Update Group", "Change Member Scope" | Simple method — returns success string. | -| `retrieve-groups.mdx` | 1. Added `description: "Learn how to fetch and paginate through groups using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `GroupsRequestBuilder` code showing `..limit`, `..searchKeyword`, `..joinedOnly`, `..tags`, `..withTags` filters; `fetchNext()` code
3. Added Response accordion after `fetchNext()` — `List` (15+ fields per group)
4. Added Error accordion after `fetchNext()`
5. Added Next Steps CardGroup with 3 cards: "Create Group", "Join Group", "Group Members" | Group retrieval response documents the full Group object for each item in the list. | -| `retrieve-group-members.mdx` | 1. Added `description: "Learn how to fetch and paginate through group members using the CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `GroupMembersRequestBuilder("GROUP_ID")` code showing `..limit`, `..scopes` (admin/moderator/participant) filters; `fetchNext()` code
3. Added ``: "Available via: SDK \| REST API \| UI Kits"
4. Simplified intro paragraph — removed redundant sentence about `GroupMembersRequestBuilder`
5. Added Response accordion after `fetchNext()` — `List` with 14 fields: all 12 User fields plus `scope` (`"admin"`/`"moderator"`/`"participant"`) and `joinedAt` (epoch timestamp)
6. Added Error accordion after `fetchNext()`
7. Added Next Steps CardGroup with 3 cards: "Add Members", "Kick Member", "Change Scope" | `GroupMember` extends `User` with two additional fields (`scope` and `joinedAt`) — the response table documents all 14 fields. | -| `group-add-members.mdx` | 1. Added `description: "Learn how to add members to a group using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.addMembersToGroup(guid, members, bannedMembers)` code
3. Added Response accordion after `addMembersToGroup()` — `Map` showing success/failure per member UID
4. Added Error accordion
5. Added Next Steps CardGroup with 3 cards: "Retrieve Group Members", "Kick Member", "Change Scope" | The Map response type is unique — it maps each member UID to a success/failure status string. | -| `group-change-member-scope.mdx` | 1. Added `description: "Learn how to change a group member's scope (role) using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.changeMemberScope(guid, uid, scope)` code showing scope values: `CometChatMemberScope.admin`, `.moderator`, `.participant`
3. Added Response accordion — `String` success message
4. Added Error accordion
5. Added Next Steps CardGroup with 3 cards: "Retrieve Group Members", "Add Members", "Transfer Ownership" | Quick Reference shows all three scope enum values. | -| `group-kick-member.mdx` | 1. Added `description: "Learn how to kick, ban, and unban group members using CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.kickGroupMember(guid, uid)` code, `CometChat.banGroupMember(guid, uid)` code, `CometChat.unbanGroupMember(guid, uid)` code
3. Added Response accordion after `kickGroupMember()` — `String` success message
4. Added Error accordion after `kickGroupMember()`
5. Added Response accordion after `banGroupMember()` — `String` success message
6. Added Error accordion after `banGroupMember()`
7. Added Response accordion after `unbanGroupMember()` — `String` success message
8. Added Error accordion after `unbanGroupMember()`
9. Added Next Steps CardGroup with 3 cards: "Retrieve Group Members", "Add Members", "Change Scope" | All three member moderation methods documented with response/error. | -| `groups-overview.mdx` | 1. Added `description: "Overview of CometChat's group management capabilities for Flutter."`
2. Added Quick Reference `` block listing: Create Group, Join Group, Leave Group, Delete Group, Update Group, Transfer Ownership, Retrieve Groups, Retrieve Group Members, Add Members, Change Scope, Kick/Ban Members with links
3. Added Next Steps CardGroup with 4 cards | Index page for the Groups section. | -| `default-call.mdx` | 1. Added `description: "Implement complete calling workflow with ringing functionality including incoming/outgoing call UI, call acceptance, rejection, and cancellation in your Flutter app."`
2. Added Quick Reference `` block with: `CometChat.initiateCall(call)` code, `CometChat.acceptCall(sessionId)` code, `CometChat.rejectCall(sessionId, status)` code with `CometChatCallStatus.rejected`/`.cancelled`/`.busy`, `CometChat.endCall(sessionId)` code
3. Added ``: "You must generate a call token using `CometChatCalls.generateToken()` before starting a call session with `CometChatCalls.startSession()`."
4. Added Response accordion after `initiateCall()` — `Call` object with 28+ fields: all BaseMessage fields (id, metadata, receiver, sender, conversationId, sentAt, type, category, etc.) PLUS call-specific fields: `sessionId` (`"v1.us.1.xxxxxxxx"`), `callStatus` (`"initiated"`), `action` (`"initiated"`), `callInitiator` (nested User object), `callReceiver` (nested User object), `initiatedAt` (epoch), `joinedAt` (epoch) — plus nested Sender, Receiver, CallInitiator, and CallReceiver User object tables (12 fields each)
5. Added Error accordion after `initiateCall()`
6. Added Response accordion after `acceptCall()` — `Call` object with `callStatus` = `"ongoing"`, `action` = `"accepted"`
7. Added Error accordion after `acceptCall()`
8. Added Response accordion after `rejectCall()` (rejected) — `Call` object with `callStatus` = `"rejected"`, `action` = `"rejected"`
9. Added Error accordion after `rejectCall()` (rejected)
10. Added Response accordion after `rejectCall()` (cancelled by initiator) — `Call` object with `callStatus` = `"cancelled"`, `action` = `"cancelled"`
11. Added Error accordion after `rejectCall()` (cancelled)
12. Added Response accordion after `endCall()` — `Call` object with `callStatus` = `"ended"`, `action` = `"ended"`
13. Added Error accordion after `endCall()`
14. Added Response accordion after `CometChatCalls.startSession()` — `Widget?` representing the call UI to embed in your screen
15. Added Error accordion after `startSession()`
16. Added Next Steps CardGroup with 3 cards: "Direct Call", "Standalone Calling", "Call Logs" | This is the single largest file change (+876 lines). The `Call` object extends `BaseMessage` with 7 additional call-specific fields (`sessionId`, `callStatus`, `action`, `callInitiator`, `callReceiver`, `initiatedAt`, `joinedAt`). Each call lifecycle state (initiated, ongoing, rejected, cancelled, ended) has its own Response accordion showing the exact `callStatus` and `action` values for that state — this is critical for developers building custom call UIs who need to know which status values to check. The `startSession()` response is unique — it returns a Flutter `Widget?` that developers embed in their screen to show the call interface. | -| `direct-call.mdx` | 1. Added `description: "Implement direct calling without ringing functionality — generate a token and start a call session directly."`
2. Added Quick Reference `` block with: `CometChatCalls.generateToken(sessionId, userAuthToken)` code, `CometChatCalls.startSession(callToken, callSettings)` code with `CallSettingsBuilder` showing `..enableDefaultLayout`, `..listener`
3. Added Response accordion after `generateToken()` — `String` call token
4. Added Error accordion after `generateToken()`
5. Added Response accordion after `startSession()` — `Widget?` call UI widget
6. Added Error accordion after `startSession()`
7. Added Next Steps CardGroup with 3 cards: "Default Call", "Standalone Calling", "Recording" | Direct calling skips the ringing flow — the Quick Reference shows the simplified two-step process (generate token → start session). | -| `standalone-calling.mdx` | 1. Added `description: "Implement standalone calling that works independently of CometChat's messaging infrastructure."`
2. Added Quick Reference `` block with: standalone `CometChatCalls.init()` code, `generateToken()` code, `startSession()` code
3. Added Response accordion after `generateToken()` — `String` call token
4. Added Error accordion
5. Added Response accordion after `startSession()` — `Widget?` call UI widget
6. Added Error accordion
7. Added Next Steps CardGroup with 3 cards: "Default Call", "Direct Call", "Call Logs" | Standalone calling is for apps that only need calling (no chat). The Quick Reference shows the independent init flow. | -| `calling-setup.mdx` | 1. Added `description: "Learn how to install and initialize the CometChat Calls SDK for Flutter to enable voice and video calling in your application."`
2. Added Quick Reference `` block with: `cometchat_calls_sdk: ^4.0.x` install yaml, `CometChatCalls.init(callAppSettings)` code with `CallAppSettingsBuilder` showing `..appId`, `..region`
3. Added Response accordion after `CometChatCalls.init()` — `String` success message: `"CometChat Calls SDK initialized successfully"`
4. Added Error accordion after `CometChatCalls.init()`
5. Added Next Steps CardGroup with 3 cards: "Default Call", "Direct Call", "Standalone Calling" | The Calls SDK has its own separate init method (`CometChatCalls.init()`) distinct from the main SDK's `CometChat.init()`. | -| `calling-overview.mdx` | 1. Added `description: "Implement voice and video calling in your Flutter application with CometChat's calling SDK, supporting ringing calls, direct calls, and standalone calling."`
2. Added Quick Reference `` block summarizing three calling modes: Default Calling (with ringing, requires chat SDK), Direct Calling (no ringing, requires chat SDK), Standalone Calling (independent, no chat SDK needed) — with use-case guidance for each
3. Added Next Steps CardGroup with 4 cards: "Calling Setup", "Default Call", "Direct Call", "Standalone Calling" | The Quick Reference is a decision guide — helps developers choose between the three calling modes based on their use case. | -| `call-logs.mdx` | 1. Added `description: "Learn how to fetch and manage call logs in your Flutter application using CometChat's Call SDK, including filtering by call type, status, and direction."`
2. Added Quick Reference `` block with: `CallLogRequestBuilder` code showing `..limit`, `..callType`, `..callStatus`, `..callDirection` filters; `fetchNext()`/`fetchPrevious()` code; `CometChatCalls.getCallDetails(sessionId)` code
3. Added Response accordion after `fetchNext()` — `List` with 10+ fields: `sessionId`, `callType` (`"audio"`/`"video"`), `callStatus` (`"initiated"`/`"ongoing"`/`"ended"`/`"cancelled"`/`"rejected"`/`"busy"`/`"unanswered"`), `callDirection` (`"incoming"`/`"outgoing"`), `initiator` (User object), `receiver` (User object), `initiatedAt`, `endedAt`, `duration`, `participants`
4. Added Error accordion after `fetchNext()`
5. Added Response accordion after `fetchPrevious()` — same structure
6. Added Error accordion after `fetchPrevious()`
7. Added Response accordion after `getCallDetails()` — `List` for a specific session
8. Added Error accordion after `getCallDetails()`
9. Added Next Steps CardGroup with 3 cards: "Default Call", "Recording", "Presenter Mode" | The `CallLog` object is distinct from the `Call` object — it's a historical record with `duration`, `endedAt`, and `participants` fields not present on the real-time `Call` object. | -| `recording.mdx` | 1. Added `description: "Learn how to enable and manage call recording in your Flutter app using CometChat's Calls SDK."`
2. Added Quick Reference `` block with: recording configuration in `CallSettingsBuilder` (`..enableRecording`), fetch recordings code
3. Added Response accordion after fetching recordings — recording object with `recordingUrl`, `recordingDuration`, `startedAt`, `endedAt`
4. Added Error accordion
5. Added Next Steps CardGroup with 3 cards: "Call Logs", "Default Call", "Presenter Mode" | Recording response includes the `recordingUrl` for playback/download. | -| `presenter-mode.mdx` | 1. Added `description: "Learn how to implement presenter mode in your Flutter app for webinars, online classes, and broadcast-style calling experiences with CometChat."`
2. Added Quick Reference `` block with: `PresentationSettingsBuilder` code showing `..enableDefaultLayout`, `..isPresenter = true` (presenter) and `..isPresenter = false` (viewer); `CometChatCalls.joinPresentation(callToken, settings)` code for both roles
3. Added Response accordion after `joinPresentation()` — `Widget?` representing the presentation UI, documented as: "A Flutter widget containing the presentation UI. Display this widget in your screen to show the presentation interface."
4. Added Error accordion after `joinPresentation()` — `code` (`"ERR_CHAT_API_FAILURE"`), `message` (`"Failed to start the presentation session."`), `details` (`"The call token provided is invalid or expired."`)
5. Added Next Steps CardGroup with 3 cards: "Default Call", "Recording", "Video View Customisation" | This was the final file updated (commit `9feb900b`). The Quick Reference shows both presenter and viewer code side-by-side so developers can see the `isPresenter` flag difference. | -| `video-view-customisation.mdx` | 1. Added `description: "Learn how to customize the video view in CometChat calls for Flutter."`
2. Added Quick Reference `` block with: video view customization code
3. Added Next Steps CardGroup with 3 cards: "Presenter Mode", "Default Call", "Recording" | No response/error accordions — this page covers UI customization, not SDK method calls. | -| `real-time-listeners.mdx` | 1. Added `description: "Complete reference for all real-time event listeners in the CometChat Flutter SDK."`
2. Added Quick Reference `` block listing all 5 listener types with their key callbacks: `MessageListener` (onTextMessageReceived, onMediaMessageReceived, onCustomMessageReceived, onMessageEdited, onMessageDeleted, onMessagesDelivered, onMessagesRead, onTypingStarted, onTypingEnded, onTransientMessageReceived), `UserListener` (onUserOnline, onUserOffline), `GroupListener` (onGroupMemberJoined, onGroupMemberLeft, onGroupMemberKicked, onGroupMemberBanned, onGroupMemberUnbanned, onGroupMemberScopeChanged, onMemberAddedToGroup), `CallListener` (onIncomingCallReceived, onOutgoingCallAccepted, onOutgoingCallRejected, onIncomingCallCancelled), `ConnectionListener` (onConnected, onConnecting, onDisconnected, onFeatureThrottled)
3. Added Next Steps CardGroup with 3 cards: "Receive Messages", "Connection Status", "Login Listeners" | The Quick Reference is a comprehensive callback catalog — developers can scan all available listener callbacks in one place without reading the full page. | -| `login-listeners.mdx` | 1. Added `description: "Learn how to handle login and logout state changes using LoginListener in CometChat Flutter SDK."`
2. Added Quick Reference `` block with: `CometChat.addLoginListener()` code showing `onLoginSuccess`, `onLoginFailure`, `onLogoutSuccess`, `onLogoutFailure` callbacks
3. Added Next Steps CardGroup with 3 cards: "Authentication", "Real-Time Listeners", "Connection Status" | Login listeners help developers react to auth state changes (e.g., auto-redirect on logout). | -| `connection-status.mdx` | 1. Added `description: "Monitor real-time WebSocket connection status with CometChat SDK using ConnectionListener callbacks and getConnectionStatus method."`
2. Added Quick Reference `` block with: `CometChat.addConnectionListener()` code showing `onConnected`, `onConnecting`, `onDisconnected`, `onFeatureThrottled` callbacks; `CometChat.getConnectionStatus()` code returning `CometChatConnectionStatus.connected`/`.connecting`/`.disconnected`
3. Added Next Steps CardGroup with 3 cards: "Connection Behaviour", "Real-Time Listeners", "Login Listeners" | The Quick Reference shows both the listener approach (reactive) and the `getConnectionStatus()` approach (polling) for monitoring connection state. | -| `connection-behaviour.mdx` | 1. Added `description: "Understand how CometChat SDK manages WebSocket connections in auto and manual modes, including background behavior and reconnection handling."`
2. Added Quick Reference `` block comparing Auto Mode (default — SDK manages connections automatically) vs Manual Mode (`autoEstablishSocketConnection = false` — developer controls `connect()`/`disconnect()`/`ping()`)
3. Added Response accordion after `CometChat.connect()` — `String` success message
4. Added Error accordion after `CometChat.connect()`
5. Added Response accordion after `CometChat.disconnect()` — `String` success message
6. Added Error accordion after `CometChat.disconnect()`
7. Added Response accordion after `CometChat.ping()` — `String` success message
8. Added Error accordion after `CometChat.ping()`
9. Added Next Steps CardGroup with 3 cards: "Connection Status", "Real-Time Listeners", "Setup" | The auto vs manual mode comparison in the Quick Reference is a key decision point for developers — most should use auto mode, but apps with specific background requirements may need manual mode. | -| `session-timeout.mdx` | 1. Added `description: "Learn how to configure session timeout behavior in CometChat Flutter SDK."`
2. Added Quick Reference `` block with: session timeout configuration code
3. Added Next Steps CardGroup with 3 cards: "Authentication", "Connection Behaviour", "Login Listeners" | No response/error accordions — session timeout is a configuration, not a method call. | -| `rate-limits.mdx` | 1. Added `description: "Understand the API rate limits for CometChat Flutter SDK operations."`
2. Added Quick Reference `` block summarizing rate limit categories and their values (messages per second, API calls per minute, etc.)
3. Added Next Steps CardGroup with 3 cards: "Send Messages", "Retrieve Conversations", "Setup" | The Quick Reference gives developers a quick view of rate limits without reading the full table. | -| `advanced-overview.mdx` | 1. Added `description: "Advanced SDK features including connection management, real-time listeners, and login state handling for Flutter applications."`
2. Added Quick Reference `` block listing 4 advanced features with one-line descriptions and links: Connection Status (monitor SDK connection state), Connection Behaviour (understand connection lifecycle), Login Listeners (handle login state changes), Real-Time Listeners (all event listeners reference)
3. Added Next Steps CardGroup with 4 cards: "Connection Status", "Real-Time Listeners", "Login Listeners", "Connection Behaviour" | Index page for the Advanced section. | -| `resources-overview.mdx` | 1. Added `description` frontmatter
2. Added Quick Reference `` block listing resource topics
3. Added Next Steps CardGroup | Index page for the Resources section. | -| `flutter-overview.mdx` | 1. Added `description` frontmatter
2. Added Quick Reference `` block with high-level SDK capabilities: real-time messaging, voice/video calling, user/group management, typing indicators, read receipts, file sharing, reactions, mentions, interactive messages, AI features
3. Added Next Steps CardGroup with 4 cards: "Overview/Setup", "Key Concepts", "Authentication", "Send Messages" | Top-level Flutter SDK overview — the Quick Reference gives a feature checklist. | -| `upgrading-from-v3-guide.mdx` | 1. Added `description: "Guide for migrating your Flutter app from CometChat SDK v3 to v4."`
2. Added Quick Reference `` block summarizing key v3→v4 breaking changes and migration steps
3. Added Next Steps CardGroup with 3 cards: "Setup", "Authentication", "Key Concepts" | The Quick Reference gives a scannable migration checklist. | -| `ai-agents.mdx` | 1. Added `description: "Learn how to integrate AI Agents in your Flutter app to enable intelligent, automated interactions that process user messages, trigger tools, and respond with contextually relevant information."`
2. Added Quick Reference `` block with: `CometChat.addAIAssistantListener("LISTENER_ID", AIAssistantListener(onAIAssistantEventReceived: (event) {}))` code, `CometChat.addMessageListener("LISTENER_ID", MessageListener(onAIAssistantMessageReceived: (msg) {}, onAIToolResultReceived: (result) {}))` code, `CometChat.removeAIAssistantListener("LISTENER_ID")` cleanup code
3. Added ``: "Available via: SDK \| REST API \| UI Kits \| Dashboard"
4. Added ``: "Always remove AI Assistant listeners when they're no longer needed (e.g., on widget dispose or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling."
5. Added Next Steps CardGroup with 3 cards: "AI Moderation", "AI Chatbots", "Extensions" | The Quick Reference shows both the AI-specific listener (`AIAssistantListener`) and the message listener callbacks for AI events (`onAIAssistantMessageReceived`, `onAIToolResultReceived`). The memory leak warning is especially important for AI listeners since they may be added in multiple screens. | -| `ai-moderation.mdx` | 1. Added `description: "Learn how to implement AI-powered content moderation in your Flutter app using CometChat SDK to automatically review messages for inappropriate content."`
2. Added Quick Reference `` block with: moderation check code showing `message.metadata["@injected"]["extensions"]["ai-moderation"]` path, status values (`"approved"`, `"pending"`, `"rejected"`), real-time listener for moderation status updates
3. Added Response accordion after sending a moderated message — `BaseMessage` with `metadata` containing nested `@injected.extensions.ai-moderation` object with fields: `status` (`"pending"`), `confidence` (number), `categories` (array of flagged categories)
4. Added Error accordion
5. Added Response accordion for real-time moderation status update — same metadata structure with `status` changed to `"approved"` or `"rejected"`
6. Added Error accordion
7. Added Next Steps CardGroup with 4 cards: "AI Agents", "AI Chatbots", "Send Messages", "Extensions" | The moderation metadata path (`@injected.extensions.ai-moderation`) is deeply nested — the Response accordion documents the exact path developers need to access moderation results. The two Response accordions show the initial "pending" state and the final "approved"/"rejected" state. | -| `ai-chatbots-overview.mdx` | 1. Added `description: "Configure AI-powered chatbots to provide automated assistance and maintain conversational momentum in your Flutter app."`
2. Added Quick Reference `` block summarizing: chatbot configuration via Dashboard, chatbot types (rule-based, AI-powered), integration with messaging flow
3. Added Next Steps CardGroup with 4 cards: "AI Agents", "AI Moderation", "AI User Copilot", "Extensions" | Index page for AI chatbots — no SDK method calls, so no response/error accordions. | -| `extensions-overview.mdx` | 1. Added `description: "Explore CometChat extensions that add enhanced functionality to your Flutter chat application"`
2. Added Quick Reference `` block listing all extension categories: User Experience (Pin message, Link preview, Thumbnails, Voice transcription), User Engagement (Polls, Reactions, Mentions, Message translation, Stickers), Collaboration (Whiteboard, Collaborative documents), Notifications (Push, Email, SMS), Moderation (Content filtering, Profanity detection), Security (Disappearing messages, End-to-end encryption) — with link to full Extensions Overview
3. Added ``: "Available via: SDK \| REST API \| UI Kits"
4. Added Next Steps CardGroup with 3 cards: "AI Features", "Webhooks", "Setup" | The Quick Reference is a comprehensive extension catalog organized by category — developers can quickly find which extension they need. | -| `webhooks-overview.mdx` | 1. Added `description: "Configure server-side webhooks to receive real-time notifications for messages, users, groups, calls, and moderation events in your Flutter application."`
2. Added Quick Reference `` block with: setup requirements (HTTPS endpoint, publicly accessible URL, POST method with `application/json`, return HTTP 200 OK), event categories (Messages: `message_sent`/`message_edited`/`message_deleted`/`message_read_receipt`; Users: `user_blocked`/`user_unblocked`/`user_connection_status_changed`; Groups: `group_created`/`group_member_added`/`group_member_left`; Calls: `call_initiated`/`call_started`/`call_ended`/`recording_generated`; Moderation: `moderation_engine_approved`/`moderation_engine_blocked`), configuration link to Dashboard
3. Added ``: "Webhooks are configured at the application level through the CometChat Dashboard, not within the Flutter SDK. The SDK handles real-time events via listeners, while webhooks deliver events to your backend server."
4. Added Next Steps CardGroup with 3 cards: "Extensions", "Real-Time Listeners", "AI Agents" | The Quick Reference lists all webhook event names — this is valuable for backend developers who need to know which events to listen for. The `` clarifies the SDK vs webhook distinction (SDK = client-side listeners, webhooks = server-side HTTP callbacks). | diff --git a/ui-kit/react/campaigns.mdx b/ui-kit/react/campaigns.mdx index c8ac622c1..42ed7ca36 100644 --- a/ui-kit/react/campaigns.mdx +++ b/ui-kit/react/campaigns.mdx @@ -55,6 +55,10 @@ The Cards library is a **pure renderer**: It does not execute actions, manage message state, or call any SDK methods. When users click interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc. + +When wiring the `onAction` callback, handle each action type (`openUrl`, `chatWithUser`, `chatWithGroup`, `sendMessage`, and the rest) explicitly in your own code. For the recommended pattern of turning card actions into app behavior, see [Event System — Card Actions](/ui-kit/react/event-system#card-actions). + + ### Card Schema JSON Example ```json @@ -151,6 +155,10 @@ You don't need to interact with the Cards library directly when using `CometChat ## Handling Push Notifications for Campaigns + +**Prerequisite: Push Notifications must be configured first.** The tracking calls below only apply once you have set up a push provider (**FCM** or **Web Push**) and are receiving campaign pushes. Start with [Web Push Notifications setup](/notifications/web-push-notifications), and see the [Push Notifications overview](/notifications/push-overview) for provider options and the delivery pipeline. + + When a campaign push notification arrives via Web Push or FCM, you should: 1. **Report delivery** — Call `CometChat.markPushNotificationDelivered()` when the notification is received diff --git a/ui-kit/react/components/ai-assistant-chat.mdx b/ui-kit/react/components/ai-assistant-chat.mdx index ed52d939e..4ff89e674 100644 --- a/ui-kit/react/components/ai-assistant-chat.mdx +++ b/ui-kit/react/components/ai-assistant-chat.mdx @@ -93,6 +93,12 @@ description: "AI agent chat interface with streaming responses, suggested messag `CometChatAIAssistantChat` is an AI agent chat interface. It renders a full chat experience with streaming responses, suggested message pills, tool calling support, and a conversation history sidebar. Pass a `CometChat.User` representing the AI assistant and the component handles the rest — message threading, streaming display, and composer integration. + +**Prerequisite: an AI Agent must be configured in the CometChat Dashboard.** This component renders nothing useful without one. `CometChatAIAssistantChat` requires an **AI Agent set up in the Dashboard as a `CometChat.User`**, and the `user` prop must be that agent's user entity. The agent's replies, tool execution, and metadata — including `suggestedMessages`, `greetingMessage`, `introductoryMessage`, and tool configuration — are defined when you create the agent. + +Set up the agent with the [AI Agent Builder](/ai-agents/agent-builder/overview). + + **1:1 and group conversations.** AI Agents work in both one-on-one and group conversations. In a 1:1 chat, the end user talks directly with the agent user. In a group, the agent participates as a member — its messages (including cards) are delivered and attributed like any other member's message. If the group contains only one user and one agent, the agent responds automatically. In groups with more than two members, the agent only responds when @mentioned. diff --git a/ui-kit/react/components/call-bubble.mdx b/ui-kit/react/components/call-bubble.mdx index 8a5bd8541..393b9c7cd 100644 --- a/ui-kit/react/components/call-bubble.mdx +++ b/ui-kit/react/components/call-bubble.mdx @@ -92,7 +92,11 @@ Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user. ### onJoinClick -Callback when the Join button is clicked. Receives the session ID. +Callback when the Join button is clicked. Receives the session ID. Empty by default — you must start or join the call session yourself. + + +See [Calling Integration](/ui-kit/react/calling-integration) for how to start or join a call session. + | | | | --- | --- | diff --git a/ui-kit/react/components/call-buttons.mdx b/ui-kit/react/components/call-buttons.mdx index 33e323647..b9c9d8e8a 100644 --- a/ui-kit/react/components/call-buttons.mdx +++ b/ui-kit/react/components/call-buttons.mdx @@ -417,7 +417,7 @@ All props are optional. Sorted alphabetically. ### callSettingsBuilder -Builder function for customizing the ongoing call settings. +Builder function for customizing the ongoing call settings, built via `callSettings`. See [Calling Integration](/ui-kit/react/calling-integration) for call-settings setup. | | | | --- | --- | diff --git a/ui-kit/react/components/collaborative-document-bubble.mdx b/ui-kit/react/components/collaborative-document-bubble.mdx index daeeef335..a21f5ea41 100644 --- a/ui-kit/react/components/collaborative-document-bubble.mdx +++ b/ui-kit/react/components/collaborative-document-bubble.mdx @@ -30,6 +30,10 @@ description: "A self-extracting bubble that renders a collaborative document car `CometChatCollaborativeDocumentBubble` renders a collaborative document card — a banner image, a title, a subtitle, and an "Open Document" button. It is **self-extracting**: pass the SDK `message` and the bubble reads the document URL from the message's extension metadata (`@injected.extensions.document.document_url`), so it works standalone. Clicking the button opens the document (by default in a new window). + +**Requires the Collaborative Document extension enabled in the [CometChat Dashboard](/fundamentals/collaborative-document).** Document messages (`extension_document`) — and the injected `document_url` this bubble reads — are only produced once the extension is turned on for your app. Without it the composer cannot create documents and this bubble never renders. See the [Collaborative Document guide](/fundamentals/collaborative-document) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes document messages to this bubble. + + **Live Preview** — interact with the collaborative document bubble. @@ -137,6 +141,9 @@ Additional CSS class applied to the root element. Plugin behavior, context menu, and conversation preview + + Turn on the extension that produces these messages + Render collaborative whiteboard messages diff --git a/ui-kit/react/components/collaborative-whiteboard-bubble.mdx b/ui-kit/react/components/collaborative-whiteboard-bubble.mdx index 7ad4dd731..8e1e6118c 100644 --- a/ui-kit/react/components/collaborative-whiteboard-bubble.mdx +++ b/ui-kit/react/components/collaborative-whiteboard-bubble.mdx @@ -30,6 +30,10 @@ description: "A self-extracting bubble that renders a collaborative whiteboard c `CometChatCollaborativeWhiteboardBubble` renders a collaborative whiteboard card — a banner image, a title, a subtitle, and an "Open Whiteboard" button. It is **self-extracting**: pass the SDK `message` and the bubble reads the board URL from the message's extension metadata (`@injected.extensions.whiteboard.board_url`), so it works standalone. Clicking the button opens the whiteboard (by default in a new window). + +**Requires the Collaborative Whiteboard extension enabled in the [CometChat Dashboard](/fundamentals/collaborative-whiteboard).** Whiteboard messages (`extension_whiteboard`) — and the injected `board_url` this bubble reads — are only produced once the extension is turned on for your app. Without it the composer cannot create whiteboards and this bubble never renders. See the [Collaborative Whiteboard guide](/fundamentals/collaborative-whiteboard) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes whiteboard messages to this bubble. + + **Live Preview** — interact with the collaborative whiteboard bubble. @@ -137,6 +141,9 @@ Additional CSS class applied to the root element. Plugin behavior, context menu, and conversation preview + + Turn on the extension that produces these messages + Render collaborative document messages diff --git a/ui-kit/react/components/conversations.mdx b/ui-kit/react/components/conversations.mdx index a40324853..b3af4e9fc 100644 --- a/ui-kit/react/components/conversations.mdx +++ b/ui-kit/react/components/conversations.mdx @@ -4,129 +4,21 @@ description: "Scrollable list of recent one-on-one and group conversations for t --- -```json -{ - "component": "CometChatConversations", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatConversations } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable list of recent one-on-one and group conversations for the logged-in user with real-time updates.", - "cssRootClass": ".cometchat-conversations", - "primaryOutput": { - "prop": "onItemClick", - "type": "(conversation: CometChat.Conversation) => void" - }, - "props": { - "data": { - "conversationsRequestBuilder": { - "type": "CometChat.ConversationsRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.ConversationsRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - }, - "activeConversation": { - "type": "CometChat.Conversation", - "default": "undefined" - }, - "lastMessageDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "hh:mm A today, Yesterday, dddd last week, DD/MM/YYYY older" - } - }, - "callbacks": { - "onItemClick": "(conversation: CometChat.Conversation) => void", - "onSelect": "(conversation: CometChat.Conversation, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void", - "onSearchBarClicked": "() => void" - }, - "visibility": { - "hideReceipts": { "type": "boolean", "default": false }, - "hideUserStatus": { "type": "boolean", "default": false }, - "hideGroupType": { "type": "boolean", "default": false }, - "hideUnreadCount": { "type": "boolean", "default": false }, - "hideDeleteConversation": { "type": "boolean", "default": false }, - "showSearchBar": { "type": "boolean", "default": true }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "sound": { - "disableSoundForMessages": { "type": "boolean", "default": false }, - "customSoundForMessages": { "type": "string", "default": "built-in" } - }, - "selection": { - "selectionMode": { - "type": "CometChatConversationsSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(conversation: CometChat.Conversation) => ReactNode", - "leadingView": "(conversation: CometChat.Conversation) => ReactNode", - "titleView": "(conversation: CometChat.Conversation) => ReactNode", - "subtitleView": "(conversation: CometChat.Conversation) => ReactNode", - "trailingView": "(conversation: CometChat.Conversation) => ReactNode", - "headerView": "ReactNode", - "searchView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(conversation: CometChat.Conversation) => CometChatConversationOption[]" - } - }, - "events": [ - { - "name": "ui:conversation/deleted", - "payload": "{ conversation: CometChat.Conversation }", - "description": "Conversation deleted from list" - } - ], - "sdkListeners": [ - "onTextMessageReceived", - "onMediaMessageReceived", - "onCustomMessageReceived", - "onInteractiveMessageReceived", - "onTypingStarted", - "onTypingEnded", - "onMessagesDelivered", - "onMessagesRead", - "onUserOnline", - "onUserOffline", - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onMemberAddedToGroup" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - }, - "CometChatConversationOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(conversation: CometChat.Conversation) => void" - }, - "CometChatConversationsSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatConversations` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatConversations } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-conversations` | +| Primary output | `onItemClick: (conversation: CometChat.Conversation) => void` — emits the selected conversation to open | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Wire `onItemClick` → derive the user/group with `conversation.getConversationWith()` → mount `CometChatMessageHeader` / `CometChatMessageList` / `CometChatMessageComposer` (see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation)). Full search needs `onSearchBarClicked` → [`CometChatSearch`](/ui-kit/react/components/search) (see the [Search Messages guide](/ui-kit/react/guide-search-messages)) | +| Events emitted | `ui:conversation/deleted` — see the [Event System](/ui-kit/react/event-system) | +| Events received | Subscribes to `ui:message/*`, `ui:conversation/*`, and `ui:group/*` events published by other components — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Messages, typing, receipts, presence, and group membership are handled internally — no wiring needed | +| Full props | See [Props](#props) | + ## Overview @@ -200,6 +92,8 @@ function Sidebar() { ### Full Layout Example +`onItemClick` is where you derive the selected user or group from the conversation and mount the `MessageHeader` / `MessageList` / `MessageComposer` panel — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) for the full two-panel wiring. + ```tsx import { useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -276,6 +170,8 @@ To use the search bar as a trigger for a custom search UI (like `CometChatSearch /> ``` +See the [Search Messages guide](/ui-kit/react/guide-search-messages) for wiring a full search experience across conversations and messages. + ### Filter Recipes | Recipe | Code | @@ -309,7 +205,7 @@ UI events this component publishes: ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see the [Event System](/ui-kit/react/event-system) for how components publish and subscribe. | Event | Payload | Behavior | | --- | --- | --- | @@ -863,6 +759,10 @@ function CustomOptionsConversations() { return ; } ``` + + +The `onClick` handlers above are placeholders — the component only renders the menu items; you must implement the actual behavior (delete, mute, pin, mark-unread, block). For the Block option, wire it to the SDK and refresh UI state as shown in the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user). + ```css @@ -1048,6 +948,10 @@ Whether to show the search bar. Set to `false` to hide it entirely. | Type | `boolean` | | Default | `true` | + +Showing the bar is not the same as enabling search. To power a full **conversation + message search** experience you need two more things: (1) enable **Conversation & Advanced Search** for your app in the [CometChat Dashboard](https://app.cometchat.com), and (2) wire the bar as a trigger — pass [`onSearchBarClicked`](#onsearchbarclicked) to open a [`CometChatSearch`](/ui-kit/react/components/search) panel and switch views. See the [Search Messages guide](/ui-kit/react/guide-search-messages) for the full wiring across conversations and messages. + + --- ### showScrollbar diff --git a/ui-kit/react/components/flag-message-dialog.mdx b/ui-kit/react/components/flag-message-dialog.mdx index b5d5ef220..ab8d8d069 100644 --- a/ui-kit/react/components/flag-message-dialog.mdx +++ b/ui-kit/react/components/flag-message-dialog.mdx @@ -226,6 +226,10 @@ Called when an SDK error occurs (e.g., while fetching reasons or during submissi On open, the dialog calls `CometChat.getFlagReasons()` and renders the result as a single-select list. While loading, a loading state is shown. If the call fails, `onError` is invoked. + +Report reasons come from your CometChat **Moderation / Report Message** configuration in the Dashboard, fetched via `CometChat.getFlagReasons()`. Configure custom reasons and review flagged messages in [Moderation](/moderation/overview). The parent component must implement `onSubmit` to submit the report. + + ### Remark The remark is optional. It is trimmed before submission, and an empty remark is passed as `undefined` to `onSubmit`. A character counter enforces `maxLength` (default 500). diff --git a/ui-kit/react/components/group-members.mdx b/ui-kit/react/components/group-members.mdx index f70cd3a55..e72705227 100644 --- a/ui-kit/react/components/group-members.mdx +++ b/ui-kit/react/components/group-members.mdx @@ -281,7 +281,7 @@ This component does not emit any UI events directly. Kick, ban, and scope change ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see [Event System → User & Group Actions](/ui-kit/react/event-system#user--group-actions) for how these `ui:group/member-*` and `ui:group/ownership-changed` events are published. | Event | Payload | Behavior | | --- | --- | --- | @@ -694,6 +694,10 @@ View slot props (`headerView`, `loadingView`, `emptyView`, `errorView`, `itemVie | Type | `CometChat.Group` | | Default | — | + +`group` is required — the component renders nothing without it. Obtain the `CometChat.Group` from the selected item in `CometChatGroups` (`onItemClick`), from `CometChat.getGroup(guid)`, or from your own state, then pass it in. See the [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) for how the group flows from selection into the members panel. + + --- ### groupMemberRequestBuilder @@ -835,6 +839,10 @@ Function that returns context menu options for each member item (shown on hover/ /> ``` + +These `onClick` handlers are placeholders — the component only renders the menu items; you must implement the behavior. For the "Message Privately" option, open a one-on-one chat with the selected member as shown in the [Message Privately guide](/ui-kit/react/guide-message-privately). Kick, ban, and scope-change actions are handled by the component's built-in options unless you override them here. + + --- ### onItemClick @@ -890,6 +898,10 @@ Callback when the back button in the header is clicked. | Type | `() => void` | | Default | `undefined` | + +`onBack` is a placeholder — the component only renders the back button and invokes this callback. Navigation and layout wiring (closing the panel, returning to the group chat, updating your router) are your app's responsibility. The [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) shows how the members panel is wired into the surrounding layout. + + --- ## CSS Selectors diff --git a/ui-kit/react/components/groups.mdx b/ui-kit/react/components/groups.mdx index c9595f707..629d53e25 100644 --- a/ui-kit/react/components/groups.mdx +++ b/ui-kit/react/components/groups.mdx @@ -202,6 +202,8 @@ function GroupList() { ### Full Layout Example +`onItemClick` is where you capture the selected group and mount the chat panel to open the group chat — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) for the two-panel wiring and the [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) for join/details flows. + ```tsx import { useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -289,7 +291,7 @@ This component does not emit any UI events. ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see [Event System → User & Group Actions](/ui-kit/react/event-system#user--group-actions) for how these `ui:group/*` events are published. | Event | Payload | Behavior | | --- | --- | --- | @@ -715,6 +717,10 @@ Function that returns context menu options for each group item (shown on hover/s /> ``` + +The `onClick` handlers above (`leaveGroup`, `openGroupDetails`) are placeholders — the component only renders the menu items; you must implement the actual behavior. The [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) shows the join, leave, and group-details flows end to end. + + --- ### onItemClick diff --git a/ui-kit/react/components/message-composer.mdx b/ui-kit/react/components/message-composer.mdx index 6cb59d304..a86b72129 100644 --- a/ui-kit/react/components/message-composer.mdx +++ b/ui-kit/react/components/message-composer.mdx @@ -293,6 +293,10 @@ This mirrors the underlying SDK upload semantics: **failed** uploads are transie - **Count** — a single batch can hold up to a configurable 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 validation banner is shown. The composer does **not** partially accept a subset of files to fill the remaining slots. - **Per-file size** — a file larger than the allowed size (`file.size.max`) is rejected as an individual tile. + +These limits are **Dashboard/app-level settings**, not UI Kit props. The maximum file **count** (`file.count.max`) and **size** (`file.size.max`) are read from your CometChat app settings at runtime, and permitted file **types** are governed by your app's role-based file-type permissions (RBAC/SBAC). If an attachment is rejected unexpectedly, verify these settings for your app and role in the CometChat Dashboard — they are not overridable from the composer. + + ### Why a file is rejected A rejected tile explains itself on hover via a tooltip: @@ -343,7 +347,7 @@ UI events this component publishes: ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components) — part of the UI Kit's [Event System](/ui-kit/react/event-system#composer-commands). Publishing `ui:compose/edit` or `ui:compose/reply` (e.g. from the [Message List](/ui-kit/react/components/message-list) edit/reply actions) is how another component drives this composer into edit/reply mode without prop drilling: | Event | Payload | Behavior | | --- | --- | --- | @@ -410,6 +414,10 @@ function ComposerCustomAttachments({ chatUser }: { chatUser: CometChat.User }) { } ``` + +Each custom option's `onClick` is a handler **you** implement — the composer only renders the menu. To send a message from a custom option, use the CometChat SDK or the UI Kit's [Event System](/ui-kit/react/event-system) (e.g. optimistic-send flows). Custom attachment options can also be provided by a [plugin](/ui-kit/react/plugins/overview); `sendTextMessageOverride` similarly lets you intercept the outgoing text before send. + + #### auxiliaryButtonView Replace the auxiliary button area. @@ -520,6 +528,10 @@ View slot props (`headerView`, `sendButtonView`, `auxiliaryButtonView`, `attachm ### Entity + +The composer requires exactly one entity — a `user` (1:1) or a `group` — to know where to send messages. Without either prop it has no conversation to post to. For how to derive the active entity from a conversation/user/group selection and mount the composer, see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation). + + --- #### user @@ -694,6 +706,10 @@ Message to reply to (triggers reply mode with preview). ### Attachments + +**Extension-backed attachment options require a Dashboard extension.** The default attachment menu auto-integrates the **Polls**, **Collaborative Document**, **Collaborative Whiteboard**, and **Sticker** options — but each only appears once its extension is enabled in the [CometChat Dashboard](/ui-kit/react/extensions). If an option is missing, enable the extension: [Polls](/fundamentals/polls), [Collaborative Document](/fundamentals/collaborative-document), [Collaborative Whiteboard](/fundamentals/collaborative-whiteboard), [Stickers](/fundamentals/stickers). See [Extensions](/ui-kit/react/extensions) for the full list of extensions the composer auto-integrates. `hideAttachmentOptions` and `hideStickersButton` only control visibility of options that are already enabled. + + --- #### attachmentOptions @@ -817,27 +833,6 @@ Hide the stickers button. --- -#### hideAIButton - -Hide the AI button. - -| | | -| --- | --- | -| Type | `boolean` | -| Default | `true` | - ---- - -#### hideLiveReaction - -Hide the live reaction button. - -| | | -| --- | --- | -| Type | `boolean` | -| Default | `false` | - ---- #### hideSendButton diff --git a/ui-kit/react/components/message-header.mdx b/ui-kit/react/components/message-header.mdx index 5a507f97f..eef8fd6d1 100644 --- a/ui-kit/react/components/message-header.mdx +++ b/ui-kit/react/components/message-header.mdx @@ -302,13 +302,17 @@ function ChatApp() { | `onVideoCallClick` | `(entity: CometChat.User \| CometChat.Group) => void` | User clicks the video call button | | `onError` | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs | + +These navigation callbacks are placeholders you wire to your app's layout. `onSearchOptionClicked` should open in-conversation search (mount `CometChatSearch` → jump to a result via `goToMessageId`) — see the [Search Messages guide](/ui-kit/react/guide-search-messages). `onItemClick` typically opens a details/info panel, and `onBack` returns to the conversation list; both are handled by your own routing/layout state. + + ### Events Emitted This component does not emit any UI events directly. Call initiation publishes call events internally via the SDK. ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components) — part of the UI Kit's [Event System](/ui-kit/react/event-system): | Event | Payload | Behavior | | --- | --- | --- | @@ -625,6 +629,10 @@ Whether to show the search button in the header toolbar. Whether to show the AI conversation summary button. + +The Conversation Summary button (`showConversationSummaryButton`, `enableAutoSummaryGeneration`, `onSummaryClick`) requires the **Conversation Summary AI feature to be enabled** for your app in the CometChat Dashboard. When the feature is disabled or not configured, the button will not surface. See [AI Features (Smart Chat)](/ui-kit/react/ai-features#conversation-summary) and [AI User Copilot](/fundamentals/ai-user-copilot/overview). + + | | | | --- | --- | | Type | `boolean` | diff --git a/ui-kit/react/components/message-list.mdx b/ui-kit/react/components/message-list.mdx index 936115211..e18f7a6a5 100644 --- a/ui-kit/react/components/message-list.mdx +++ b/ui-kit/react/components/message-list.mdx @@ -420,7 +420,7 @@ Pass a `CometChat.MessagesRequestBuilder` to `messagesRequestBuilder` to control | Prop | Signature | Fires when | | --- | --- | --- | -| `onThreadRepliesClick` | `(message: CometChat.BaseMessage) => void` | User clicks the thread reply indicator | +| `onThreadRepliesClick` | `(message: CometChat.BaseMessage) => void` | User clicks the thread reply indicator — wire this to open a thread panel ([Threaded Messages guide](/ui-kit/react/guide-threaded-messages)) | | `onAvatarClick` | `(user: CometChat.User) => void` | User clicks an avatar on an incoming message | | `onEditMessage` | `(message: CometChat.BaseMessage) => void` | User selects "Edit" from context menu | | `onReplyMessage` | `(message: CometChat.BaseMessage) => void` | User selects "Reply" from context menu | @@ -451,7 +451,7 @@ The "Edit" and "Reply" context menu options publish `ui:compose/edit` and `ui:co ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components) — part of the UI Kit's [Event System](/ui-kit/react/event-system). These let group/call/composer actions elsewhere in your app update the list automatically: | Event | Payload | Behavior | | --- | --- | --- | @@ -684,6 +684,10 @@ View slot props (`bubbleView`, `headerView`, `footerView`, `loadingView`, `empty ### Entity + +The message list requires exactly one entity — a `user` (1:1) or a `group` — to know which conversation to render. Without either prop it shows nothing. For how to derive the active entity from a conversation/user/group selection and mount the list, see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation). + + --- ### user @@ -717,6 +721,10 @@ Enables thread mode. When set, the component fetches and displays replies to the | Type | `number` | | Default | `undefined` | + +Thread replies require wiring: capture the parent from `onThreadRepliesClick`, then mount a **second** `CometChatMessageList` + `CometChatMessageComposer` with this `parentMessageId` (usually alongside a `CometChatThreadHeader`) in a thread panel. See the [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) for the full pattern. + + --- ### Data @@ -776,6 +784,10 @@ Jump to a specific message by ID (e.g., from search results or a deep link). The | Type | `number` | | Default | `undefined` | + +This is how in-conversation search "jump to result" and deep links work: take the message ID from `CometChatSearch` (or your deep link) and pass it here. See the [Search Messages guide](/ui-kit/react/guide-search-messages) for the end-to-end wiring. + + --- ### startFromUnreadMessages @@ -793,6 +805,10 @@ When `true`, the list scrolls to the first unread message on open instead of the When `true`, loads the last agent conversation on initial render. Used for AI agent chat flows. + +Agent chat props (`loadLastAgentConversation`, `isAgentChat`) require an **AI Agent configured in the CometChat Dashboard** — the conversation entity must be that agent user. For a purpose-built agent experience, use the [AI Assistant Chat](/ui-kit/react/components/ai-assistant-chat) component, which wraps this list. See [AI Features](/ui-kit/react/ai-features) for the broader AI capabilities. + + | | | | --- | --- | | Type | `boolean` | @@ -868,6 +884,10 @@ Hide the moderation footer beneath disapproved messages. | Type | `boolean` | | Default | `false` | + +The moderation footer only appears when messages are actually moderated, which requires **Moderation rules configured in the CometChat Dashboard**. See [Moderation overview](/moderation/overview) to set up rules. This prop only controls whether the UI Kit renders the footer for already-moderated messages. + + --- ### showScrollbar @@ -885,6 +905,10 @@ Show the native scrollbar on the message list. When `false`, the scrollbar is hi Show AI-generated smart reply suggestions in the footer when the last received message matches keyword criteria. + +This requires the **Smart Replies** AI feature to be enabled for your app in the CometChat Dashboard. With the feature disabled, no suggestions are generated even when `showSmartReplies` is `true`. See [AI Features](/ui-kit/react/ai-features#smart-replies). + + | | | | --- | --- | | Type | `boolean` | @@ -896,6 +920,10 @@ Show AI-generated smart reply suggestions in the footer when the last received m Show AI-generated conversation starters in the footer when the message list is empty. + +This requires the **Conversation Starter** AI feature to be enabled for your app in the CometChat Dashboard. With the feature disabled, no starters are generated even when `showConversationStarters` is `true`. See [AI Features](/ui-kit/react/ai-features#conversation-starter). + + | | | | --- | --- | | Type | `boolean` | @@ -1026,6 +1054,10 @@ Hide the "Flag/Report" option from the message context menu. | Type | `boolean` | | Default | `false` | + +Flagging/reporting a message feeds CometChat **Moderation**. Flagged messages are reviewed in the [Moderation dashboard](/moderation/overview), and custom report reasons are configured there. See [Moderation overview](/moderation/overview). + + --- ### hideMessagePrivatelyOption @@ -1048,6 +1080,10 @@ Hide the "Translate" option from the message context menu. | Type | `boolean` | | Default | `false` | + +The "Translate" option only works when the **Message Translation extension is enabled** in the CometChat Dashboard. Without it, the option has nothing to call. Enable it from [Extensions](/ui-kit/react/extensions) — see the [Message Translation guide](/fundamentals/message-translation). + + --- ### hideFlagRemarkField diff --git a/ui-kit/react/components/notification-feed.mdx b/ui-kit/react/components/notification-feed.mdx index 79711463c..f1e367c1e 100644 --- a/ui-kit/react/components/notification-feed.mdx +++ b/ui-kit/react/components/notification-feed.mdx @@ -59,6 +59,10 @@ description: "Full-screen notification feed component with category filtering, c `CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a card using `@cometchat/cards-react`. It handles fetching, pagination, category filtering, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically. + +**Prerequisite: Campaigns must be configured first.** The feed only shows content once **Campaigns / Notifications are set up in the CometChat Dashboard** — channels, categories, and card templates. Without this, the feed renders but stays empty. See [Campaigns](/ui-kit/react/campaigns) for the end-to-end setup (Dashboard configuration through frontend wiring). + + @@ -200,6 +204,10 @@ Fires when an interactive element (button, link) inside a card is clicked. The ` /> ``` + +**Navigation is your app's responsibility.** `onItemClick` and `onActionClick` only report the intent (deep link, `chatWithUser`, `chatWithGroup`, `openUrl`) — the component does not route anywhere on its own. Your app must handle the transition (open the URL, switch to the chat with `params.uid` / `params.guid`, etc.). For the recommended navigation-event pattern, see [Event System — Navigation](/ui-kit/react/event-system#navigation). + + #### onError Fires when an internal error occurs (network failure, SDK exception). diff --git a/ui-kit/react/components/poll-bubble.mdx b/ui-kit/react/components/poll-bubble.mdx index 5d0304e1d..18dc19abb 100644 --- a/ui-kit/react/components/poll-bubble.mdx +++ b/ui-kit/react/components/poll-bubble.mdx @@ -31,6 +31,10 @@ description: "A self-extracting bubble that renders a poll with its question, se `CometChatPollBubble` renders a poll. It is **self-extracting**: pass the SDK custom `message` and the bubble derives the question, options, per-option vote counts, total votes, and the logged-in user's selected option entirely from the message metadata. Selecting an option submits a vote; the bar fills and counts/avatars update. + +**Requires the Polls extension enabled in the [CometChat Dashboard](/fundamentals/polls).** Poll messages (`extension_poll`) are only produced once the Polls extension is turned on for your app. Without it the composer cannot send polls and this bubble never renders. See the [Polls guide](/fundamentals/polls) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes poll messages to this bubble. + + **Live Preview** — interact with the poll bubble. @@ -155,6 +159,9 @@ Additional CSS class applied to the root element. Plugin behavior, context menu, and conversation preview + + Turn on the Polls extension that produces these messages + Render sticker messages diff --git a/ui-kit/react/components/reaction-list.mdx b/ui-kit/react/components/reaction-list.mdx index 26e56de93..f2d583487 100644 --- a/ui-kit/react/components/reaction-list.mdx +++ b/ui-kit/react/components/reaction-list.mdx @@ -362,3 +362,18 @@ Optional custom CSS class for the root container. - Shimmer respects `prefers-reduced-motion`. - Spinner respects `prefers-reduced-motion`. - High contrast mode supported via `@media (prefers-contrast: high)`. + +## Related + + +`CometChatReactionList` never calls the SDK itself. The **parent owns reaction removal** — it calls `CometChat.removeReaction`, manages the panel's open/close state, and responds to `onItemClick` (a current-user reaction was tapped) and `onEmpty` (all reactions gone — close the panel). + + + + + Display-only reaction chips shown on message bubbles + + + The parent that owns the reaction add/remove SDK calls + + diff --git a/ui-kit/react/components/reactions.mdx b/ui-kit/react/components/reactions.mdx index 193d56f04..2b0a59cb7 100644 --- a/ui-kit/react/components/reactions.mdx +++ b/ui-kit/react/components/reactions.mdx @@ -45,6 +45,10 @@ description: "Displays emoji reaction chips on message bubbles with hover toolti `CometChatReactions` renders below message bubbles to show emoji reactions. It is typically used inside `CometChatMessageBubble` as the footer view. The parent (usually `CometChatMessageList`) owns the reaction add/remove SDK calls and passes the updated message down. + +**This component is display-only.** It renders reaction chips and tooltips but does **not** call the SDK to add or remove reactions. The **parent owns all reaction SDK calls** — it handles `onReactionClick` (to toggle a reaction via the SDK), supplies `reactionsRequestBuilder`, and passes an updated `message` prop down after each change. In practice the parent is [Message List](/ui-kit/react/components/message-list), which wires these calls for you. For a standalone reactor panel with removal support, use [Reaction List](/ui-kit/react/components/reaction-list). + + **Live Preview** — interact with the reactions component. diff --git a/ui-kit/react/components/search.mdx b/ui-kit/react/components/search.mdx index fa56f643b..01ce63176 100644 --- a/ui-kit/react/components/search.mdx +++ b/ui-kit/react/components/search.mdx @@ -136,6 +136,10 @@ description: "Unified search across conversations and messages with filter chips ## Overview `CometChatSearch` is a unified search component. It searches across conversations and messages, displaying results in separate sections with filter chips for scoping. It emits the selected result via `onConversationClicked` or `onMessageClicked` — both include the `searchKeyword` in the event payload. Wire it to `CometChatConversations` or `CometChatMessageList` to navigate to the matched result. + + +**These result callbacks are required to make the component useful.** `CometChatSearch` does not navigate on its own — clicking a result only fires `onConversationClicked` or `onMessageClicked`. Your app must handle navigation: open the [Conversations](/ui-kit/react/components/conversations) list or route to the matched entity, and pass the message's ID to [Message List](/ui-kit/react/components/message-list) via `goToMessageId` to scroll to the exact message. For an end-to-end walkthrough, see the [Search Messages guide](/ui-kit/react/guide-search-messages). + **Live Preview** — interact with the default search component. diff --git a/ui-kit/react/components/sticker-bubble.mdx b/ui-kit/react/components/sticker-bubble.mdx index 786f159aa..40bd21c47 100644 --- a/ui-kit/react/components/sticker-bubble.mdx +++ b/ui-kit/react/components/sticker-bubble.mdx @@ -28,6 +28,10 @@ description: "A self-extracting bubble that renders a sticker image from a stick `CometChatStickerBubble` renders a sticker. It is **self-extracting**: pass the SDK custom `message` and the bubble extracts the sticker image URL and name from its metadata, so it works standalone. + +**Requires the Stickers extension enabled in the [CometChat Dashboard](/fundamentals/stickers).** Sticker messages (`extension_sticker`) are only produced once the Stickers extension is turned on and sticker sets are configured for your app. Without it the composer's sticker keyboard is unavailable and this bubble never renders. See the [Stickers guide](/fundamentals/stickers) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes sticker messages to this bubble. + + **Live Preview** — interact with the sticker bubble. @@ -109,6 +113,9 @@ Additional CSS class applied to the root element. Plugin behavior, keyboard, and conversation preview + + Turn on the Stickers extension that produces these messages + Render poll messages diff --git a/ui-kit/react/components/users.mdx b/ui-kit/react/components/users.mdx index 44e988e5d..033265954 100644 --- a/ui-kit/react/components/users.mdx +++ b/ui-kit/react/components/users.mdx @@ -170,6 +170,8 @@ function UserPicker() { ### New Conversation Example +`onItemClick` is where you capture the selected user and mount the chat panel to start a new conversation — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) for the complete flow. + ```tsx import { useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -258,7 +260,7 @@ This component does not emit any UI events. ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see [Event System → User & Group Actions](/ui-kit/react/event-system#user--group-actions) for how they are published. To publish these `ui:user/blocked` / `ui:user/unblocked` events yourself when a user is blocked or unblocked, follow the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user). | Event | Payload | Behavior | | --- | --- | --- | @@ -763,6 +765,10 @@ Function that returns context menu options for each user item (shown on hover/sw /> ``` + +The `onClick` handlers above (`blockUser`, `openProfile`) are placeholders — the component only renders the menu items; you must implement the actual behavior. For the Block User option, wire it to the SDK and refresh UI state as shown in the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user). + + --- ### onItemClick diff --git a/ui-kit/react/components/video-bubble.mdx b/ui-kit/react/components/video-bubble.mdx index ffe99dc11..a582e7ef6 100644 --- a/ui-kit/react/components/video-bubble.mdx +++ b/ui-kit/react/components/video-bubble.mdx @@ -40,6 +40,10 @@ Key capabilities: - **Fullscreen viewer** — click any video to open in fullscreen player - **Batch grouping** — rendered as one connected group when several media messages are sent together (handled by the [message list](/ui-kit/react/components/message-list#multi-attachment-batch-grouping)) + +Auto poster thumbnails are produced by the **Thumbnail Generation** extension — enable it in the Dashboard ([Thumbnail Generation](/fundamentals/thumbnail-generation)). Without it, the bubble falls back to the first video frame. + + **Live Preview** — interact with the video bubble. diff --git a/ui-kit/react/core-features.mdx b/ui-kit/react/core-features.mdx index b7b22b315..0567fe8b1 100644 --- a/ui-kit/react/core-features.mdx +++ b/ui-kit/react/core-features.mdx @@ -131,6 +131,10 @@ Mentions is a robust feature provided by CometChat that enhances the interactivi Rich Text Formatting allows users to style their messages with bold, italic, underline, strikethrough, code, links, lists, and blockquotes. This brings richer expression to conversations and helps users emphasize key points, making communication clearer and more engaging. + +Rich text is opt-in: enable it on the composer with `enableRichTextEditor` (see [Message Composer](/ui-kit/react/components/message-composer)). + + @@ -148,9 +152,13 @@ The Threaded Conversations feature enables users to respond directly to a specif + +Threads require wiring: capture the parent message from the Message List's `onThreadRepliesClick`, then mount a second `CometChatMessageList` + `CometChatMessageComposer` (with `parentMessageId`) and a `CometChatThreadHeader` in a thread panel. The [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) walks through the full flow end-to-end. + + | Components | Functionality | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| [Threaded Message Preview](/ui-kit/react/guide-threaded-messages) | [Threaded Message Preview](/ui-kit/react/guide-threaded-messages) component displays the parent message along with the number of replies. | +| [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) | The [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) shows how to build a thread panel: `onThreadRepliesClick`, `parentMessageId`, and `CometChatThreadHeader` (which displays the parent message with its reply count). | ## Quoted Replies @@ -213,6 +221,10 @@ Learn more about how flagged messages are handled, reviewed, and moderated in th Conversation and Advanced Search is a powerful feature provided by CometChat that enables users to quickly find conversations, messages, and media across chats in real time. It supports filters, scopes, and custom actions, allowing users to locate content efficiently while keeping the chat experience smooth and intuitive. + +Search requires wiring the result callbacks to navigation: handle `onConversationClicked` / `onMessageClicked` to open the conversation and jump to a message via the Message List's `goToMessageId`. The [Search Messages guide](/ui-kit/react/guide-search-messages) walks through the full in-conversation search flow. + + diff --git a/ui-kit/react/event-system.mdx b/ui-kit/react/event-system.mdx index a2b35e12e..c73f15c10 100644 --- a/ui-kit/react/event-system.mdx +++ b/ui-kit/react/event-system.mdx @@ -225,6 +225,8 @@ These events are published by UI Kit components for local cross-component commun | `ui:group/member-scope-changed` | `{ message, user, group, newScope }` | GroupMembers | | `ui:group/ownership-changed` | `{ group, newOwner, previousOwnerUid }` | GroupMembers | +**Used by:** the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user) publishes and subscribes to `ui:user/blocked` / `ui:user/unblocked` to keep the composer in sync, and the [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) reacts to `ui:group/created` in the group creation flow. + ### Thread | Event Type | Payload | Published by | @@ -232,6 +234,8 @@ These events are published by UI Kit components for local cross-component commun | `ui:thread/opened` | `{ parentMessage }` | MessageList (thread option) | | `ui:thread/closed` | — | ThreadHeader | +**Used by:** the [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) opens and closes the thread panel in response to `ui:thread/opened` / `ui:thread/closed`. + ### Call Actions | Event Type | Payload | Published by | @@ -248,6 +252,8 @@ These events are published by UI Kit components for local cross-component commun | --- | --- | --- | | `ui:open-chat` | `{ user?, group? }` | MessageList (message privately option) | +**Used by:** the [Message Privately guide](/ui-kit/react/guide-message-privately) subscribes to `ui:open-chat` to open a private one-on-one panel from within a group chat. + ### Card Actions | Event Type | Payload | Published by | diff --git a/ui-kit/react/guide-block-unblock-user.mdx b/ui-kit/react/guide-block-unblock-user.mdx index 95eb9cb06..7f3a62ce1 100644 --- a/ui-kit/react/guide-block-unblock-user.mdx +++ b/ui-kit/react/guide-block-unblock-user.mdx @@ -105,6 +105,10 @@ const [showBlockDialog, setShowBlockDialog] = useState(false); Use `useCometChatEvents` to subscribe to block/unblock events. This keeps the composer visibility in sync even when the block action originates from a different component (e.g., a details panel). + +The `ui:user/blocked` and `ui:user/unblocked` events are part of the UI Kit's [Event System](/ui-kit/react/event-system#user--group-actions). See that page for the full list of user and group action events and the `usePublishEvent` / `useCometChatEvents` hooks. + + _File: ChatView.tsx_ ```tsx @@ -299,6 +303,7 @@ export default App; ## Next Steps +- [Event System](/ui-kit/react/event-system#user--group-actions) — full reference for the `ui:user/*` events and pub/sub hooks - [Message Composer](/ui-kit/react/components/message-composer) — learn about composer customization - [Conversations](/ui-kit/react/components/conversations) — build a full conversations list - [CometChatProvider](/ui-kit/react/cometchat-provider) — configure the root provider diff --git a/ui-kit/react/guide-group-chat-setup.mdx b/ui-kit/react/guide-group-chat-setup.mdx index ac2667ad9..ec9bccb05 100644 --- a/ui-kit/react/guide-group-chat-setup.mdx +++ b/ui-kit/react/guide-group-chat-setup.mdx @@ -69,6 +69,10 @@ async function createGroup() { } ``` + +When a group is created through the UI Kit's built-in flow, it publishes the `ui:group/created` event on the [Event System](/ui-kit/react/event-system#user--group-actions). Subscribe with `useCometChatEvents` if other components need to react to new groups being created. + + ## Step 3: Add members to the group After creating a group, add members using `CometChat.addMembersToGroup()`. Each member needs a UID and a scope (admin, moderator, or participant). @@ -355,4 +359,5 @@ export default App; - [Groups](/ui-kit/react/components/groups) — browse and join existing groups - [Group Members](/ui-kit/react/components/group-members) — manage group membership - [Message Header](/ui-kit/react/components/message-header) — customize the group header +- [Event System](/ui-kit/react/event-system#user--group-actions) — react to `ui:group/created` and other group action events - [CometChatProvider](/ui-kit/react/cometchat-provider) — configure the root provider diff --git a/ui-kit/react/guide-message-privately.mdx b/ui-kit/react/guide-message-privately.mdx index 02454e238..ae0bf8111 100644 --- a/ui-kit/react/guide-message-privately.mdx +++ b/ui-kit/react/guide-message-privately.mdx @@ -105,6 +105,10 @@ async function handleMessagePrivately(uid: string) { Use `useCometChatEvents` to subscribe to the `ui:open-chat` event, which is published internally when a user clicks "Message Privately" from the context menu. When the event fires, extract the user and open the private panel. + +`ui:open-chat` is one of the UI Kit's [Event System — Navigation events](/ui-kit/react/event-system#navigation). See that page for the event payload and the full list of navigation and UI events. + + ```tsx import { useCometChatEvents } from "@cometchat/chat-uikit-react"; import type { CometChatEvent } from "@cometchat/chat-uikit-react"; @@ -260,6 +264,7 @@ export default App; ## Next Steps +- [Event System](/ui-kit/react/event-system#navigation) — reference for `ui:open-chat` and other navigation events - [Message Composer](/ui-kit/react/components/message-composer) — customize the composer for private chats - [Conversations](/ui-kit/react/components/conversations) — manage the conversations list - [Users](/ui-kit/react/components/users) — browse and select users directly diff --git a/ui-kit/react/guide-threaded-messages.mdx b/ui-kit/react/guide-threaded-messages.mdx index ced528be6..72f48f797 100644 --- a/ui-kit/react/guide-threaded-messages.mdx +++ b/ui-kit/react/guide-threaded-messages.mdx @@ -45,6 +45,10 @@ function ChatWithThreads() { Use the `onThreadRepliesClick` callback on `CometChatMessageList` to capture when a user clicks "Reply in Thread." This sets the threaded message and opens the panel — no events required. + +This guide uses a state-based approach, but the UI Kit also emits `ui:thread/opened` and `ui:thread/closed` on its [Event System — Thread events](/ui-kit/react/event-system#thread). Subscribe to those with `useCometChatEvents` if you need to react to thread open/close from another component. + + _File: ChatWithThreads.tsx_ ```tsx @@ -211,4 +215,5 @@ export default App; - [Thread Header](/ui-kit/react/components/thread-header) — customize the thread header appearance - [Message List](/ui-kit/react/components/message-list) — configure message list rendering and options +- [Event System](/ui-kit/react/event-system#thread) — subscribe to `ui:thread/opened` and `ui:thread/closed` events - [CometChatProvider](/ui-kit/react/cometchat-provider) — learn about provider configuration diff --git a/ui-kit/react/plugins/custom-plugin.mdx b/ui-kit/react/plugins/custom-plugin.mdx index a0b3dab77..51b6d7450 100644 --- a/ui-kit/react/plugins/custom-plugin.mdx +++ b/ui-kit/react/plugins/custom-plugin.mdx @@ -214,10 +214,12 @@ The `context` object passed to every plugin method: | `onFlagMessage` | `(msg) => void` | Open flag/report dialog | | `showToast` | `(text) => void` | Show a toast notification | | `getTextFormatters` | `() => Formatter[]` | Get text formatters for caption rendering | -| `publish` | `(event) => void` | Publish a UI event | +| `publish` | `(event) => void` | Publish a UI event — part of the UI Kit's [Event System](/ui-kit/react/event-system). Use it to drive other components (e.g. navigation, composer commands) from your plugin. | ## Tips +- **External API keys are your responsibility** — the map preview above calls the Google Maps Static API with `key=YOUR_API_KEY`. Replace it with your own Google Maps API key (an external dependency; not provided by CometChat). +- **Use `context.publish`** — to communicate with the rest of the UI, publish [UI events](/ui-kit/react/event-system) rather than reaching into other components directly - **Lazy-load heavy components** — use `React.lazy()` + `Suspense` for bubble components that import large libraries - **Use `context.getLocalizedString`** — for any user-facing text in options or bubbles - **Return `[]` from `getOptions`** — for system messages that shouldn't have a context menu diff --git a/ui-kit/react/plugins/overview.mdx b/ui-kit/react/plugins/overview.mdx index 5b466ef20..f23823b73 100644 --- a/ui-kit/react/plugins/overview.mdx +++ b/ui-kit/react/plugins/overview.mdx @@ -96,7 +96,11 @@ function App() { ## Built-in Plugins -These plugins are included automatically — no configuration needed. Each routes its message type to a bubble component; follow the component link for the full rendering behavior, props, and CSS. +These plugins are included automatically — no code configuration needed to render their message type. Each routes its message type to a bubble component; follow the component link for the full rendering behavior, props, and CSS. + + +**Extension-backed plugins require a Dashboard extension.** The renderer for the four extension plugins — **Polls** (`extension_poll`), **Stickers** (`extension_sticker`), **Collaborative Document** (`extension_document`), and **Collaborative Whiteboard** (`extension_whiteboard`) — ships with the UI Kit, but the messages themselves are only produced once the matching extension is enabled in the [CometChat Dashboard](https://app.cometchat.com). Enable each one before the composer can send it or the bubble can appear: [Polls](/fundamentals/polls), [Stickers](/fundamentals/stickers), [Collaborative Document](/fundamentals/collaborative-document), [Collaborative Whiteboard](/fundamentals/collaborative-whiteboard). + | Plugin | Message type(s) | Category | What it renders | Component | | --- | --- | --- | --- | --- | @@ -105,10 +109,10 @@ These plugins are included automatically — no configuration needed. Each route | **Video** | `video` | `message` | Video grid with poster thumbnails, duration overlays, and a fullscreen viewer | [Video Bubble](/ui-kit/react/components/video-bubble) | | **File** | `file` | `message` | Stacked file cards with type icons, size, and download | [File Bubble](/ui-kit/react/components/file-bubble) | | **Audio** | `audio` | `message` | Attached audio as stacked player cards; recorded voice notes as a waveform player | [Audio Bubble](/ui-kit/react/components/audio-bubble) | -| **Polls** | `extension_poll` | `custom` | Interactive poll with voting and live results | [Poll Bubble](/ui-kit/react/components/poll-bubble) | -| **Stickers** | `extension_sticker` | `custom` | Sticker image extracted from the message metadata | [Sticker Bubble](/ui-kit/react/components/sticker-bubble) | -| **Collaborative Document** | `extension_document` | `custom` | Document card with an "Open Document" button | [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) | -| **Collaborative Whiteboard** | `extension_whiteboard` | `custom` | Whiteboard card with an "Open Whiteboard" button | [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) | +| **Polls** ([enable in Dashboard](/fundamentals/polls)) | `extension_poll` | `custom` | Interactive poll with voting and live results | [Poll Bubble](/ui-kit/react/components/poll-bubble) | +| **Stickers** ([enable in Dashboard](/fundamentals/stickers)) | `extension_sticker` | `custom` | Sticker image extracted from the message metadata | [Sticker Bubble](/ui-kit/react/components/sticker-bubble) | +| **Collaborative Document** ([enable in Dashboard](/fundamentals/collaborative-document)) | `extension_document` | `custom` | Document card with an "Open Document" button | [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) | +| **Collaborative Whiteboard** ([enable in Dashboard](/fundamentals/collaborative-whiteboard)) | `extension_whiteboard` | `custom` | Whiteboard card with an "Open Whiteboard" button | [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) | | **Card** | any | `card` | Developer-defined card messages, drawn by the `CometChatCardView` renderer | [Card Bubble](/ui-kit/react/components/card-bubble) | | **Group Action** | `groupMember` | `action` | Centered system messages (joined, left, kicked, banned, scope change) | [Group Action Bubble](/ui-kit/react/components/group-action-bubble) | | **Call Action** | `audio` / `video` | `call` | Centered call status messages (missed, outgoing, incoming, ended) | [Call Action Bubble](/ui-kit/react/components/call-action-bubble) | diff --git a/ui-kit/react/plugins/text-formatters.mdx b/ui-kit/react/plugins/text-formatters.mdx index 13def11c9..315e9a077 100644 --- a/ui-kit/react/plugins/text-formatters.mdx +++ b/ui-kit/react/plugins/text-formatters.mdx @@ -11,14 +11,14 @@ Text formatters detect patterns in message text and transform them into formatte | Formatter | Priority | Detects | Output | | --- | --- | --- | --- | | `CometChatMarkdownFormatter` | 10 | `**bold**`, `_italic_`, `` `code` ``, `> quote`, lists, links | HTML tags (``, ``, ``, etc.) | -| `CometChatMentionsFormatter` | 50 | `<@uid:xxx>` tokens | Styled `@DisplayName` chips | +| `CometChatMentionsFormatter` | 20 | `<@uid:xxx>` tokens | Styled `@DisplayName` chips | | `CometChatUrlFormatter` | 100 | `https://...`, `www.` | Clickable `` links | ``` Raw text: "Hey **@Alice**, check https://example.com" ↓ MarkdownFormatter (priority 10) "Hey @Alice, check https://example.com" - ↓ MentionsFormatter (priority 50) + ↓ MentionsFormatter (priority 20) "Hey @Alice, check https://example.com" ↓ UrlFormatter (priority 100) "Hey @Alice, check https://example.com" @@ -59,7 +59,7 @@ import { CometChatTextFormatter } from "@cometchat/chat-uikit-react"; export class HashtagFormatter extends CometChatTextFormatter { readonly id = "hashtag-formatter"; - override priority = 90; // After mentions (50), before URLs (100) + override priority = 90; // After mentions (20), before URLs (100) private hashtags: string[] = []; @@ -101,6 +101,8 @@ export class HashtagFormatter extends CometChatTextFormatter { ## Registering Custom Formatters +A custom formatter is not registered on its own — it must be wrapped in a custom **text plugin** (see [Plugins overview](/ui-kit/react/plugins/overview)) and that plugin registered via the provider's `plugins` prop (see [With Additional Plugins](/ui-kit/react/cometchat-provider#with-additional-plugins)). + Custom formatters are registered by creating a custom text plugin that provides them: ```typescript title="src/plugins/CustomTextPlugin.ts" @@ -120,7 +122,7 @@ export const CustomTextPlugin = { getTextFormatters(): CometChatTextFormatter[] { return [ new CometChatMarkdownFormatter(), // priority 10 - new CometChatMentionsFormatter(), // priority 50 + new CometChatMentionsFormatter(), // priority 20 new HashtagFormatter(), // priority 90 new CometChatUrlFormatter(), // priority 100 ]; From f2597ff63a7eda196c1d420dbed89bb5853c0def Mon Sep 17 00:00:00 2001 From: rajdubey Date: Fri, 31 Jul 2026 12:36:30 +0530 Subject: [PATCH 03/63] Updated Ai Integration qucik notes --- ui-kit/react/components/ai-assistant-chat.mdx | 97 ++------ ui-kit/react/components/audio-bubble.mdx | 31 +-- .../react/components/call-action-bubble.mdx | 30 +-- ui-kit/react/components/call-bubble.mdx | 30 +-- ui-kit/react/components/call-buttons.mdx | 94 ++------ ui-kit/react/components/call-logs.mdx | 92 ++------ ui-kit/react/components/card-bubble.mdx | 30 +-- .../collaborative-document-bubble.mdx | 31 +-- .../collaborative-whiteboard-bubble.mdx | 31 +-- ui-kit/react/components/delete-bubble.mdx | 28 +-- ui-kit/react/components/file-bubble.mdx | 31 +-- .../react/components/flag-message-dialog.mdx | 48 +--- .../react/components/group-action-bubble.mdx | 30 +-- ui-kit/react/components/group-members.mdx | 128 ++--------- ui-kit/react/components/groups.mdx | 142 ++---------- ui-kit/react/components/image-bubble.mdx | 33 +-- ui-kit/react/components/incoming-call.mdx | 79 ++----- ui-kit/react/components/message-bubble.mdx | 67 +----- ui-kit/react/components/message-composer.mdx | 142 ++---------- ui-kit/react/components/message-header.mdx | 166 ++------------ .../react/components/message-information.mdx | 50 +--- ui-kit/react/components/message-list.mdx | 216 ++---------------- ui-kit/react/components/notification-feed.mdx | 64 ++---- ui-kit/react/components/outgoing-call.mdx | 52 +---- ui-kit/react/components/poll-bubble.mdx | 32 +-- ui-kit/react/components/reaction-list.mdx | 45 +--- ui-kit/react/components/reactions.mdx | 47 +--- ui-kit/react/components/search.mdx | 139 +---------- ui-kit/react/components/sticker-bubble.mdx | 29 +-- ui-kit/react/components/text-bubble.mdx | 32 +-- ui-kit/react/components/thread-header.mdx | 103 ++------- ui-kit/react/components/users.mdx | 110 ++------- ui-kit/react/components/video-bubble.mdx | 32 +-- ui-kit/react/components/voice-note-bubble.mdx | 30 +-- 34 files changed, 433 insertions(+), 1908 deletions(-) diff --git a/ui-kit/react/components/ai-assistant-chat.mdx b/ui-kit/react/components/ai-assistant-chat.mdx index 4ff89e674..eff675a3a 100644 --- a/ui-kit/react/components/ai-assistant-chat.mdx +++ b/ui-kit/react/components/ai-assistant-chat.mdx @@ -4,89 +4,20 @@ description: "AI agent chat interface with streaming responses, suggested messag --- -```json -{ - "component": "CometChatAIAssistantChat", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatAIAssistantChat } from \"@cometchat/chat-uikit-react\";", - "description": "AI agent chat interface with streaming responses, suggested messages, tool calling, and conversation history.", - "cssRootClass": ".cometchat-ai-assistant-chat", - "primaryOutput": { - "prop": "onSendButtonClick", - "type": "(message: CometChat.BaseMessage) => void" - }, - "props": { - "data": { - "user": { - "type": "CometChat.User", - "default": "REQUIRED", - "note": "The AI assistant user entity" - }, - "streamingSpeed": { - "type": "number", - "default": 30, - "note": "Milliseconds between text chunks during streaming" - }, - "aiAssistantTools": { - "type": "CometChatAIAssistantTools", - "default": "undefined", - "note": "Tool handlers for AI function calls" - }, - "loadLastAgentConversation": { - "type": "boolean", - "default": false - }, - "suggestedMessages": { - "type": "string[]", - "default": "[] (falls back to user metadata)" - }, - "parentMessageId": { - "type": "number", - "default": "undefined", - "note": "Load a specific conversation thread" - } - }, - "callbacks": { - "onSendButtonClick": "(message: CometChat.BaseMessage) => void", - "onBackButtonClicked": "() => void", - "onCloseButtonClicked": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideSuggestedMessages": { "type": "boolean", "default": false }, - "hideChatHistory": { "type": "boolean", "default": false }, - "hideNewChat": { "type": "boolean", "default": false }, - "showBackButton": { "type": "boolean", "default": false }, - "showCloseButton": { "type": "boolean", "default": false } - }, - "viewSlots": { - "emptyChatImageView": "ReactNode", - "emptyChatGreetingView": "ReactNode", - "emptyChatIntroMessageView": "ReactNode", - "emptyView": "ReactNode", - "loadingView": "ReactNode", - "errorView": "ReactNode", - "headerItemView": "ReactNode", - "headerTitleView": "ReactNode", - "headerSubtitleView": "ReactNode", - "headerLeadingView": "ReactNode", - "headerTrailingView": "ReactNode", - "headerAuxiliaryButtonView": "ReactNode" - } - }, - "events": [ - { - "name": "ui:compose/text", - "payload": "{ text }", - "description": "Suggestion pill clicked (sets text in composer)" - } - ], - "sdkListeners": [], - "types": { - "CometChatAIAssistantTools": "Class — maps tool function names to handler functions via constructor(actions: Record) => void>)" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatAIAssistantChat` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-ai-assistant-chat` | +| Primary output | `onSendButtonClick: (message: CometChat.BaseMessage) => void` — emits the sent user message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus an [AI Agent](/ai-agents/agent-builder/overview) configured in the Dashboard (passed as the `user` prop) | +| Stitching | Pass the AI Agent's `user` entity; the component streams replies and handles tool calls internally | +| Events emitted | `ui:compose/text` — sets text in the composer when a suggestion pill is clicked — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | None directly; internally uses the message list's SDK listeners for message updates, plus an AI assistant listener for streaming replies | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/audio-bubble.mdx b/ui-kit/react/components/audio-bubble.mdx index 0c2a1e774..18d981e4b 100644 --- a/ui-kit/react/components/audio-bubble.mdx +++ b/ui-kit/react/components/audio-bubble.mdx @@ -5,25 +5,18 @@ description: "A batch-aware bubble that renders one or more audio file attachmen --- -```json -{ - "component": "CometChatAudiosBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatAudiosBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware audio bubble for attached audio files. Renders stacked audio cards with play/pause, seekable slider, duration, and download. NOT used for voice notes — see CometChatVoiceNoteBubble.", - "cssRootClass": ".cometchat-audios-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of audio attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatAudiosBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatAudiosBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-audios-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/call-action-bubble.mdx b/ui-kit/react/components/call-action-bubble.mdx index 16032d5a1..c6dc8dfa6 100644 --- a/ui-kit/react/components/call-action-bubble.mdx +++ b/ui-kit/react/components/call-action-bubble.mdx @@ -5,24 +5,18 @@ description: "A self-extracting bubble that renders call status system messages --- -```json -{ - "component": "CometChatCallActionBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallActionBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting bubble for call status system messages. Derives the status text, icon, and error color from the SDK call message and the logged-in user.", - "cssRootClass": ".cometchat-action-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The call message (audio/video) in the 'call' category. Drives all extraction." }, - "className": { "type": "string", "default": "undefined", "note": "Additional CSS class for the root element" } - } - }, - "rendersThrough": "CometChatActionBubble (base primitive)", - "usedBy": ["CometChatCallActionPlugin"] -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallActionBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallActionBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-action-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/call-bubble.mdx b/ui-kit/react/components/call-bubble.mdx index 393b9c7cd..c4e6b8eae 100644 --- a/ui-kit/react/components/call-bubble.mdx +++ b/ui-kit/react/components/call-bubble.mdx @@ -5,24 +5,18 @@ description: "A self-extracting bubble for direct-call / meeting messages, with --- -```json -{ - "component": "CometChatCallBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting call bubble for meeting / direct-call custom messages. Derives the call type, session ID, title, icon, and timestamp from the message.", - "cssRootClass": ".cometchat-call-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The meeting/direct-call message; drives extraction." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "onJoinClick": { "type": "(sessionId: string) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-call-bubble` | +| Primary output | Self-extracting call bubble; `onJoinClick: (sessionId: string) => void` starts the call on Join | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; see [Calling Integration](/ui-kit/react/calling-integration) to start/join a call session | +| Stitching | Wire `onJoinClick` to start the call (see [Calling Integration](/ui-kit/react/calling-integration)) | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/call-buttons.mdx b/ui-kit/react/components/call-buttons.mdx index b9c9d8e8a..50de83487 100644 --- a/ui-kit/react/components/call-buttons.mdx +++ b/ui-kit/react/components/call-buttons.mdx @@ -4,85 +4,21 @@ description: "Voice and video call buttons for user or group conversations, with --- -```json -{ - "component": "CometChatCallButtons", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallButtons } from \"@cometchat/chat-uikit-react\";", - "description": "Voice and video call initiation buttons for user or group conversations. Manages the full call lifecycle (outgoing + ongoing) internally.", - "cssRootClass": ".cometchat-call-buttons", - "primaryOutput": { - "description": "Initiates calls via the SDK and renders the outgoing/ongoing call screens" - }, - "props": { - "data": { - "user": { - "type": "CometChat.User", - "default": "undefined", - "note": "Pass either user or group, not both" - }, - "group": { - "type": "CometChat.Group", - "default": "undefined", - "note": "Pass either user or group, not both" - } - }, - "callbacks": { - "onVoiceCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onVideoCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onCallEnded": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideVoiceCallButton": { "type": "boolean", "default": false }, - "hideVideoCallButton": { "type": "boolean", "default": false } - }, - "viewSlots": { - "voiceCallButtonView": "ReactNode", - "videoCallButtonView": "ReactNode" - }, - "configuration": { - "callSettingsBuilder": "(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => CallSettingsBuilder", - "className": "string" - } - }, - "eventsEmitted": [ - { - "name": "ui:call/outgoing", - "payload": "{ call }", - "description": "User initiates a 1-on-1 voice/video call" - }, - { - "name": "ui:message/sent", - "payload": "{ message, status }", - "description": "Group call meeting message sent" - } - ], - "eventsReceived": [ - { - "name": "ui:call/rejected", - "payload": "{ call }", - "description": "Re-enables call buttons after the call is rejected" - }, - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Resets all call state when the call ends" - } - ], - "sdkListeners": [ - "onIncomingCallReceived", - "onIncomingCallCancelled", - "onOutgoingCallAccepted", - "onOutgoingCallRejected" - ], - "compositionExample": { - "description": "Standalone call buttons or embedded in the MessageHeader auxiliary view", - "components": ["CometChatCallButtons", "CometChatOutgoingCall", "CometChatOngoingCall"], - "flow": "user/group prop -> click button -> SDK initiateCall -> CometChatOutgoingCall overlay -> onOutgoingCallAccepted -> CometChatOngoingCall" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallButtons` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallButtons } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-call-buttons` | +| Primary output | Initiates voice/video calls via the SDK and renders the outgoing/ongoing call screens; `onVoiceCallClick` / `onVideoCallClick` override the default initiation | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the Calls SDK installed and calling enabled — see [Calling Integration](/ui-kit/react/calling-integration) | +| Stitching | Pass `user` or `group`; the buttons manage the outgoing/ongoing call lifecycle internally (see [Calling Integration](/ui-kit/react/calling-integration)) | +| Events emitted | `ui:call/outgoing`, `ui:message/sent` — see [Event System](/ui-kit/react/event-system) | +| Events received | `ui:call/rejected`, `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Incoming call events (received/cancelled) and outgoing call events (accepted/rejected) to sync button state and screen transitions | +| Full props | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/call-logs.mdx b/ui-kit/react/components/call-logs.mdx index 5f30f2500..a06ef9c68 100644 --- a/ui-kit/react/components/call-logs.mdx +++ b/ui-kit/react/components/call-logs.mdx @@ -4,85 +4,19 @@ description: "Scrollable list of call history with call details, duration, and t --- -```json -{ - "component": "CometChatCallLogs", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallLogs } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable list of call history with call details, duration, and the ability to initiate new calls.", - "cssRootClass": ".cometchat-call-logs", - "primaryOutput": { - "prop": "onItemClick", - "type": "(call: any) => void" - }, - "props": { - "data": { - "activeCall": { - "type": "any", - "default": "undefined", - "note": "Object representing the active/selected call log" - }, - "callLogRequestBuilder": { - "type": "any", - "default": "limit 30, category \"call\"", - "note": "Custom request builder for filtering call logs" - }, - "callInitiatedDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "hh:mm A today, Yesterday, dddd last week, DD/MM/YYYY older" - } - }, - "callbacks": { - "onItemClick": "(call: any) => void", - "onCallButtonClicked": "(call: any) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "configuration": { - "callSettingsBuilder": { - "type": "any", - "default": "undefined", - "note": "Custom call settings builder for ongoing call sessions initiated from call logs" - } - }, - "visibility": { - "showScrollbar": { "type": "boolean", "default": false } - }, - "viewSlots": { - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "itemView": "(call: any) => ReactNode", - "leadingView": "(call: any) => ReactNode", - "titleView": "(call: any) => ReactNode", - "subtitleView": "(call: any) => ReactNode", - "trailingView": "(call: any) => ReactNode" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Resets ongoing call state (hides call screen)" - } - ], - "sdkListeners": [], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallLogs` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallLogs } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-call-logs` | +| Primary output | `onItemClick: (call: any) => void` — emits the selected call log | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Wire `onItemClick` / `onCallButtonClicked` to open details or start a call | +| Events received | `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/card-bubble.mdx b/ui-kit/react/components/card-bubble.mdx index e65e879cd..c1a34976d 100644 --- a/ui-kit/react/components/card-bubble.mdx +++ b/ui-kit/react/components/card-bubble.mdx @@ -5,24 +5,18 @@ description: "A render-only bubble that draws developer-defined card messages (c --- -```json -{ - "component": "CometChatCardBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCardBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Render-only bubble for developer card messages (category \"card\"). Stringifies the raw payload from message.getCard() and hands it to the prebuilt CometChatCardView renderer, then forwards user actions back to the app. It never parses, mutates, or acts on the card itself.", - "cssRootClass": ".cometchat-card-bubble", - "renderOnly": true, - "props": { - "data": { - "message": { "type": "CometChat.CardMessage", "required": true, "note": "The developer card message (category \"card\"). Drives message.getCard()." }, - "themeMode": { "type": "CometChatCardThemeMode", "default": "\"auto\"", "note": "Theme mode forwarded to CometChatCardView." }, - "themeOverride": { "type": "CometChatCardThemeOverride", "note": "Optional theme overrides forwarded to the renderer." }, - "onCardAction": { "type": "(message: CometChat.BaseMessage, action: CometChatCardAction) => void", "note": "Direct callback for card actions, fired in addition to the ui:card/action event." } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCardBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCardBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-card-bubble` | +| Primary output | `onCardAction: (message: CometChat.BaseMessage, action: CometChatCardAction) => void` — forwards the user's card action | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/collaborative-document-bubble.mdx b/ui-kit/react/components/collaborative-document-bubble.mdx index a21f5ea41..4bc808e9d 100644 --- a/ui-kit/react/components/collaborative-document-bubble.mdx +++ b/ui-kit/react/components/collaborative-document-bubble.mdx @@ -5,25 +5,18 @@ description: "A self-extracting bubble that renders a collaborative document car --- -```json -{ - "component": "CometChatCollaborativeDocumentBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCollaborativeDocumentBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting collaborative document bubble. Extracts the document URL from the message metadata and opens it on click.", - "cssRootClass": ".cometchat-collaborative-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "Drives extraction of the document URL." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "onButtonClick": { "type": "(url: string) => void", "note": "Defaults to window.open." }, - "disabled": { "type": "boolean", "default": false }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCollaborativeDocumentBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCollaborativeDocumentBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-collaborative-bubble` | +| Primary output | `onButtonClick: (url: string) => void` — opens the document URL (defaults to `window.open`) | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Collaborative Document extension](/fundamentals/collaborative-document) enabled in the Dashboard | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/collaborative-whiteboard-bubble.mdx b/ui-kit/react/components/collaborative-whiteboard-bubble.mdx index 8e1e6118c..8b0cb0741 100644 --- a/ui-kit/react/components/collaborative-whiteboard-bubble.mdx +++ b/ui-kit/react/components/collaborative-whiteboard-bubble.mdx @@ -5,25 +5,18 @@ description: "A self-extracting bubble that renders a collaborative whiteboard c --- -```json -{ - "component": "CometChatCollaborativeWhiteboardBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCollaborativeWhiteboardBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting collaborative whiteboard bubble. Extracts the board URL from the message metadata and opens it on click.", - "cssRootClass": ".cometchat-collaborative-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "Drives extraction of the board URL." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "onButtonClick": { "type": "(url: string) => void", "note": "Defaults to window.open." }, - "disabled": { "type": "boolean", "default": false }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCollaborativeWhiteboardBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCollaborativeWhiteboardBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-collaborative-bubble` | +| Primary output | Self-extracting; primary callback `onButtonClick: (url: string) => void` opens the whiteboard URL (defaults to `window.open`). | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Collaborative Whiteboard extension](/fundamentals/collaborative-whiteboard) enabled in the Dashboard. | +| Stitching | None — self-extracting from the SDK message. | +| Full props | See [Props](#props). | + ## Overview diff --git a/ui-kit/react/components/delete-bubble.mdx b/ui-kit/react/components/delete-bubble.mdx index 87511df46..fb0812883 100644 --- a/ui-kit/react/components/delete-bubble.mdx +++ b/ui-kit/react/components/delete-bubble.mdx @@ -5,22 +5,18 @@ description: "A presentational bubble that renders a 'This message was deleted' --- -```json -{ - "component": "CometChatDeleteBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatDeleteBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Presentational placeholder bubble for deleted messages.", - "cssRootClass": ".cometchat-delete-bubble", - "props": { - "data": { - "isSentByMe": { "type": "boolean", "note": "Affects sent vs received styling." }, - "text": { "type": "string", "note": "Defaults to localized \"This message was deleted\"." }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatDeleteBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatDeleteBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-delete-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/file-bubble.mdx b/ui-kit/react/components/file-bubble.mdx index f5d4e97a8..51d037af9 100644 --- a/ui-kit/react/components/file-bubble.mdx +++ b/ui-kit/react/components/file-bubble.mdx @@ -5,25 +5,18 @@ description: "A batch-aware bubble that renders one or more generic file attachm --- -```json -{ - "component": "CometChatFilesBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatFilesBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware file bubble. Extracts file attachments and caption from a MediaMessage; renders stacked file cards with type icons, name, size, extension, and download. Collapses to 3 cards with '+N more' expander.", - "cssRootClass": ".cometchat-files-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of file attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatFilesBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatFilesBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-files-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/flag-message-dialog.mdx b/ui-kit/react/components/flag-message-dialog.mdx index ab8d8d069..6d5336dbf 100644 --- a/ui-kit/react/components/flag-message-dialog.mdx +++ b/ui-kit/react/components/flag-message-dialog.mdx @@ -5,42 +5,18 @@ description: "A dialog for reporting inappropriate messages with reason selectio --- -```json -{ - "component": "CometChatFlagMessageDialog", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatFlagMessageDialog } from \"@cometchat/chat-uikit-react\";", - "description": "Dialog for reporting/flagging an inappropriate message. Fetches flag reasons from the SDK, captures an optional remark, and submits the report.", - "cssRootClass": ".cometchat-flag-message-dialog", - "primaryOutput": { - "prop": "onSubmit", - "type": "(messageId: string, reasonId: string, remark?: string) => Promise" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message being flagged." }, - "isOpen": { "type": "boolean", "note": "When provided, the dialog is controlled." } - }, - "callbacks": { - "onSubmit": { "type": "(messageId: string, reasonId: string, remark?: string) => Promise", "note": "Return true to close, false to keep open and show an error." }, - "onClose": { "type": "() => void" }, - "onError": { "type": "((error: CometChat.CometChatException) => void) | null" } - }, - "config": { - "closeOnOutsideClick": { "type": "boolean", "default": true }, - "className": { "type": "string" } - } - }, - "types": { - "CometChatFlagMessageDialogRootProps": "Root overlay props", - "CometChatFlagMessageDialogHeaderProps": "Header sub-component props", - "CometChatFlagMessageDialogReasonsProps": "Reasons list sub-component props", - "CometChatFlagMessageDialogRemarkProps": "Remark input sub-component props", - "CometChatFlagMessageDialogActionsProps": "Actions (cancel/submit) sub-component props", - "CometChatFlagMessageDialogContextValue": "Full context value" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatFlagMessageDialog` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatFlagMessageDialog } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-flag-message-dialog` | +| Primary output | `onSubmit: (messageId: string, reasonId: string, remark?: string) => Promise` — submits the flag report | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; implement `onSubmit` (return `true` to close) and `onClose` to dismiss | +| Full props | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/group-action-bubble.mdx b/ui-kit/react/components/group-action-bubble.mdx index 64b9882e5..190edd8fb 100644 --- a/ui-kit/react/components/group-action-bubble.mdx +++ b/ui-kit/react/components/group-action-bubble.mdx @@ -5,24 +5,18 @@ description: "A self-extracting bubble that renders group action system messages --- -```json -{ - "component": "CometChatGroupActionBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatGroupActionBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting bubble for group membership system messages. Derives the localized action text from the SDK group-action message.", - "cssRootClass": ".cometchat-action-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The group-action message (member joined/left/added/kicked/banned/scope change). Drives all extraction." }, - "className": { "type": "string", "default": "undefined", "note": "Additional CSS class for the root element" } - } - }, - "rendersThrough": "CometChatActionBubble (base primitive)", - "usedBy": ["CometChatGroupActionPlugin"] -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatGroupActionBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatGroupActionBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-action-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/group-members.mdx b/ui-kit/react/components/group-members.mdx index e72705227..0da173864 100644 --- a/ui-kit/react/components/group-members.mdx +++ b/ui-kit/react/components/group-members.mdx @@ -4,120 +4,20 @@ description: "Scrollable list of members for a specific group with role-based ac --- -```json -{ - "component": "CometChatGroupMembers", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatGroupMembers } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable list of members for a specific group with role-based actions like kick, ban, and scope change.", - "cssRootClass": ".cometchat-group-members", - "primaryOutput": { - "prop": "onItemClick", - "type": "(member: CometChat.GroupMember) => void" - }, - "props": { - "data": { - "group": { - "type": "CometChat.Group", - "default": "none (required)", - "note": "The group whose members to display" - }, - "groupMemberRequestBuilder": { - "type": "CometChat.GroupMembersRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.GroupMembersRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - } - }, - "callbacks": { - "onItemClick": "(member: CometChat.GroupMember) => void", - "onSelect": "(member: CometChat.GroupMember, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void", - "onBack": "() => void" - }, - "visibility": { - "hideUserStatus": { "type": "boolean", "default": false }, - "hideSearch": { "type": "boolean", "default": false }, - "hideKickMemberOption": { "type": "boolean", "default": false }, - "hideBanMemberOption": { "type": "boolean", "default": false }, - "hideScopeChangeOption": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "selection": { - "selectionMode": { - "type": "CometChatGroupMembersSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(member: CometChat.GroupMember) => ReactNode", - "leadingView": "(member: CometChat.GroupMember) => ReactNode", - "titleView": "(member: CometChat.GroupMember) => ReactNode", - "subtitleView": "(member: CometChat.GroupMember) => ReactNode", - "trailingView": "(member: CometChat.GroupMember) => ReactNode", - "headerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(member: CometChat.GroupMember) => CometChatGroupMemberOption[]" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:group/member-added", - "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }", - "description": "Adds new members to the list" - }, - { - "name": "ui:group/member-kicked", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Removes the kicked member from the list" - }, - { - "name": "ui:group/member-banned", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Removes the banned member from the list" - }, - { - "name": "ui:group/member-scope-changed", - "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }", - "description": "Updates the member's scope/role display" - }, - { - "name": "ui:group/ownership-changed", - "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }", - "description": "Updates new owner's scope to owner and demotes previous owner to admin" - } - ], - "sdkListeners": [ - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onGroupMemberScopeChanged", - "onMemberAddedToGroup" - ], - "types": { - "CometChatGroupMemberOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(member: CometChat.GroupMember) => void" - }, - "CometChatGroupMembersSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatGroupMembers` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatGroupMembers } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-group-members` | +| Primary output | `onItemClick: (member: CometChat.GroupMember) => void` — emits the selected group member | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `group`; wire `onItemClick` (or `onSelect` in selection mode) to act on a member | +| Events received | `ui:group/member-added`, `ui:group/member-kicked`, `ui:group/member-banned`, `ui:group/member-scope-changed`, `ui:group/ownership-changed` — keeps the member list in sync — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Group membership changes (joins, leaves, kicks, bans, scope changes) — handled internally | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/groups.mdx b/ui-kit/react/components/groups.mdx index 629d53e25..6a685b2e3 100644 --- a/ui-kit/react/components/groups.mdx +++ b/ui-kit/react/components/groups.mdx @@ -4,134 +4,20 @@ description: "Searchable, scrollable list of groups with selection support and r --- -```json -{ - "component": "CometChatGroups", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatGroups } from \"@cometchat/chat-uikit-react\";", - "description": "Searchable, scrollable list of groups with selection support and real-time membership updates.", - "cssRootClass": ".cometchat-groups", - "primaryOutput": { - "prop": "onItemClick", - "type": "(group: CometChat.Group) => void" - }, - "props": { - "data": { - "groupsRequestBuilder": { - "type": "CometChat.GroupsRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.GroupsRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - }, - "activeGroup": { - "type": "CometChat.Group", - "default": "undefined" - } - }, - "callbacks": { - "onItemClick": "(group: CometChat.Group) => void", - "onSelect": "(group: CometChat.Group, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void" - }, - "visibility": { - "hideGroupType": { "type": "boolean", "default": false }, - "hideSearch": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "selection": { - "selectionMode": { - "type": "CometChatGroupsSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(group: CometChat.Group) => ReactNode", - "leadingView": "(group: CometChat.Group) => ReactNode", - "titleView": "(group: CometChat.Group) => ReactNode", - "subtitleView": "(group: CometChat.Group) => ReactNode", - "trailingView": "(group: CometChat.Group) => ReactNode", - "headerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(group: CometChat.Group) => CometChatGroupOption[]" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:group/created", - "payload": "{ group: CometChat.Group }", - "description": "Adds the new group to the list" - }, - { - "name": "ui:group/deleted", - "payload": "{ group: CometChat.Group }", - "description": "Removes the group from the list" - }, - { - "name": "ui:group/left", - "payload": "{ group: CometChat.Group }", - "description": "Removes (private) or updates (public) the group" - }, - { - "name": "ui:group/member-joined", - "payload": "{ joinedGroup: CometChat.Group }", - "description": "Updates the group (member count)" - }, - { - "name": "ui:group/member-added", - "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }", - "description": "Updates the group" - }, - { - "name": "ui:group/member-kicked", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Updates the group" - }, - { - "name": "ui:group/member-banned", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Updates the group" - }, - { - "name": "ui:group/member-scope-changed", - "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }", - "description": "Updates the group" - }, - { - "name": "ui:group/ownership-changed", - "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }", - "description": "Updates the group" - } - ], - "sdkListeners": [ - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onMemberAddedToGroup" - ], - "types": { - "CometChatGroupOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(group: CometChat.Group) => void" - }, - "CometChatGroupsSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatGroups` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatGroups } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-groups` | +| Primary output | `onItemClick: (group: CometChat.Group) => void` — emits the selected group to open | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Emits the selected group; wire `onItemClick` to open it (mount MessageHeader/List/Composer) — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) | +| Events received | `ui:group/created`, `ui:group/deleted`, `ui:group/left`, and `ui:group/member-*` / `ui:group/ownership-changed` — keeps the list in sync — see the [Event System](/ui-kit/react/event-system#user--group-actions) | +| SDK listeners (automatic) | Group membership changes — handled internally | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/image-bubble.mdx b/ui-kit/react/components/image-bubble.mdx index 1a2508976..d9772d202 100644 --- a/ui-kit/react/components/image-bubble.mdx +++ b/ui-kit/react/components/image-bubble.mdx @@ -5,27 +5,18 @@ description: "A batch-aware bubble that renders one or more image attachments wi --- -```json -{ - "component": "CometChatImagesBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatImagesBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware image bubble. Extracts image attachments and caption from a MediaMessage; renders adaptive grid layouts (single, 2-col, 2x2, overflow) and opens a fullscreen gallery viewer.", - "cssRootClass": ".cometchat-images-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "placeholderImage": { "type": "string" }, - "onImageClicked": { "type": "(attachment, index) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatImagesBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatImagesBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-images-bubble` | +| Primary output | `onImageClicked(attachment, index)` — opens the fullscreen gallery | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/incoming-call.mdx b/ui-kit/react/components/incoming-call.mdx index 31ae55f5d..b503247fc 100644 --- a/ui-kit/react/components/incoming-call.mdx +++ b/ui-kit/react/components/incoming-call.mdx @@ -4,71 +4,20 @@ description: "Displays an incoming call notification with caller info, accept/de --- -```json -{ - "component": "CometChatIncomingCall", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatIncomingCall } from \"@cometchat/chat-uikit-react\";", - "description": "Displays an incoming call notification with caller info, accept/decline buttons, and transitions to the ongoing call screen.", - "cssRootClass": ".cometchat-incoming-call", - "primaryOutput": { - "prop": "onAccept", - "type": "(call: CometChat.Call) => void" - }, - "props": { - "callbacks": { - "onAccept": "(call: CometChat.Call) => void", - "onDecline": "(call: CometChat.Call) => void", - "onCallEnded": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "sound": { - "disableSoundForCalls": { "type": "boolean", "default": false }, - "customSoundForCalls": { "type": "string", "default": "built-in" } - }, - "configuration": { - "callSettingsBuilder": { - "type": "(call: CometChat.Call) => any", - "default": "undefined", - "note": "Custom call settings for the ongoing call session after accepting" - } - }, - "viewSlots": { - "itemView": "(call: CometChat.Call) => ReactNode", - "leadingView": "(call: CometChat.Call) => ReactNode", - "titleView": "(call: CometChat.Call) => ReactNode", - "subtitleView": "(call: CometChat.Call) => ReactNode", - "trailingView": "(call: CometChat.Call) => ReactNode" - } - }, - "events": [ - { - "name": "ui:call/rejected", - "payload": "{ call }", - "description": "Call declined by user" - }, - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Ongoing call ended" - } - ], - "sdkListeners": [ - "onIncomingCallReceived", - "onIncomingCallCancelled", - "onOutgoingCallAccepted", - "onOutgoingCallRejected" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined" - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatIncomingCall` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-incoming-call` | +| **Primary output** | `onAccept: (call: CometChat.Call) => void` — fires when the call is accepted | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| **Stitching** | Mount at the app root to catch incoming calls; wire `onAccept` / `onDecline` | +| **Events emitted** | `ui:call/rejected`, `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | +| **SDK listeners (automatic)** | Incoming and outgoing call lifecycle — handled internally | +| **Full props** | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/message-bubble.mdx b/ui-kit/react/components/message-bubble.mdx index ff35e8223..5cbc22f43 100644 --- a/ui-kit/react/components/message-bubble.mdx +++ b/ui-kit/react/components/message-bubble.mdx @@ -4,61 +4,18 @@ description: "A shared wrapper component that renders all message types with com --- -```json -{ - "component": "CometChatMessageBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Layout shell that wraps plugin-rendered bubble content with shared chrome — avatar, sender name, bubble background, timestamp, receipts, thread replies, reactions, and context menu.", - "cssRootClass": ".cometchat-message-bubble", - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true }, - "alignment": { "type": "'left' | 'right' | 'center'", "required": true }, - "contentView": { "type": "ReactNode", "required": true, "note": "Inner content from the plugin's renderBubble()." }, - "group": { "type": "CometChat.Group" }, - "options": { "type": "CometChatMessageOption[]" }, - "quickOptionsCount": { "type": "number", "default": 2 } - }, - "visibility": { - "hideAvatar": { "type": "boolean", "default": false }, - "forceShowAvatar": { "type": "boolean", "default": false }, - "hideSenderName": { "type": "boolean", "default": false }, - "hideTimestamp": { "type": "boolean", "default": false }, - "hideThreadView": { "type": "boolean", "default": false }, - "hideReceipts": { "type": "boolean", "note": "Reads from GlobalConfig if not set." }, - "showError": { "type": "boolean", "default": false }, - "disableInteraction": { "type": "boolean", "default": false } - }, - "config": { - "messageSentAtDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "isSelected": { "type": "boolean" }, - "ariaPosinset": { "type": "number" }, - "ariaSetsize": { "type": "number" }, - "className": { "type": "string" }, - "setRef": { "type": "Ref" }, - "includeBottomViewHeight": { "type": "boolean", "default": false }, - "toggleOptionsVisibility": { "type": "boolean" } - }, - "viewSlots": { - "leadingView": "((message) => ReactNode) | null", - "headerView": "((message) => ReactNode) | null", - "statusInfoView": "((message) => ReactNode) | null", - "footerView": "((message) => ReactNode) | null", - "threadView": "((message) => ReactNode) | null", - "replyView": "ReactNode | null", - "bottomView": "((message) => ReactNode) | null" - }, - "callbacks": { - "onAvatarClick": "(user: CometChat.User) => void", - "onThreadRepliesClick": "(message: CometChat.BaseMessage) => void", - "onOptionClick": "(option: CometChatMessageOption, message: CometChat.BaseMessage) => void", - "onReactionChipClick": "(messageId: number, emoji: string) => void", - "onReactorClick": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void" - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatMessageBubble` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatMessageBubble } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-message-bubble` | +| **Primary output** | None — renders from the SDK message (it renders provided content; there is no single primary callback). | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user. | +| **Stitching** | Feed `message`, `alignment`, and a plugin-rendered `contentView`; it supplies the surrounding chrome. | +| **Full props** | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/message-composer.mdx b/ui-kit/react/components/message-composer.mdx index a86b72129..67f436ceb 100644 --- a/ui-kit/react/components/message-composer.mdx +++ b/ui-kit/react/components/message-composer.mdx @@ -4,133 +4,21 @@ description: "Rich text input with attachments, emoji, voice recording, mentions --- -```json -{ - "component": "CometChatMessageComposer", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageComposer } from \"@cometchat/chat-uikit-react\";", - "description": "Rich text input with attachments, emoji, voice recording, mentions, and formatting for sending messages.", - "cssRootClass": ".cometchat-message-composer", - "primaryOutput": { - "prop": "onSendButtonClick", - "type": "(message: CometChat.BaseMessage, mode?: 'send' | 'edit') => void" - }, - "props": { - "entity": { - "user": { "type": "CometChat.User", "default": "undefined" }, - "group": { "type": "CometChat.Group", "default": "undefined" }, - "parentMessageId": { "type": "number", "default": "undefined" } - }, - "layout": { - "layout": { - "type": "CometChatMessageComposerLayout", - "values": ["'compact'", "'multiline'"], - "default": "'compact'" - } - }, - "textInput": { - "initialText": { "type": "string", "default": "undefined" }, - "text": { "type": "string", "default": "undefined", "note": "Controlled mode — consumer owns state" }, - "placeholder": { "type": "string", "default": "'Type a message...'" }, - "enterKeyBehavior": { - "type": "'send' | 'newline' | 'none'", - "default": "'send'" - }, - "maxInputHeight": { "type": "number", "default": "200" } - }, - "richText": { - "enableRichTextEditor": { "type": "boolean", "default": false }, - "hideRichTextFormattingOptions": { "type": "boolean", "default": false }, - "showBubbleMenuOnSelection": { "type": "boolean", "default": false } - }, - "editReply": { - "messageToEdit": { "type": "CometChat.TextMessage | null", "default": "null" }, - "messageToReply": { "type": "CometChat.BaseMessage | null", "default": "null" } - }, - "attachments": { - "attachmentOptions": { "type": "CometChatComposerAttachmentOption[]", "default": "undefined" }, - "hideAttachmentOptions": { "type": "CometChatAttachmentHideOptions", "default": "undefined" }, - "showAttachmentPreview": { "type": "boolean", "default": true }, - "enableMultipleAttachments": { "type": "boolean", "default": true, "note": "Enable multi-attachment staging tray and batch send. Set false for legacy single-select behavior." }, - "disableDragAndDrop": { "type": "boolean", "default": false, "note": "Disable drag-and-drop file upload." }, - "allowedFileTypes": { "type": "string[]", "default": "undefined" } - }, - "hideButtons": { - "hideAttachmentButton": { "type": "boolean", "default": false }, - "hideEmojiKeyboardButton": { "type": "boolean", "default": false }, - "hideVoiceRecordingButton": { "type": "boolean", "default": false }, - "hideStickersButton": { "type": "boolean", "default": false }, - "hideAIButton": { "type": "boolean", "default": true }, - "hideLiveReaction": { "type": "boolean", "default": false }, - "hideSendButton": { "type": "boolean", "default": false }, - "hideError": { "type": "boolean", "default": false } - }, - "mentions": { - "textFormatters": { "type": "CometChatTextFormatter[]", "default": "undefined" }, - "disableMentions": { "type": "boolean", "default": false }, - "disableMentionAll": { "type": "boolean", "default": false }, - "mentionAllLabel": { "type": "string", "default": "'all'" }, - "mentionsUsersRequestBuilder": { "type": "CometChat.UsersRequestBuilder", "default": "undefined" }, - "mentionsGroupMembersRequestBuilder": { "type": "CometChat.GroupMembersRequestBuilder", "default": "undefined" } - }, - "sound": { - "disableTypingEvents": { "type": "boolean", "default": false }, - "disableSoundForMessage": { "type": "boolean", "default": false }, - "customSoundForMessage": { "type": "string", "default": "undefined" } - }, - "misc": { - "disableAutoFocusOnMobile": { "type": "boolean", "default": true }, - "liveReactionIcon": { "type": "string", "default": "undefined" }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "customViews": { - "attachmentButtonIconView": "ReactNode", - "voiceRecordingButtonIconView": "ReactNode", - "emojiButtonIconView": "ReactNode", - "sendButtonView": "ReactNode", - "auxiliaryButtonView": "ReactNode", - "headerView": "ReactNode" - }, - "callbacks": { - "onTextChange": "(text: string) => void", - "onSendButtonClick": "(message: CometChat.BaseMessage, mode?: 'send' | 'edit') => void", - "sendTextMessageOverride": "(text: string, richTextHtml?: string) => string", - "onError": "(error: unknown) => void", - "onClosePreview": "() => void", - "onAttachmentAdded": "(file: File) => void", - "onAttachmentRemoved": "(file: File) => void", - "onMentionSelected": "(user: CometChat.User | CometChat.GroupMember) => void" - } - }, - "events": { - "emitted": [ - { "name": "ui:message/sent", "payload": "{ message, status }", "description": "Message sent (inprogress → success/error)" }, - { "name": "ui:compose/edit", "payload": "{ message, status }", "description": "Message edit (inprogress → success/error/cancelled)" }, - { "name": "ui:compose/reply", "payload": "{ message, status }", "description": "Reply context set/cleared" }, - { "name": "ui:compose/recording-started", "payload": "{ composerInstanceId }", "description": "Voice recording started (stops other instances)" } - ], - "received": [ - { "name": "ui:compose/edit", "payload": "{ message, status: 'inprogress' }", "description": "Enters edit mode for the message" }, - { "name": "ui:compose/reply", "payload": "{ message, status: 'inprogress' }", "description": "Sets reply-to message" }, - { "name": "ui:compose/text", "payload": "{ text }", "description": "Sets the composer text programmatically" }, - { "name": "ui:compose/recording-started", "payload": "{ composerInstanceId }", "description": "Stops own recording if another instance started" } - ] - }, - "sdkListeners": [], - "types": { - "CometChatMessageComposerLayout": "'compact' | 'multiline'", - "CometChatAttachmentHideOptions": { - "image": "boolean | undefined", - "video": "boolean | undefined", - "audio": "boolean | undefined", - "file": "boolean | undefined", - "polls": "boolean | undefined", - "collaborativeDocument": "boolean | undefined", - "collaborativeWhiteboard": "boolean | undefined" - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageComposer` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageComposer } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-composer` | +| Primary output | `onSendButtonClick: (message: CometChat.BaseMessage, mode?: 'send' \| 'edit') => void` — emits the sent/edited message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; the AI-assist button requires [AI features](/ui-kit/react/ai-features) enabled in the Dashboard | +| Stitching | Pass `user`, `group`, or `parentMessageId`; the composer sends via the SDK and emits `onSendButtonClick` | +| Events emitted | `ui:message/sent`, `ui:compose/edit`, `ui:compose/reply`, `ui:compose/recording-started` — see [Event System](/ui-kit/react/event-system) | +| Events received | `ui:compose/edit`, `ui:compose/reply`, `ui:compose/text`, `ui:compose/recording-started` (drives edit/reply/text mode) | +| SDK listeners (automatic) | None; emits typing-indicator events via the SDK when `disableTypingEvents` is `false` | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/message-header.mdx b/ui-kit/react/components/message-header.mdx index eef8fd6d1..9488ca871 100644 --- a/ui-kit/react/components/message-header.mdx +++ b/ui-kit/react/components/message-header.mdx @@ -4,158 +4,20 @@ description: "Toolbar displaying conversation details with avatar, name, presenc --- -```json -{ - "component": "CometChatMessageHeader", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageHeader } from \"@cometchat/chat-uikit-react\";", - "description": "Toolbar displaying conversation details with avatar, name, presence status, typing indicator, and call buttons.", - "cssRootClass": ".cometchat-message-header", - "primaryOutput": { - "prop": "onItemClick", - "type": "(entity: CometChat.User | CometChat.Group) => void" - }, - "props": { - "data": { - "user": { - "type": "CometChat.User", - "default": "undefined", - "note": "For 1-on-1 conversations. Mutually exclusive with group." - }, - "group": { - "type": "CometChat.Group", - "default": "undefined", - "note": "For group conversations. Mutually exclusive with user." - }, - "callSettingsBuilder": { - "type": "any", - "default": "GlobalConfig.callSettingsBuilder or built-in default", - "note": "Custom call settings builder for ongoing call sessions." - }, - "lastActiveAtDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "relative time format" - }, - "summaryGenerationMessageCount": { - "type": "number", - "default": 1000 - } - }, - "callbacks": { - "onBack": "() => void", - "onItemClick": "(entity: CometChat.User | CometChat.Group) => void", - "onSearchOptionClicked": "() => void", - "onSummaryClick": "() => void", - "onVoiceCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onVideoCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideUserStatus": { "type": "boolean", "default": false }, - "hideBackButton": { "type": "boolean", "default": false }, - "showSearchOption": { "type": "boolean", "default": true }, - "showConversationSummaryButton": { "type": "boolean", "default": false }, - "enableAutoSummaryGeneration": { "type": "boolean", "default": false }, - "hideVoiceCallButton": { "type": "boolean", "default": false }, - "hideVideoCallButton": { "type": "boolean", "default": false } - }, - "viewSlots": { - "leadingView": "ReactNode", - "titleView": "ReactNode", - "subtitleView": "ReactNode", - "trailingView": "ReactNode", - "auxiliaryButtonView": "ReactNode" - } - }, - "eventsEmitted": [], - "eventsReceived": [ - { - "name": "ui:call/rejected", - "payload": "{ call }", - "description": "Re-enables call buttons after incoming call rejection" - }, - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Resets all call state (re-enables buttons, hides call screens)" - }, - { - "name": "ui:call/join", - "payload": "{ sessionId, isAudioOnly, group }", - "description": "Starts a direct call (user clicked Join on meeting bubble)" - }, - { - "name": "ui:active-chat/changed", - "payload": "{ unreadCount, ... }", - "description": "Auto-triggers summary when unread >= 15 (if enabled)" - }, - { - "name": "ui:group/member-added", - "payload": "{ group, members, messages }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-kicked", - "payload": "{ group, user, message }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-banned", - "payload": "{ group, user, message }", - "description": "Updates group member count" - }, - { - "name": "ui:group/left", - "payload": "{ group }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-joined", - "payload": "{ joinedGroup }", - "description": "Updates group member count" - }, - { - "name": "ui:group/ownership-changed", - "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-scope-changed", - "payload": "{ group, user, newScope }", - "description": "Updates group member count" - } - ], - "sdkListeners": [ - "onUserOnline", - "onUserOffline", - "onTypingStarted", - "onTypingEnded", - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onMemberAddedToGroup", - "onIncomingCallReceived", - "onOutgoingCallAccepted", - "onOutgoingCallRejected", - "onIncomingCallCancelled" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageHeader` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-header` | +| Primary output | `onItemClick`: `(entity: CometChat.User \| CometChat.Group) => void` — opens the chat entity's details | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; the summary button requires the [Conversation Summary AI feature](/ui-kit/react/ai-features#conversation-summary) enabled in the Dashboard | +| Stitching | Pass `user` or `group`; wire `onItemClick` (and call/summary callbacks) as needed | +| Events received | `ui:call/*`, `ui:active-chat/changed`, and `ui:group/*` events keep the header in sync — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Presence, typing, group membership, and call listeners attached internally | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/message-information.mdx b/ui-kit/react/components/message-information.mdx index 13aafd2e0..23787fc40 100644 --- a/ui-kit/react/components/message-information.mdx +++ b/ui-kit/react/components/message-information.mdx @@ -4,44 +4,18 @@ description: "Displays detailed message information including delivery and read --- -```json -{ - "component": "CometChatMessageInformation", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageInformation } from \"@cometchat/chat-uikit-react\";", - "description": "Displays detailed message information including delivery and read receipts for 1-on-1 and group conversations.", - "cssRootClass": ".cometchat-message-information", - "primaryOutput": { - "prop": "onClose", - "type": "() => void" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show information for." }, - "messageInfoDateTimeFormat": { "type": "CometChatMessageInformationCalendarObject", "note": "Custom date format for receipt timestamps (read/delivered)." }, - "messageSentAtDateTimeFormat": { "type": "CometChatMessageInformationCalendarObject", "note": "Format for the sent-at timestamp on the message bubble preview." }, - "textFormatters": { "type": "CometChatTextFormatter[]", "note": "Text formatters for the message bubble preview." }, - "showScrollbar": { "type": "boolean", "default": false, "note": "Whether to show the scrollbar in the content area." }, - "className": { "type": "string", "note": "Optional custom className for the root element." } - }, - "callbacks": { - "onClose": { "type": "() => void", "note": "Called when the panel close button is clicked." }, - "onError": { "type": "(error: unknown) => void", "note": "Called when an SDK error occurs." } - }, - "visibility": { - "showScrollbar": { "type": "boolean", "default": "false", "note": "Whether to show the scrollbar in the content area." } - } - }, - "types": { - "CometChatMessageInformationRootProps": "Root provider props", - "CometChatMessageInformationHeaderProps": "Header sub-component props", - "CometChatMessageInformationMessagePreviewProps": "Message preview sub-component props", - "CometChatMessageInformationReceiptListProps": "Receipt list sub-component props", - "CometChatUserReceiptInfo": "Combined user receipt info (user + readAt + deliveredAt)", - "CometChatMessageInformationContextValue": "Context value for sub-components" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageInformation` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageInformation } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-information` | +| Primary output | `onClose: () => void` — closes the information panel | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; wire `onClose` to dismiss the panel | +| Full props | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/message-list.mdx b/ui-kit/react/components/message-list.mdx index e18f7a6a5..d97a40d19 100644 --- a/ui-kit/react/components/message-list.mdx +++ b/ui-kit/react/components/message-list.mdx @@ -4,207 +4,21 @@ description: "Scrollable message feed with plugin-based bubble rendering, reacti --- -```json -{ - "component": "CometChatMessageList", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageList } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable message feed with plugin-based bubble rendering, reactions, receipts, threads, and real-time updates.", - "cssRootClass": ".cometchat-message-list", - "primaryOutput": { - "prop": "onThreadRepliesClick", - "type": "(message: CometChat.BaseMessage) => void" - }, - "props": { - "entity": { - "user": { - "type": "CometChat.User", - "default": "undefined", - "note": "For 1-on-1 chat. Mutually exclusive with group." - }, - "group": { - "type": "CometChat.Group", - "default": "undefined", - "note": "For group chat. Mutually exclusive with user." - }, - "parentMessageId": { - "type": "number", - "default": "undefined", - "note": "Enables thread mode — fetches replies to this message." - } - }, - "data": { - "messagesRequestBuilder": { - "type": "CometChat.MessagesRequestBuilder", - "default": "SDK default (limit 30)", - "note": "Pass the builder instance, not the result of .build()" - }, - "reactionsRequestBuilder": { - "type": "CometChat.ReactionsRequestBuilder", - "default": "undefined" - }, - "messageTypes": { - "type": "string[]", - "default": "Plugin registry types" - }, - "messageCategories": { - "type": "string[]", - "default": "Plugin registry categories" - }, - "goToMessageId": { - "type": "number", - "default": "undefined", - "note": "Jump to a specific message (e.g., from search or deep link)" - }, - "startFromUnreadMessages": { - "type": "boolean", - "default": false - }, - "loadLastAgentConversation": { - "type": "boolean", - "default": false - } - }, - "visibility": { - "hideReceipts": { "type": "boolean", "default": false }, - "hideStickyDate": { "type": "boolean", "default": false }, - "hideDateSeparator": { "type": "boolean", "default": false }, - "hideAvatar": { "type": "boolean", "default": false }, - "hideGroupActionMessages": { "type": "boolean", "default": false }, - "hideModerationView": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false }, - "showSmartReplies": { "type": "boolean", "default": false }, - "showConversationStarters": { "type": "boolean", "default": false }, - "showMarkAsUnreadOption": { "type": "boolean", "default": false }, - "disableTruncation": { "type": "boolean", "default": false }, - "isAgentChat": { "type": "boolean", "default": false } - }, - "optionToggles": { - "hideReplyOption": { "type": "boolean", "default": false }, - "hideReplyInThreadOption": { "type": "boolean", "default": false }, - "hideEditMessageOption": { "type": "boolean", "default": false }, - "hideDeleteMessageOption": { "type": "boolean", "default": false }, - "hideCopyMessageOption": { "type": "boolean", "default": false }, - "hideReactionOption": { "type": "boolean", "default": false }, - "hideMessageInfoOption": { "type": "boolean", "default": false }, - "hideFlagMessageOption": { "type": "boolean", "default": false }, - "hideMessagePrivatelyOption": { "type": "boolean", "default": false }, - "hideTranslateMessageOption": { "type": "boolean", "default": false }, - "hideFlagRemarkField": { "type": "boolean", "default": false }, - "quickOptionsCount": { "type": "number", "default": 3 } - }, - "dateFormatting": { - "separatorDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "stickyDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "messageSentAtDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "messageInfoDateTimeFormat": { "type": "CometChatDateFormatConfig" } - }, - "alignment": { - "messageAlignment": { - "type": "CometChatMessageListAlignment", - "values": ["0 (left)", "1 (standard)"], - "default": "1 (standard)" - } - }, - "sound": { - "disableSoundForMessages": { "type": "boolean", "default": false }, - "customSoundForMessages": { "type": "string", "default": "built-in" } - }, - "ai": { - "smartRepliesKeywords": { - "type": "string[]", - "default": "['what','when','why','who','where','how','?']" - }, - "smartRepliesDelayDuration": { - "type": "number", - "default": 10000 - } - }, - "callbacks": { - "onThreadRepliesClick": "(message: CometChat.BaseMessage) => void", - "onAvatarClick": "(user: CometChat.User) => void", - "onEditMessage": "(message: CometChat.BaseMessage) => void", - "onReplyMessage": "(message: CometChat.BaseMessage) => void", - "onReactionClick": "(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void", - "onReactionListItemClick": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void", - "onActiveChatChanged": "(data: { user?, group?, message?, unreadMessageCount? }) => void", - "onMessageRead": "(message: CometChat.BaseMessage) => void", - "onMessageDeleted": "(message: CometChat.BaseMessage) => void", - "onConversationMarkedAsRead": "(conversation: CometChat.Conversation) => void", - "onConversationUpdated": "(conversation: CometChat.Conversation) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "viewSlots": { - "bubbleView": "(message: CometChat.BaseMessage, loggedInUser: CometChat.User) => ReactNode", - "headerView": "ReactNode", - "footerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode" - } - }, - "events": [ - { - "name": "ui:message/read", - "payload": "{ message }", - "description": "Message marked as read" - }, - { - "name": "ui:message/deleted", - "payload": "{ message }", - "description": "Message deleted by user" - }, - { - "name": "ui:active-chat/changed", - "payload": "{ user?, group?, message?, unreadMessageCount? }", - "description": "Active chat context changed on init" - }, - { - "name": "ui:conversation/read", - "payload": "{ conversationId }", - "description": "Conversation marked as read" - }, - { - "name": "ui:conversation/updated", - "payload": "{ conversation }", - "description": "Conversation updated (mark-as-unread)" - } - ], - "sdkListeners": [ - "onTextMessageReceived", - "onMediaMessageReceived", - "onCustomMessageReceived", - "onInteractiveMessageReceived", - "onTypingStarted", - "onTypingEnded", - "onMessagesDelivered", - "onMessagesRead", - "onMessagesDeliveredToAll", - "onMessagesReadByAll", - "onMessageEdited", - "onMessageDeleted", - "onTransientMessageReceived" - ], - "types": { - "CometChatMessageListAlignment": { - "left": 0, - "standard": 1 - }, - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageList` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageList } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-list` | +| Primary output | `onThreadRepliesClick: (message: CometChat.BaseMessage) => void` — opens the message's thread | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; Smart Replies / Conversation Starters require the matching [AI features](/ui-kit/react/ai-features) enabled in the Dashboard | +| Stitching | Pass `user`, `group`, or `parentMessageId`; wire `onThreadRepliesClick` to open a thread | +| Events emitted | `ui:message/read`, `ui:message/deleted`, `ui:active-chat/changed`, `ui:conversation/read`, `ui:conversation/updated` — see [Event System](/ui-kit/react/event-system) | +| Events received | `ui:message/sent`, `ui:compose/edit`, `ui:group/*` member and lifecycle events, `ui:call/*` events — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Incoming messages, typing, receipts (delivered/read), edits/deletes, transient messages | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/notification-feed.mdx b/ui-kit/react/components/notification-feed.mdx index f1e367c1e..fe47845ef 100644 --- a/ui-kit/react/components/notification-feed.mdx +++ b/ui-kit/react/components/notification-feed.mdx @@ -4,57 +4,19 @@ description: "Full-screen notification feed component with category filtering, c --- -```json -{ - "component": "CometChatNotificationFeed", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatNotificationFeed } from \"@cometchat/chat-uikit-react\";", - "description": "Full-screen notification feed with category filtering, timestamp grouping, card rendering via @cometchat/cards-react, real-time updates, and automatic engagement reporting.", - "cssRootClass": ".cometchat-notification-feed", - "props": { - "data": { - "title": { "type": "string", "default": "\"Notifications\"" }, - "notificationFeedRequestBuilder": { "type": "NotificationFeedRequestBuilder", "default": "SDK default (20 per page)" }, - "notificationCategoriesRequestBuilder": { "type": "NotificationCategoriesRequestBuilder", "default": "SDK default (50 per page)" } - }, - "callbacks": { - "onItemClick": "(feedItem: NotificationFeedItem) => void", - "onActionClick": "(feedItem: NotificationFeedItem, action: CardAction) => void", - "onError": "(error: CometChat.CometChatException) => void", - "onBackPress": "() => void" - }, - "visibility": { - "showHeader": { "type": "boolean", "default": true }, - "showBackButton": { "type": "boolean", "default": false }, - "showFilterChips": { "type": "boolean", "default": true } - }, - "viewSlots": { - "headerView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "loadingView": "ReactNode", - "itemView": "(item: NotificationFeedItem) => ReactNode" - }, - "cards": { - "cardThemeMode": { "type": "\"auto\" | \"light\" | \"dark\"", "default": "\"auto\"" }, - "cardThemeOverride": { "type": "Record", "default": "undefined" } - } - }, - "automaticBehaviors": [ - "Real-time updates via WebSocket listener", - "Delivery reporting on fetch", - "Read reporting on viewport visibility (IntersectionObserver)", - "Unread count polling every 30 seconds", - "Infinite scroll pagination", - "Timestamp grouping (Today, Yesterday, day name, date)", - "Category filter chips with unread badges", - "Mark all read button" - ], - "additionalExports": { - "useNotificationUnreadCount": "Hook for tracking unread count with shared polling" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatNotificationFeed` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-notification-feed` | +| Primary output | `onItemClick: (feedItem: NotificationFeedItem) => void` — emits the clicked feed item | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus [Campaigns](/ui-kit/react/campaigns) configured in the Dashboard | +| Stitching | Wire `onItemClick` / `onActionClick` to route the tapped notification (see [Campaigns](/ui-kit/react/campaigns)) | +| SDK listeners (automatic) | Real-time feed updates, delivery/read reporting, and unread-count polling — handled internally | +| Full props | See [Props](#props) | + `CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a card using `@cometchat/cards-react`. It handles fetching, pagination, category filtering, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically. diff --git a/ui-kit/react/components/outgoing-call.mdx b/ui-kit/react/components/outgoing-call.mdx index aee19e4ea..57db7598b 100644 --- a/ui-kit/react/components/outgoing-call.mdx +++ b/ui-kit/react/components/outgoing-call.mdx @@ -4,46 +4,18 @@ description: "Displays the outgoing call screen with receiver info and a cancel --- -```json -{ - "component": "CometChatOutgoingCall", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatOutgoingCall } from \"@cometchat/chat-uikit-react\";", - "description": "Displays the outgoing call screen with receiver info and a cancel button while waiting for the call to be answered.", - "cssRootClass": ".cometchat-outgoing-call", - "primaryOutput": { - "prop": "onCallCanceled", - "type": "() => void" - }, - "props": { - "data": { - "call": { - "type": "CometChat.Call", - "required": true, - "note": "The CometChat call object representing the outgoing call" - } - }, - "callbacks": { - "onCallCanceled": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "sound": { - "disableSoundForCalls": { "type": "boolean", "default": false }, - "customSoundForCalls": { "type": "string", "default": "built-in" } - }, - "viewSlots": { - "titleView": "ReactNode", - "subtitleView": "ReactNode", - "avatarView": "ReactNode", - "cancelButtonView": "ReactNode" - } - }, - "events": [], - "eventsReceived": [], - "sdkListeners": [], - "types": {} -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatOutgoingCall` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-outgoing-call` | +| Primary output | `onCallCanceled: () => void` — fires when the user cancels the call | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the outgoing `call` object; wire `onCallCanceled` to dismiss the screen | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/poll-bubble.mdx b/ui-kit/react/components/poll-bubble.mdx index 18dc19abb..f3c371d70 100644 --- a/ui-kit/react/components/poll-bubble.mdx +++ b/ui-kit/react/components/poll-bubble.mdx @@ -5,26 +5,18 @@ description: "A self-extracting bubble that renders a poll with its question, se --- -```json -{ - "component": "CometChatPollBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatPollBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting poll bubble. Derives the question, options, vote counts, totals, and the logged-in user's vote from the message metadata.", - "cssRootClass": ".cometchat-poll-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.CustomMessage", "required": true, "note": "Contains poll data in its metadata; drives all extraction." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "disableInteraction": { "type": "boolean", "default": false }, - "onVoteSubmit": { "type": "(event: CometChatPollVoteEvent) => void" }, - "onVoteError": { "type": "(event: CometChatPollVoteErrorEvent) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatPollBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatPollBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-poll-bubble` | +| Primary output | `onVoteSubmit: (event: CometChatPollVoteEvent) => void` — emits the submitted vote | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Polls extension](/fundamentals/polls) enabled in the Dashboard | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/reaction-list.mdx b/ui-kit/react/components/reaction-list.mdx index f2d583487..60b543f59 100644 --- a/ui-kit/react/components/reaction-list.mdx +++ b/ui-kit/react/components/reaction-list.mdx @@ -4,39 +4,18 @@ description: "Standalone panel showing who reacted to a message, with emoji tab --- -```json -{ - "component": "CometChatReactionList", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatReactionList } from \"@cometchat/chat-uikit-react\";", - "description": "Standalone panel showing who reacted to a message, with emoji tab filtering, pagination, and optimistic removal for the current user.", - "cssRootClass": ".cometchat-reaction-list", - "primaryOutput": { - "prop": "onItemClick", - "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show reactions for." }, - "reactionsRequestBuilder": { "type": "CometChat.ReactionsRequestBuilder" } - }, - "callbacks": { - "onItemClick": { "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void", "note": "Fires only for current user's reactions (to remove)." }, - "onEmpty": { "type": "() => void", "note": "Fires when all reactions are removed. Parent should close the panel." }, - "onError": { "type": "(error: unknown) => void" } - } - }, - "types": { - "CometChatReactionListRootProps": "Root provider props", - "CometChatReactionListTabsProps": "Emoji tab bar props", - "CometChatReactionListItemsProps": "Scrollable reactor list props", - "CometChatReactionListLoadingStateProps": "Shimmer loading state props", - "CometChatReactionListErrorStateProps": "Error state props", - "CometChatReactionListEmptyStateProps": "Empty state props", - "CometChatReactionListContextValue": "Full context value" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatReactionList` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatReactionList } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-reaction-list` | +| Primary output | `onItemClick: (reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void` — removes the current user's reaction | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; wire `onEmpty` to close the panel when all reactions are removed | +| Full props | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/reactions.mdx b/ui-kit/react/components/reactions.mdx index 2b0a59cb7..19e345008 100644 --- a/ui-kit/react/components/reactions.mdx +++ b/ui-kit/react/components/reactions.mdx @@ -4,41 +4,18 @@ description: "Displays emoji reaction chips on message bubbles with hover toolti --- -```json -{ - "component": "CometChatReactions", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatReactions } from \"@cometchat/chat-uikit-react\";", - "description": "Displays emoji reaction chips on message bubbles with hover tooltips, a full reactor list, and overflow handling.", - "cssRootClass": ".cometchat-reactions", - "primaryOutput": { - "prop": "onReactionClick", - "type": "(emoji: string, message: CometChat.BaseMessage) => void" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show reactions for." }, - "alignment": { "type": "'left' | 'right' | 'center'", "default": "'left'" }, - "reactionsRequestBuilder": { "type": "CometChat.ReactionsRequestBuilder" } - }, - "callbacks": { - "onReactionClick": { "type": "(emoji: string, message: CometChat.BaseMessage) => void" }, - "onReactorClick": { "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void" }, - "onError": { "type": "(error: unknown) => void" } - }, - "config": { - "hoverDebounceTime": { "type": "number", "note": "Debounce (ms) before showing the hover tooltip." } - } - }, - "types": { - "CometChatReactionsRootProps": "Root provider props", - "CometChatReactionsBarProps": "Reaction chips bar props", - "CometChatReactionsChipProps": "Single reaction chip props", - "CometChatReactionsInfoProps": "Hover tooltip props", - "CometChatReactionsOverflowProps": "Overflow button props" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatReactions` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatReactions } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-reactions` | +| Primary output | `onReactionClick: (emoji: string, message: CometChat.BaseMessage) => void` — emits the clicked reaction | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; wire `onReactionClick` / `onReactorClick` to handle taps | +| Full props | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/search.mdx b/ui-kit/react/components/search.mdx index 01ce63176..b960c5d7e 100644 --- a/ui-kit/react/components/search.mdx +++ b/ui-kit/react/components/search.mdx @@ -4,133 +4,18 @@ description: "Unified search across conversations and messages with filter chips --- -```json -{ - "component": "CometChatSearch", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatSearch } from \"@cometchat/chat-uikit-react\";", - "description": "Unified search across conversations and messages with filter chips, scoped search, and customizable result views.", - "cssRootClass": ".cometchat-search", - "primaryOutput": { - "prop": "onConversationClicked", - "type": "(event: CometChatSearchConversationClickEvent) => void" - }, - "props": { - "data": { - "searchIn": { - "type": "CometChatSearchScope[]", - "default": "[] (both conversations and messages)", - "note": "Empty array shows both sections" - }, - "searchFilters": { - "type": "CometChatSearchFilter[]", - "default": "all available filters" - }, - "initialSearchFilter": { - "type": "CometChatSearchFilter", - "default": "undefined" - }, - "defaultSearchText": { - "type": "string", - "default": "undefined" - }, - "uid": { - "type": "string", - "default": "undefined", - "note": "Scope search to a specific user's conversation" - }, - "guid": { - "type": "string", - "default": "undefined", - "note": "Scope search to a specific group's conversation" - }, - "lastMessageDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "DD/MM/YYYY for all date ranges in search context" - }, - "messageSentAtDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "undefined" - }, - "conversationsRequestBuilder": { - "type": "CometChat.ConversationsRequestBuilder", - "default": "SDK default", - "note": "Pass the builder instance, not the result of .build()" - }, - "messagesRequestBuilder": { - "type": "CometChat.MessagesRequestBuilder", - "default": "SDK default", - "note": "Pass the builder instance, not the result of .build()" - }, - "textFormatters": { - "type": "CometChatTextFormatter[]", - "default": "undefined" - } - }, - "callbacks": { - "onBack": "() => void", - "onConversationClicked": "(event: CometChatSearchConversationClickEvent) => void", - "onMessageClicked": "(event: CometChatSearchMessageClickEvent) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideBackButton": { "type": "boolean", "default": false }, - "hideUserStatus": { "type": "boolean", "default": false }, - "hideGroupType": { "type": "boolean", "default": false }, - "hideReceipts": { "type": "boolean", "default": false } - }, - "viewSlots": { - "initialView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "conversationItemView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationLeadingView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationTitleView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationSubtitleView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationTrailingView": "(conversation: CometChat.Conversation) => ReactNode", - "messageItemView": "(message: CometChat.BaseMessage) => ReactNode", - "messageLeadingView": "(message: CometChat.BaseMessage) => ReactNode", - "messageTitleView": "(message: CometChat.BaseMessage) => ReactNode", - "messageSubtitleView": "(message: CometChat.BaseMessage) => ReactNode", - "messageTrailingView": "(message: CometChat.BaseMessage) => ReactNode", - "conversationOptions": "(conversation: CometChat.Conversation) => CometChatSearchConversationOption[]" - } - }, - "events": [], - "sdkListeners": [], - "types": { - "CometChatSearchScope": "'conversations' | 'messages'", - "CometChatSearchFilter": "'messages' | 'conversations' | 'unread' | 'groups' | 'photos' | 'videos' | 'links' | 'files' | 'audio'", - "CometChatSearchConversationClickEvent": { - "conversation": "CometChat.Conversation", - "searchKeyword": "string" - }, - "CometChatSearchMessageClickEvent": { - "message": "CometChat.BaseMessage", - "searchKeyword": "string" - }, - "CometChatSearchConversationOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(conversation: CometChat.Conversation) => void" - }, - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatSearch` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatSearch } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-search` | +| **Primary output** | `onConversationClicked: (event: CometChatSearchConversationClickEvent) => void` — emits the clicked search result | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| **Stitching** | Wire `onConversationClicked` / `onMessageClicked` to open the selected result — see the [Search Messages guide](/ui-kit/react/guide-search-messages) | +| **Full props** | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/sticker-bubble.mdx b/ui-kit/react/components/sticker-bubble.mdx index 40bd21c47..23836999c 100644 --- a/ui-kit/react/components/sticker-bubble.mdx +++ b/ui-kit/react/components/sticker-bubble.mdx @@ -5,23 +5,18 @@ description: "A self-extracting bubble that renders a sticker image from a stick --- -```json -{ - "component": "CometChatStickerBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatStickerBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting sticker bubble. Extracts the sticker image URL and name from the message metadata.", - "cssRootClass": ".cometchat-sticker-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.CustomMessage", "required": true, "note": "The sticker custom message; drives extraction of the image URL and name." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatStickerBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatStickerBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-sticker-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Stickers extension](/fundamentals/stickers) enabled in the Dashboard | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/text-bubble.mdx b/ui-kit/react/components/text-bubble.mdx index 2e6b421cb..92f61052a 100644 --- a/ui-kit/react/components/text-bubble.mdx +++ b/ui-kit/react/components/text-bubble.mdx @@ -5,26 +5,18 @@ description: "A self-extracting bubble that renders text messages with markdown, --- -```json -{ - "component": "CometChatTextBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatTextBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting text bubble. Renders message text through the formatter pipeline (markdown, mentions, URLs), with optional read-more truncation.", - "cssRootClass": ".cometchat-text-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "When set (and text omitted), the bubble extracts content via message.getText() and configures mention formatting." }, - "text": { "type": "string", "note": "Explicit text override (used for media captions). At least one of text / message should be set." }, - "isSentByMe": { "type": "boolean", "default": true }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "disableTruncation": { "type": "boolean", "default": false }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatTextBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatTextBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-text-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/thread-header.mdx b/ui-kit/react/components/thread-header.mdx index c217723ca..e36c22af3 100644 --- a/ui-kit/react/components/thread-header.mdx +++ b/ui-kit/react/components/thread-header.mdx @@ -4,95 +4,20 @@ description: "Displays the parent message bubble and reply count for threaded co --- -```json -{ - "component": "CometChatThreadHeader", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatThreadHeader } from \"@cometchat/chat-uikit-react\";", - "description": "Displays the parent message bubble and reply count for threaded conversations.", - "cssRootClass": ".cometchat-thread-header", - "primaryOutput": { - "prop": "onClose", - "type": "() => void" - }, - "props": { - "data": { - "parentMessage": { - "type": "CometChat.BaseMessage", - "required": true, - "note": "The parent message of the thread" - }, - "separatorDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "undefined" - }, - "messageSentAtDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "undefined" - } - }, - "visibility": { - "hideReceipts": { "type": "boolean", "default": false }, - "hideDate": { "type": "boolean", "default": false }, - "hideReplyCount": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "callbacks": { - "onClose": "() => void", - "onSubtitleClicked": "() => void", - "onParentDeleted": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "viewSlots": { - "headerView": "ReactNode", - "messageBubbleView": "ReactNode", - "subtitleView": "ReactNode" - } - }, - "events": { - "emitted": [], - "received": [ - { - "name": "ui:message/sent", - "payload": "{ message, status: 'success' }", - "description": "Increments reply count when current user sends a reply" - }, - { - "name": "ui:compose/edit", - "payload": "{ message, status: 'success' }", - "description": "Updates parent bubble when edited" - }, - { - "name": "ui:message/deleted", - "payload": "{ message }", - "description": "Triggers onParentDeleted" - } - ] - }, - "sdkListeners": [ - "onTextMessageReceived", - "onMediaMessageReceived", - "onCustomMessageReceived", - "onInteractiveMessageReceived", - "onMessageEdited", - "onMessageDeleted" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatThreadHeader` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-thread-header` | +| **Primary output** | `onClose` (`() => void`) — closes the thread view | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| **Stitching** | Pass the parent `message`; wire `onClose` to dismiss the thread view | +| **Events received** | `ui:message/sent`, `ui:compose/edit`, `ui:message/deleted` — see [Event System](/ui-kit/react/event-system) | +| **SDK listeners (automatic)** | Message updates in the thread — new replies, edits, and deletes to the parent message | +| **Full props** | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/users.mdx b/ui-kit/react/components/users.mdx index 033265954..b5410ff44 100644 --- a/ui-kit/react/components/users.mdx +++ b/ui-kit/react/components/users.mdx @@ -4,102 +4,20 @@ description: "Searchable, scrollable list of users with selection support and re --- -```json -{ - "component": "CometChatUsers", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatUsers } from \"@cometchat/chat-uikit-react\";", - "description": "Searchable, scrollable list of users with selection support and real-time presence updates.", - "cssRootClass": ".cometchat-users", - "primaryOutput": { - "prop": "onItemClick", - "type": "(user: CometChat.User) => void" - }, - "props": { - "data": { - "usersRequestBuilder": { - "type": "CometChat.UsersRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.UsersRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - }, - "activeUser": { - "type": "CometChat.User", - "default": "undefined" - }, - "sectionHeaderKey": { - "type": "keyof CometChat.User", - "default": "undefined" - } - }, - "callbacks": { - "onItemClick": "(user: CometChat.User) => void", - "onSelect": "(user: CometChat.User, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void" - }, - "visibility": { - "hideUserStatus": { "type": "boolean", "default": false }, - "hideSearch": { "type": "boolean", "default": false }, - "showSectionHeader": { "type": "boolean", "default": true }, - "showSelectedUsersPreview": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "selection": { - "selectionMode": { - "type": "CometChatUsersSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(user: CometChat.User) => ReactNode", - "leadingView": "(user: CometChat.User) => ReactNode", - "titleView": "(user: CometChat.User) => ReactNode", - "subtitleView": "(user: CometChat.User) => ReactNode", - "trailingView": "(user: CometChat.User) => ReactNode", - "headerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(user: CometChat.User) => CometChatUserOption[]" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:user/blocked", - "payload": "{ user: CometChat.User }", - "description": "Updates user in the list (shows blocked state)" - }, - { - "name": "ui:user/unblocked", - "payload": "{ user: CometChat.User }", - "description": "Updates user in the list (removes blocked state)" - } - ], - "sdkListeners": [ - "onUserOnline", - "onUserOffline" - ], - "types": { - "CometChatUserOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(user: CometChat.User) => void" - }, - "CometChatUsersSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatUsers` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatUsers } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-users` | +| Primary output | `onItemClick: (user: CometChat.User) => void` — emits the selected user to open | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Emits the selected user; wire `onItemClick` to open a chat (mount MessageHeader/List/Composer) — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) | +| Events received | `ui:user/blocked`, `ui:user/unblocked` — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | User presence (online/offline) | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/video-bubble.mdx b/ui-kit/react/components/video-bubble.mdx index a582e7ef6..2b2961e08 100644 --- a/ui-kit/react/components/video-bubble.mdx +++ b/ui-kit/react/components/video-bubble.mdx @@ -5,26 +5,18 @@ description: "A batch-aware bubble that renders one or more video attachments wi --- -```json -{ - "component": "CometChatVideosBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatVideosBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware video bubble. Extracts video attachments and caption from a MediaMessage; renders adaptive grid layouts with poster thumbnails and opens a fullscreen viewer.", - "cssRootClass": ".cometchat-videos-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "onVideoClicked": { "type": "(attachment, index) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatVideosBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatVideosBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-videos-bubble` | +| Primary output | `onVideoClicked: (attachment: CometChatVideosBubbleAttachment, index: number) => void` — opens the fullscreen viewer | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/voice-note-bubble.mdx b/ui-kit/react/components/voice-note-bubble.mdx index 605a34e91..206866e44 100644 --- a/ui-kit/react/components/voice-note-bubble.mdx +++ b/ui-kit/react/components/voice-note-bubble.mdx @@ -5,24 +5,18 @@ description: "A dedicated bubble for recorded voice notes with waveform playback --- -```json -{ - "component": "CometChatVoiceNoteBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatVoiceNoteBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Voice note bubble. Renders for audio messages explicitly tagged audioType='voice_note'. Renders the CometChatAudioBubble waveform player internally. Always standalone (no grid).", - "cssRootClass": ".cometchat-audio-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Must have metadata audioType='voice_note'." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatVoiceNoteBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatVoiceNoteBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-audio-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview From 00aecd6d12018bf7ba6efeacee9c9ebe001edc33 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 3 Aug 2026 15:55:23 +0530 Subject: [PATCH 04/63] added react v7 llm.txt --- ui-kit/react/components/incoming-call.mdx | 20 ++-- ui-kit/react/components/message-bubble.mdx | 16 +-- ui-kit/react/components/search.mdx | 16 +-- ui-kit/react/components/thread-header.mdx | 20 ++-- ui-kit/react/llms-react-v7.mdx | 126 +++++++++++++++++++++ 5 files changed, 162 insertions(+), 36 deletions(-) create mode 100644 ui-kit/react/llms-react-v7.mdx diff --git a/ui-kit/react/components/incoming-call.mdx b/ui-kit/react/components/incoming-call.mdx index b503247fc..af4260f57 100644 --- a/ui-kit/react/components/incoming-call.mdx +++ b/ui-kit/react/components/incoming-call.mdx @@ -7,16 +7,16 @@ description: "Displays an incoming call notification with caller info, accept/de | Field | Value | | --- | --- | -| **Component** | `CometChatIncomingCall` | -| **Package** | `@cometchat/chat-uikit-react` | -| **Import** | `import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";` | -| **CSS root class** | `.cometchat-incoming-call` | -| **Primary output** | `onAccept: (call: CometChat.Call) => void` — fires when the call is accepted | -| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | -| **Stitching** | Mount at the app root to catch incoming calls; wire `onAccept` / `onDecline` | -| **Events emitted** | `ui:call/rejected`, `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | -| **SDK listeners (automatic)** | Incoming and outgoing call lifecycle — handled internally | -| **Full props** | See [Props](#props) | +| Component | `CometChatIncomingCall` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-incoming-call` | +| Primary output | `onAccept: (call: CometChat.Call) => void` — fires when the call is accepted | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Mount at the app root to catch incoming calls; wire `onAccept` / `onDecline` | +| Events emitted | `ui:call/rejected`, `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Incoming and outgoing call lifecycle — handled internally | +| Full props | See [Props](#props) | diff --git a/ui-kit/react/components/message-bubble.mdx b/ui-kit/react/components/message-bubble.mdx index 5cbc22f43..ca0346a44 100644 --- a/ui-kit/react/components/message-bubble.mdx +++ b/ui-kit/react/components/message-bubble.mdx @@ -7,14 +7,14 @@ description: "A shared wrapper component that renders all message types with com | Field | Value | | --- | --- | -| **Component** | `CometChatMessageBubble` | -| **Package** | `@cometchat/chat-uikit-react` | -| **Import** | `import { CometChatMessageBubble } from "@cometchat/chat-uikit-react";` | -| **CSS root class** | `.cometchat-message-bubble` | -| **Primary output** | None — renders from the SDK message (it renders provided content; there is no single primary callback). | -| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user. | -| **Stitching** | Feed `message`, `alignment`, and a plugin-rendered `contentView`; it supplies the surrounding chrome. | -| **Full props** | See [Props](#props) | +| Component | `CometChatMessageBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-bubble` | +| Primary output | None — renders from the SDK message (it renders provided content; there is no single primary callback). | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user. | +| Stitching | Feed `message`, `alignment`, and a plugin-rendered `contentView`; it supplies the surrounding chrome. | +| Full props | See [Props](#props) | diff --git a/ui-kit/react/components/search.mdx b/ui-kit/react/components/search.mdx index b960c5d7e..a6785ac28 100644 --- a/ui-kit/react/components/search.mdx +++ b/ui-kit/react/components/search.mdx @@ -7,14 +7,14 @@ description: "Unified search across conversations and messages with filter chips | Field | Value | | --- | --- | -| **Component** | `CometChatSearch` | -| **Package** | `@cometchat/chat-uikit-react` | -| **Import** | `import { CometChatSearch } from "@cometchat/chat-uikit-react";` | -| **CSS root class** | `.cometchat-search` | -| **Primary output** | `onConversationClicked: (event: CometChatSearchConversationClickEvent) => void` — emits the clicked search result | -| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | -| **Stitching** | Wire `onConversationClicked` / `onMessageClicked` to open the selected result — see the [Search Messages guide](/ui-kit/react/guide-search-messages) | -| **Full props** | See [Props](#props) | +| Component | `CometChatSearch` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatSearch } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-search` | +| Primary output | `onConversationClicked: (event: CometChatSearchConversationClickEvent) => void` — emits the clicked search result | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Wire `onConversationClicked` / `onMessageClicked` to open the selected result — see the [Search Messages guide](/ui-kit/react/guide-search-messages) | +| Full props | See [Props](#props) | diff --git a/ui-kit/react/components/thread-header.mdx b/ui-kit/react/components/thread-header.mdx index e36c22af3..d8d867ab1 100644 --- a/ui-kit/react/components/thread-header.mdx +++ b/ui-kit/react/components/thread-header.mdx @@ -7,16 +7,16 @@ description: "Displays the parent message bubble and reply count for threaded co | Field | Value | | --- | --- | -| **Component** | `CometChatThreadHeader` | -| **Package** | `@cometchat/chat-uikit-react` | -| **Import** | `import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";` | -| **CSS root class** | `.cometchat-thread-header` | -| **Primary output** | `onClose` (`() => void`) — closes the thread view | -| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | -| **Stitching** | Pass the parent `message`; wire `onClose` to dismiss the thread view | -| **Events received** | `ui:message/sent`, `ui:compose/edit`, `ui:message/deleted` — see [Event System](/ui-kit/react/event-system) | -| **SDK listeners (automatic)** | Message updates in the thread — new replies, edits, and deletes to the parent message | -| **Full props** | See [Props](#props) | +| Component | `CometChatThreadHeader` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-thread-header` | +| Primary output | `onClose` (`() => void`) — closes the thread view | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the parent `message`; wire `onClose` to dismiss the thread view | +| Events received | `ui:message/sent`, `ui:compose/edit`, `ui:message/deleted` — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Message updates in the thread — new replies, edits, and deletes to the parent message | +| Full props | See [Props](#props) | diff --git a/ui-kit/react/llms-react-v7.mdx b/ui-kit/react/llms-react-v7.mdx new file mode 100644 index 000000000..009244fc3 --- /dev/null +++ b/ui-kit/react/llms-react-v7.mdx @@ -0,0 +1,126 @@ +--- +title: "React UI Kit v7 — LLM docs index" +description: "Machine-readable, React-v7-scoped index of every UI Kit page as a clean .md twin. Built for AI coding agents; kept out of the human sidebar." +--- + +{/* + SCOPED LLM INDEX for the React v7 UI Kit. + - UNLISTED, NOT hidden: intentionally omitted from docs.json navigation so it never shows in + the human sidebar — but it IS built, served as a clean .md twin, and INDEXED for search + + AI assistants (so AI tools, and this pack's skill via its docs-map, can discover and read it). + - We deliberately do NOT use `hidden: true`/`noindex` here: in Mintlify `hidden` auto-applies + noindex, which would drop this page from search AND the auto global llms.txt / AI context. + We want it discoverable, so it stays indexable. + - Fetch this file's own .md twin as a lightweight, React-only routing index instead of the + site-wide /docs/llms.txt (which spans every product and is far larger). +*/} + +# React UI Kit v7 — LLM docs index (Latest) + +> Stateful, drop-in React chat/calling UI. Package `@cometchat/chat-uikit-react@7` + +> `@cometchat/chat-sdk-javascript@4`. This page is a **React-v7-only** routing index for AI +> agents — a scoped alternative to the site-wide `/docs/llms.txt`. + +## How to use this index +Each link below is already a **`.md` twin** (clean Markdown: verbatim code + an +"AI Integration Quick Reference" block with prop names, types, and defaults). Pick the page for +the intent, fetch its `.md`, read the props there. +- Convention: any docs page URL + `.md` → raw Markdown. +- Fallback: if a `.md` twin 404s, fetch the same URL **without** `.md` (HTML). Never read a + package `.d.ts` and never answer props from memory. + +## Hot path — usually no fetch needed +For a plain "add chat" the install, `init → login → render`, provider, and the core drop-in props +are stable; a well-built agent skill bakes them. Fetch below only for exhaustive props, long-tail +components, theming tokens, or feature enablement. +- Setup: [React.js Integration](https://www.cometchat.com/docs/ui-kit/react/integration-react.md) +- Provider/lifecycle: [CometChatProvider](https://www.cometchat.com/docs/ui-kit/react/cometchat-provider.md) +- Core drop-ins: [Conversations](https://www.cometchat.com/docs/ui-kit/react/components/conversations.md) · [Message Header](https://www.cometchat.com/docs/ui-kit/react/components/message-header.md) · [Message List](https://www.cometchat.com/docs/ui-kit/react/components/message-list.md) · [Message Composer](https://www.cometchat.com/docs/ui-kit/react/components/message-composer.md) + +## Getting started / integration +- [React.js Integration](https://www.cometchat.com/docs/ui-kit/react/integration-react.md) +- [Next.js Integration](https://www.cometchat.com/docs/ui-kit/react/integration-nextjs.md) +- [React Router Integration](https://www.cometchat.com/docs/ui-kit/react/integration-react-router.md) +- [Astro Integration](https://www.cometchat.com/docs/ui-kit/react/integration-astro.md) +- [React UI Kit — Overview](https://www.cometchat.com/docs/ui-kit/react/overview.md) +- [Components Overview](https://www.cometchat.com/docs/ui-kit/react/components-overview.md) + +## Core & configuration +- [CometChatProvider](https://www.cometchat.com/docs/ui-kit/react/cometchat-provider.md) +- [Core Features](https://www.cometchat.com/docs/ui-kit/react/core-features.md) +- [Methods](https://www.cometchat.com/docs/ui-kit/react/methods.md) +- [Event System](https://www.cometchat.com/docs/ui-kit/react/event-system.md) +- [Sound Manager](https://www.cometchat.com/docs/ui-kit/react/sound-manager.md) +- [Localization](https://www.cometchat.com/docs/ui-kit/react/localization.md) +- [Extensions](https://www.cometchat.com/docs/ui-kit/react/extensions.md) +- [Troubleshooting](https://www.cometchat.com/docs/ui-kit/react/troubleshooting.md) + +## Theming +- [Theming (`--cometchat-*` tokens, light/dark)](https://www.cometchat.com/docs/ui-kit/react/theming.md) + +## Components — conversations & lists +- [Conversations](https://www.cometchat.com/docs/ui-kit/react/components/conversations.md) +- [Users](https://www.cometchat.com/docs/ui-kit/react/components/users.md) +- [Groups](https://www.cometchat.com/docs/ui-kit/react/components/groups.md) +- [Group Members](https://www.cometchat.com/docs/ui-kit/react/components/group-members.md) + +## Components — messages +- [Message Header](https://www.cometchat.com/docs/ui-kit/react/components/message-header.md) +- [Message List](https://www.cometchat.com/docs/ui-kit/react/components/message-list.md) +- [Message Composer](https://www.cometchat.com/docs/ui-kit/react/components/message-composer.md) +- [Message Bubble](https://www.cometchat.com/docs/ui-kit/react/components/message-bubble.md) +- [Thread Header](https://www.cometchat.com/docs/ui-kit/react/components/thread-header.md) +- [Message Information](https://www.cometchat.com/docs/ui-kit/react/components/message-information.md) +- [Reactions](https://www.cometchat.com/docs/ui-kit/react/components/reactions.md) +- [Reaction List](https://www.cometchat.com/docs/ui-kit/react/components/reaction-list.md) +- [Flag Message Dialog](https://www.cometchat.com/docs/ui-kit/react/components/flag-message-dialog.md) + +## Components — message bubbles +- [Text Bubble](https://www.cometchat.com/docs/ui-kit/react/components/text-bubble.md) +- [Image Bubble](https://www.cometchat.com/docs/ui-kit/react/components/image-bubble.md) +- [Video Bubble](https://www.cometchat.com/docs/ui-kit/react/components/video-bubble.md) +- [Audio Bubble](https://www.cometchat.com/docs/ui-kit/react/components/audio-bubble.md) +- [Voice Note Bubble](https://www.cometchat.com/docs/ui-kit/react/components/voice-note-bubble.md) +- [File Bubble](https://www.cometchat.com/docs/ui-kit/react/components/file-bubble.md) +- [Poll Bubble](https://www.cometchat.com/docs/ui-kit/react/components/poll-bubble.md) +- [Sticker Bubble](https://www.cometchat.com/docs/ui-kit/react/components/sticker-bubble.md) +- [Card Bubble](https://www.cometchat.com/docs/ui-kit/react/components/card-bubble.md) +- [Collaborative Document Bubble](https://www.cometchat.com/docs/ui-kit/react/components/collaborative-document-bubble.md) +- [Collaborative Whiteboard Bubble](https://www.cometchat.com/docs/ui-kit/react/components/collaborative-whiteboard-bubble.md) +- [Call Bubble](https://www.cometchat.com/docs/ui-kit/react/components/call-bubble.md) +- [Call Action Bubble](https://www.cometchat.com/docs/ui-kit/react/components/call-action-bubble.md) +- [Group Action Bubble](https://www.cometchat.com/docs/ui-kit/react/components/group-action-bubble.md) +- [Delete Bubble](https://www.cometchat.com/docs/ui-kit/react/components/delete-bubble.md) + +## Components — calling +- [Call Buttons](https://www.cometchat.com/docs/ui-kit/react/components/call-buttons.md) +- [Incoming Call](https://www.cometchat.com/docs/ui-kit/react/components/incoming-call.md) +- [Outgoing Call](https://www.cometchat.com/docs/ui-kit/react/components/outgoing-call.md) +- [Call Logs](https://www.cometchat.com/docs/ui-kit/react/components/call-logs.md) +- [Calling Integration](https://www.cometchat.com/docs/ui-kit/react/calling-integration.md) +- [Call Features](https://www.cometchat.com/docs/ui-kit/react/call-features.md) + +## Components — search, AI & notifications +- [Search](https://www.cometchat.com/docs/ui-kit/react/components/search.md) +- [AI Assistant Chat](https://www.cometchat.com/docs/ui-kit/react/components/ai-assistant-chat.md) +- [Smart / AI Features](https://www.cometchat.com/docs/ui-kit/react/ai-features.md) +- [Notification Feed](https://www.cometchat.com/docs/ui-kit/react/components/notification-feed.md) + +## Task guides (recipes) +- [New Chat Creation](https://www.cometchat.com/docs/ui-kit/react/guide-new-chat-creation.md) +- [Group Chat Setup](https://www.cometchat.com/docs/ui-kit/react/guide-group-chat-setup.md) +- [Search Messages](https://www.cometchat.com/docs/ui-kit/react/guide-search-messages.md) +- [Threaded Messages](https://www.cometchat.com/docs/ui-kit/react/guide-threaded-messages.md) +- [Message Privately](https://www.cometchat.com/docs/ui-kit/react/guide-message-privately.md) +- [Block / Unblock User](https://www.cometchat.com/docs/ui-kit/react/guide-block-unblock-user.md) + +## Framework recipes (full-page layouts) +- React: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/react-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/react-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/react-tab-based-chat.md) +- Next.js: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/next-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/next-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/next-tab-based-chat.md) +- React Router: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/react-router-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/react-router-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/react-router-tab-based-chat.md) +- Astro: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/astro-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/astro-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/astro-tab-based-chat.md) + +## Migration & misc +- [Upgrading from v6 to v7](https://www.cometchat.com/docs/ui-kit/react/migration-overview.md) +- [v6 → v7 Property Changes](https://www.cometchat.com/docs/ui-kit/react/migration-property-changes.md) +- [Campaigns](https://www.cometchat.com/docs/ui-kit/react/campaigns.md) From 59422dc7c7926d129e0492450e5fac42a7bdbdad Mon Sep 17 00:00:00 2001 From: rajdubey Date: Fri, 7 Aug 2026 20:32:31 +0530 Subject: [PATCH 05/63] updated docs info --- ui-kit/react/llms-react-v7.mdx | 138 ++++++++++++++++----------------- 1 file changed, 69 insertions(+), 69 deletions(-) diff --git a/ui-kit/react/llms-react-v7.mdx b/ui-kit/react/llms-react-v7.mdx index 009244fc3..6b69549e0 100644 --- a/ui-kit/react/llms-react-v7.mdx +++ b/ui-kit/react/llms-react-v7.mdx @@ -33,94 +33,94 @@ the intent, fetch its `.md`, read the props there. For a plain "add chat" the install, `init → login → render`, provider, and the core drop-in props are stable; a well-built agent skill bakes them. Fetch below only for exhaustive props, long-tail components, theming tokens, or feature enablement. -- Setup: [React.js Integration](https://www.cometchat.com/docs/ui-kit/react/integration-react.md) -- Provider/lifecycle: [CometChatProvider](https://www.cometchat.com/docs/ui-kit/react/cometchat-provider.md) -- Core drop-ins: [Conversations](https://www.cometchat.com/docs/ui-kit/react/components/conversations.md) · [Message Header](https://www.cometchat.com/docs/ui-kit/react/components/message-header.md) · [Message List](https://www.cometchat.com/docs/ui-kit/react/components/message-list.md) · [Message Composer](https://www.cometchat.com/docs/ui-kit/react/components/message-composer.md) +- Setup: [React.js Integration](integration-react.md) +- Provider/lifecycle: [CometChatProvider](cometchat-provider.md) +- Core drop-ins: [Conversations](components/conversations.md) · [Message Header](components/message-header.md) · [Message List](components/message-list.md) · [Message Composer](components/message-composer.md) ## Getting started / integration -- [React.js Integration](https://www.cometchat.com/docs/ui-kit/react/integration-react.md) -- [Next.js Integration](https://www.cometchat.com/docs/ui-kit/react/integration-nextjs.md) -- [React Router Integration](https://www.cometchat.com/docs/ui-kit/react/integration-react-router.md) -- [Astro Integration](https://www.cometchat.com/docs/ui-kit/react/integration-astro.md) -- [React UI Kit — Overview](https://www.cometchat.com/docs/ui-kit/react/overview.md) -- [Components Overview](https://www.cometchat.com/docs/ui-kit/react/components-overview.md) +- [React.js Integration](integration-react.md) +- [Next.js Integration](integration-nextjs.md) +- [React Router Integration](integration-react-router.md) +- [Astro Integration](integration-astro.md) +- [React UI Kit — Overview](overview.md) +- [Components Overview](components-overview.md) ## Core & configuration -- [CometChatProvider](https://www.cometchat.com/docs/ui-kit/react/cometchat-provider.md) -- [Core Features](https://www.cometchat.com/docs/ui-kit/react/core-features.md) -- [Methods](https://www.cometchat.com/docs/ui-kit/react/methods.md) -- [Event System](https://www.cometchat.com/docs/ui-kit/react/event-system.md) -- [Sound Manager](https://www.cometchat.com/docs/ui-kit/react/sound-manager.md) -- [Localization](https://www.cometchat.com/docs/ui-kit/react/localization.md) -- [Extensions](https://www.cometchat.com/docs/ui-kit/react/extensions.md) -- [Troubleshooting](https://www.cometchat.com/docs/ui-kit/react/troubleshooting.md) +- [CometChatProvider](cometchat-provider.md) +- [Core Features](core-features.md) +- [Methods](methods.md) +- [Event System](event-system.md) +- [Sound Manager](sound-manager.md) +- [Localization](localization.md) +- [Extensions](extensions.md) +- [Troubleshooting](troubleshooting.md) ## Theming -- [Theming (`--cometchat-*` tokens, light/dark)](https://www.cometchat.com/docs/ui-kit/react/theming.md) +- [Theming (`--cometchat-*` tokens, light/dark)](theming.md) ## Components — conversations & lists -- [Conversations](https://www.cometchat.com/docs/ui-kit/react/components/conversations.md) -- [Users](https://www.cometchat.com/docs/ui-kit/react/components/users.md) -- [Groups](https://www.cometchat.com/docs/ui-kit/react/components/groups.md) -- [Group Members](https://www.cometchat.com/docs/ui-kit/react/components/group-members.md) +- [Conversations](components/conversations.md) +- [Users](components/users.md) +- [Groups](components/groups.md) +- [Group Members](components/group-members.md) ## Components — messages -- [Message Header](https://www.cometchat.com/docs/ui-kit/react/components/message-header.md) -- [Message List](https://www.cometchat.com/docs/ui-kit/react/components/message-list.md) -- [Message Composer](https://www.cometchat.com/docs/ui-kit/react/components/message-composer.md) -- [Message Bubble](https://www.cometchat.com/docs/ui-kit/react/components/message-bubble.md) -- [Thread Header](https://www.cometchat.com/docs/ui-kit/react/components/thread-header.md) -- [Message Information](https://www.cometchat.com/docs/ui-kit/react/components/message-information.md) -- [Reactions](https://www.cometchat.com/docs/ui-kit/react/components/reactions.md) -- [Reaction List](https://www.cometchat.com/docs/ui-kit/react/components/reaction-list.md) -- [Flag Message Dialog](https://www.cometchat.com/docs/ui-kit/react/components/flag-message-dialog.md) +- [Message Header](components/message-header.md) +- [Message List](components/message-list.md) +- [Message Composer](components/message-composer.md) +- [Message Bubble](components/message-bubble.md) +- [Thread Header](components/thread-header.md) +- [Message Information](components/message-information.md) +- [Reactions](components/reactions.md) +- [Reaction List](components/reaction-list.md) +- [Flag Message Dialog](components/flag-message-dialog.md) ## Components — message bubbles -- [Text Bubble](https://www.cometchat.com/docs/ui-kit/react/components/text-bubble.md) -- [Image Bubble](https://www.cometchat.com/docs/ui-kit/react/components/image-bubble.md) -- [Video Bubble](https://www.cometchat.com/docs/ui-kit/react/components/video-bubble.md) -- [Audio Bubble](https://www.cometchat.com/docs/ui-kit/react/components/audio-bubble.md) -- [Voice Note Bubble](https://www.cometchat.com/docs/ui-kit/react/components/voice-note-bubble.md) -- [File Bubble](https://www.cometchat.com/docs/ui-kit/react/components/file-bubble.md) -- [Poll Bubble](https://www.cometchat.com/docs/ui-kit/react/components/poll-bubble.md) -- [Sticker Bubble](https://www.cometchat.com/docs/ui-kit/react/components/sticker-bubble.md) -- [Card Bubble](https://www.cometchat.com/docs/ui-kit/react/components/card-bubble.md) -- [Collaborative Document Bubble](https://www.cometchat.com/docs/ui-kit/react/components/collaborative-document-bubble.md) -- [Collaborative Whiteboard Bubble](https://www.cometchat.com/docs/ui-kit/react/components/collaborative-whiteboard-bubble.md) -- [Call Bubble](https://www.cometchat.com/docs/ui-kit/react/components/call-bubble.md) -- [Call Action Bubble](https://www.cometchat.com/docs/ui-kit/react/components/call-action-bubble.md) -- [Group Action Bubble](https://www.cometchat.com/docs/ui-kit/react/components/group-action-bubble.md) -- [Delete Bubble](https://www.cometchat.com/docs/ui-kit/react/components/delete-bubble.md) +- [Text Bubble](components/text-bubble.md) +- [Image Bubble](components/image-bubble.md) +- [Video Bubble](components/video-bubble.md) +- [Audio Bubble](components/audio-bubble.md) +- [Voice Note Bubble](components/voice-note-bubble.md) +- [File Bubble](components/file-bubble.md) +- [Poll Bubble](components/poll-bubble.md) +- [Sticker Bubble](components/sticker-bubble.md) +- [Card Bubble](components/card-bubble.md) +- [Collaborative Document Bubble](components/collaborative-document-bubble.md) +- [Collaborative Whiteboard Bubble](components/collaborative-whiteboard-bubble.md) +- [Call Bubble](components/call-bubble.md) +- [Call Action Bubble](components/call-action-bubble.md) +- [Group Action Bubble](components/group-action-bubble.md) +- [Delete Bubble](components/delete-bubble.md) ## Components — calling -- [Call Buttons](https://www.cometchat.com/docs/ui-kit/react/components/call-buttons.md) -- [Incoming Call](https://www.cometchat.com/docs/ui-kit/react/components/incoming-call.md) -- [Outgoing Call](https://www.cometchat.com/docs/ui-kit/react/components/outgoing-call.md) -- [Call Logs](https://www.cometchat.com/docs/ui-kit/react/components/call-logs.md) -- [Calling Integration](https://www.cometchat.com/docs/ui-kit/react/calling-integration.md) -- [Call Features](https://www.cometchat.com/docs/ui-kit/react/call-features.md) +- [Call Buttons](components/call-buttons.md) +- [Incoming Call](components/incoming-call.md) +- [Outgoing Call](components/outgoing-call.md) +- [Call Logs](components/call-logs.md) +- [Calling Integration](calling-integration.md) +- [Call Features](call-features.md) ## Components — search, AI & notifications -- [Search](https://www.cometchat.com/docs/ui-kit/react/components/search.md) -- [AI Assistant Chat](https://www.cometchat.com/docs/ui-kit/react/components/ai-assistant-chat.md) -- [Smart / AI Features](https://www.cometchat.com/docs/ui-kit/react/ai-features.md) -- [Notification Feed](https://www.cometchat.com/docs/ui-kit/react/components/notification-feed.md) +- [Search](components/search.md) +- [AI Assistant Chat](components/ai-assistant-chat.md) +- [Smart / AI Features](ai-features.md) +- [Notification Feed](components/notification-feed.md) ## Task guides (recipes) -- [New Chat Creation](https://www.cometchat.com/docs/ui-kit/react/guide-new-chat-creation.md) -- [Group Chat Setup](https://www.cometchat.com/docs/ui-kit/react/guide-group-chat-setup.md) -- [Search Messages](https://www.cometchat.com/docs/ui-kit/react/guide-search-messages.md) -- [Threaded Messages](https://www.cometchat.com/docs/ui-kit/react/guide-threaded-messages.md) -- [Message Privately](https://www.cometchat.com/docs/ui-kit/react/guide-message-privately.md) -- [Block / Unblock User](https://www.cometchat.com/docs/ui-kit/react/guide-block-unblock-user.md) +- [New Chat Creation](guide-new-chat-creation.md) +- [Group Chat Setup](guide-group-chat-setup.md) +- [Search Messages](guide-search-messages.md) +- [Threaded Messages](guide-threaded-messages.md) +- [Message Privately](guide-message-privately.md) +- [Block / Unblock User](guide-block-unblock-user.md) ## Framework recipes (full-page layouts) -- React: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/react-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/react-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/react-tab-based-chat.md) -- Next.js: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/next-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/next-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/next-tab-based-chat.md) -- React Router: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/react-router-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/react-router-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/react-router-tab-based-chat.md) -- Astro: [Conversation + Messages](https://www.cometchat.com/docs/ui-kit/react/astro-conversation.md) · [One-to-One / Group](https://www.cometchat.com/docs/ui-kit/react/astro-one-to-one-chat.md) · [Tab-Based](https://www.cometchat.com/docs/ui-kit/react/astro-tab-based-chat.md) +- React: [Conversation + Messages](react-conversation.md) · [One-to-One / Group](react-one-to-one-chat.md) · [Tab-Based](react-tab-based-chat.md) +- Next.js: [Conversation + Messages](next-conversation.md) · [One-to-One / Group](next-one-to-one-chat.md) · [Tab-Based](next-tab-based-chat.md) +- React Router: [Conversation + Messages](react-router-conversation.md) · [One-to-One / Group](react-router-one-to-one-chat.md) · [Tab-Based](react-router-tab-based-chat.md) +- Astro: [Conversation + Messages](astro-conversation.md) · [One-to-One / Group](astro-one-to-one-chat.md) · [Tab-Based](astro-tab-based-chat.md) ## Migration & misc -- [Upgrading from v6 to v7](https://www.cometchat.com/docs/ui-kit/react/migration-overview.md) -- [v6 → v7 Property Changes](https://www.cometchat.com/docs/ui-kit/react/migration-property-changes.md) -- [Campaigns](https://www.cometchat.com/docs/ui-kit/react/campaigns.md) +- [Upgrading from v6 to v7](migration-overview.md) +- [v6 → v7 Property Changes](migration-property-changes.md) +- [Campaigns](campaigns.md) From 75dcd1e47f04c150c9b310110b0531569f219440 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 13 Aug 2026 21:04:07 +0530 Subject: [PATCH 06/63] Docs Correction --- ui-kit/react/components/search.mdx | 3 ++ ui-kit/react/integration-react.mdx | 76 ++++++++++++++++++++++++++++++ ui-kit/react/theming.mdx | 68 +++++++++++++++++++++++++- 3 files changed, 145 insertions(+), 2 deletions(-) diff --git a/ui-kit/react/components/search.mdx b/ui-kit/react/components/search.mdx index a6785ac28..d8674c733 100644 --- a/ui-kit/react/components/search.mdx +++ b/ui-kit/react/components/search.mdx @@ -25,6 +25,9 @@ description: "Unified search across conversations and messages with filter chips **These result callbacks are required to make the component useful.** `CometChatSearch` does not navigate on its own — clicking a result only fires `onConversationClicked` or `onMessageClicked`. Your app must handle navigation: open the [Conversations](/ui-kit/react/components/conversations) list or route to the matched entity, and pass the message's ID to [Message List](/ui-kit/react/components/message-list) via `goToMessageId` to scroll to the exact message. For an end-to-end walkthrough, see the [Search Messages guide](/ui-kit/react/guide-search-messages). + +**Message search is plan-gated.** It requires **Search enabled on your CometChat plan** (check your app's plan in the [Dashboard](https://app.cometchat.com/)). Until it's enabled, the search API responds with **HTTP `402 Payment Required`** and no results appear — even when `CometChatSearch` is wired correctly. + **Live Preview** — interact with the default search component. diff --git a/ui-kit/react/integration-react.mdx b/ui-kit/react/integration-react.mdx index be1b58400..ac75d7735 100644 --- a/ui-kit/react/integration-react.mdx +++ b/ui-kit/react/integration-react.mdx @@ -188,6 +188,82 @@ Open `http://localhost:5173` (Vite) or `http://localhost:3000` (CRA). You should --- +## Layout & Sizing + +The UI Kit components are `height: 100%` / flex-fill — they **fill their parent** rather than sizing to their content. If the host layout doesn't give them room, they collapse to a sliver or overflow. The bare `height: 100vh` in the example above is the minimum; keep these rules in mind: + +- **Give the container a content-independent height _and_ width.** Use `height: 100dvh` (or `100vh`) on the outer wrapper — not `min-height` or `auto`, which collapse to ~0px because the components have no intrinsic height. +- **Constrain flex children so they scroll instead of growing.** Add `min-height: 0` (and `overflow: hidden`) to flex columns that hold a message list; without it, a long list pushes the whole layout taller instead of scrolling internally. +- **Reset any app scaffold that caps `#root`.** A fresh Vite/CRA `#root` is often `max-width`-capped, centered, and padded (from the starter's `index.css`/`App.css`) — which renders the chat gutter-boxed. Clear those: + ```css title="src/index.css" + #root { + max-width: none; + margin: 0; + padding: 0; + width: 100%; + height: 100dvh; + } + ``` +- **Don't put `transform` or `filter` on an ancestor.** Either property creates a new containing block that clips the kit's `position: fixed` overlays — context menus, the emoji keyboard, and the call screen. + +### Responsive layout + +The two-panel example is a fixed side-by-side layout, which squashes on a phone. On narrow viewports, show **one pane at a time** — the conversation list, then the message view with a back button. Drive it off a breakpoint: + +```tsx +import { useEffect, useState } from "react"; + +function useIsMobile(breakpoint = 768) { + const [isMobile, setIsMobile] = useState( + () => window.matchMedia(`(max-width: ${breakpoint}px)`).matches + ); + + useEffect(() => { + const media = window.matchMedia(`(max-width: ${breakpoint}px)`); + const onChange = () => setIsMobile(media.matches); + media.addEventListener("change", onChange); + return () => media.removeEventListener("change", onChange); + }, [breakpoint]); + + return isMobile; +} +``` + +On mobile, render **either** the list **or** the message pane based on `isMobile` and whether a conversation is selected, and use `CometChatMessageHeader`'s built-in back button (it renders by default; wire `onBack` to clear the selection, or set `hideBackButton` to control it) to return to the list: + +```tsx +// Inside App, with `chatUser`/`chatGroup` state from the example above: +const isMobile = useIsMobile(); +const hasSelection = Boolean(chatUser || chatGroup); + +if (isMobile) { + return ( + +
+ {!hasSelection ? ( + + ) : ( +
+ { + setChatUser(undefined); + setChatGroup(undefined); + }} + /> + + +
+ )} +
+ + ); +} +``` + +--- + ## Choose a Chat Experience ### Conversation List + Message View diff --git a/ui-kit/react/theming.mdx b/ui-kit/react/theming.mdx index 2de7a9dbe..7581b2173 100644 --- a/ui-kit/react/theming.mdx +++ b/ui-kit/react/theming.mdx @@ -57,6 +57,50 @@ function ThemeToggle() { --- +## Follow the System (OS) Theme + +The UI Kit ships `light` and `dark` themes but **does not follow the operating system's color-scheme setting on its own** — there is no `theme="system"`. A fresh app stays on the default `light` theme even when the OS is in dark mode. To follow the OS, read `prefers-color-scheme` and drive the theme yourself. + +Seed the initial theme from the OS setting when you mount the provider: + +```tsx title="src/main.tsx" +const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches; + + + +; +``` + +Then keep it in sync at runtime by subscribing to the media query's `change` event from inside the provider (so `useTheme` is available): + +```tsx +import { useEffect } from "react"; +import { useTheme } from "@cometchat/chat-uikit-react"; + +function useFollowSystemTheme() { + const { setTheme } = useTheme(); + + useEffect(() => { + const media = window.matchMedia("(prefers-color-scheme: dark)"); + + // Apply the current OS setting immediately. + setTheme(media.matches ? "dark" : "light"); + + // Update whenever the OS toggles light/dark. + const onChange = (event: MediaQueryListEvent) => + setTheme(event.matches ? "dark" : "light"); + media.addEventListener("change", onChange); + return () => media.removeEventListener("change", onChange); + }, [setTheme]); +} +``` + + +Call `useFollowSystemTheme()` from a component rendered **inside** `CometChatProvider`. If you also expose a manual toggle, stop calling `setTheme` from this hook once the user overrides the theme — otherwise the next OS change will revert their choice. + + +--- + ## Customizing Tokens Override CSS variables to change the look of all components at once: @@ -77,15 +121,19 @@ import "./cometchat-overrides.css"; ### Per-Theme Overrides -Target a specific theme with the `data-theme` selector: +Target a specific theme with the `data-theme` selector. The `data-theme` attribute and the `.cometchat` class sit on the **same** wrapper `
`, so use the **same-element** selector `.cometchat[data-theme="dark"]` — not the descendant form `[data-theme="dark"] .cometchat`, which matches only a `.cometchat` *nested inside* another `[data-theme]` element and therefore misses the root wrapper: ```css -[data-theme="dark"] .cometchat { +.cometchat[data-theme="dark"] { --cometchat-primary-color: #bb86fc; --cometchat-background-color-01: #121212; } ``` + +Component-class overrides *are* descendants of the wrapper, so the descendant form is correct for them — e.g. `[data-theme="dark"] .cometchat-message-list { … }`. It's only overriding tokens on the **root wrapper** that requires the same-element `.cometchat[data-theme="dark"]` selector. + + ### Per-Component Overrides Target a specific component by its BEM class name: @@ -108,6 +156,20 @@ Or wrap the component in your own class: } ``` +### Differentiating the Thread Panel + +Some surfaces paint their **own opaque token** rather than inheriting a background from their wrapper. The clearest example is the thread panel: its `CometChatMessageList` fills itself with `--cometchat-message-list-bg` (default `--cometchat-background-color-03`), while the thread header uses `--cometchat-thread-header-background` (which falls back to `--cometchat-background-color-01`). Because the list background is opaque, setting a `background` on the wrapping `
` has **no visible effect** — the list paints over it, and the panel looks mismatched against its header and composer. + +To style such a surface, override its own token instead of a wrapper background. For example, to make the thread panel's message list match its header: + +```css +/* Scope to the thread wrapper in your app */ +.my-thread-panel { + --cometchat-message-list-bg: var(--cometchat-background-color-01); + --cometchat-thread-header-background: var(--cometchat-background-color-01); +} +``` + --- ## Design Token Categories @@ -133,6 +195,8 @@ Or wrap the component in your own class: | Token | Purpose | | --- | --- | | `--cometchat-background-color-01` to `04` | Background layers (01 = base, 04 = elevated) | +| `--cometchat-message-list-bg` | Opaque background painted by `CometChatMessageList` (default `--cometchat-background-color-03`). Set this — not a wrapper `background` — to recolor the list surface | +| `--cometchat-thread-header-background` | Background of the thread panel header (falls back to `--cometchat-background-color-01`) | | `--cometchat-border-color-light` / `default` / `dark` / `highlight` | Border variants | | `--cometchat-text-color-primary` / `secondary` / `tertiary` / `disabled` / `highlight` | Text colors | | `--cometchat-icon-color-primary` / `secondary` / `tertiary` / `highlight` | Icon colors | From 58dd16ce2d9a0012271c79e43300f41bc1f46cbc Mon Sep 17 00:00:00 2001 From: rajdubey Date: Fri, 14 Aug 2026 12:02:04 +0530 Subject: [PATCH 07/63] Updated guides --- sdk/javascript/leave-group.mdx | 4 + ui-kit/react/components/groups.mdx | 2 +- ui-kit/react/guide-group-chat-setup.mdx | 201 +++++++++++++++++++++--- 3 files changed, 181 insertions(+), 26 deletions(-) diff --git a/sdk/javascript/leave-group.mdx b/sdk/javascript/leave-group.mdx index d3a9c32a1..9ec256558 100644 --- a/sdk/javascript/leave-group.mdx +++ b/sdk/javascript/leave-group.mdx @@ -49,6 +49,10 @@ Once a group is left, the user will no longer receive any updates or messages pe On success, the method resolves with `true` (boolean). + +The group **owner cannot leave** the group directly — `leaveGroup()` rejects for the owner. Transfer ownership to another member with [`transferGroupOwnership()`](/sdk/javascript/transfer-group-ownership) first, then call `leaveGroup()`. + + ## Real-time Group Member Left Events Register a `GroupListener` to receive events when members leave. diff --git a/ui-kit/react/components/groups.mdx b/ui-kit/react/components/groups.mdx index 6a685b2e3..23a3de6bc 100644 --- a/ui-kit/react/components/groups.mdx +++ b/ui-kit/react/components/groups.mdx @@ -604,7 +604,7 @@ Function that returns context menu options for each group item (shown on hover/s ``` -The `onClick` handlers above (`leaveGroup`, `openGroupDetails`) are placeholders — the component only renders the menu items; you must implement the actual behavior. The [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) shows the join, leave, and group-details flows end to end. +The `onClick` handlers above (`leaveGroup`, `openGroupDetails`) are placeholders — the component only renders the menu items; you must implement the actual behavior. The [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) shows the join, member-management, and leave / ownership-transfer flows end to end. Note that wiring **Leave Group** directly to `leaveGroup()` throws for the group **owner** — the owner must [transfer ownership](/sdk/javascript/transfer-group-ownership) first. --- diff --git a/ui-kit/react/guide-group-chat-setup.mdx b/ui-kit/react/guide-group-chat-setup.mdx index ec9bccb05..930153810 100644 --- a/ui-kit/react/guide-group-chat-setup.mdx +++ b/ui-kit/react/guide-group-chat-setup.mdx @@ -1,12 +1,12 @@ --- title: "Group Chat Setup" sidebarTitle: "Group Chat Setup" -description: "Create and join group conversations with a full messaging interface using CometChat UI Kit components." +description: "Create public, password-protected, and private groups; add, remove, and manage members with role-based permissions; join, leave, and transfer ownership using the CometChat UI Kit." --- ## Goal -By the end of this guide you will have a working group chat interface where users can create a new group, add members, and exchange messages in real time using the CometChat compound components. +By the end of this guide you will have a working group chat where users can create a group of any type (public, password-protected, or private), add and remove members with role-based permissions, join or leave a group, transfer ownership, and exchange messages in real time using the CometChat components. ## Prerequisites @@ -19,12 +19,17 @@ By the end of this guide you will have a working group chat interface where user | Component / API | Purpose | |:----------------|:--------| | `CometChatConversations` | Lists existing conversations including groups | +| `CometChatGroupMembers` | Built-in member list with role-gated kick / ban / scope-change actions | | `CometChatMessageHeader` | Displays group name, avatar, and member count | | `CometChatMessageList` | Renders group messages in real time | | `CometChatMessageComposer` | Text input for sending messages to the group | | `CometChat.createGroup()` | SDK method to create a new group | -| `CometChat.joinGroup()` | SDK method to join an existing group | +| `CometChat.joinGroup()` | SDK method to join a public or password-protected group | | `CometChat.addMembersToGroup()` | SDK method to add members | +| `CometChat.kickGroupMember()` / `banGroupMember()` | SDK methods to remove or ban a member | +| `CometChat.updateGroupMemberScope()` | SDK method to change a member's role | +| `CometChat.leaveGroup()` | SDK method to leave a group | +| `CometChat.transferGroupOwnership()` | SDK method to hand ownership to another member | ## Step 1: Set up the app shell @@ -47,16 +52,29 @@ function App() { export default App; ``` -## Step 2: Create a new group +## Step 2: Create a group -Use `CometChat.createGroup()` to programmatically create a group. You need a unique GUID, a name, and a group type (public, private, or password-protected). +A group has one of three types, and the type decides how other users can get in. Choose the right one up front — it changes both the create call and how (or whether) users can join. + +| Type | Constant | How users get in | +| --- | --- | --- | +| **Public** | `CometChat.GROUP_TYPE.PUBLIC` | Anyone can join, no password. | +| **Password-protected** | `CometChat.GROUP_TYPE.PASSWORD` | Users must supply the correct password to join. | +| **Private** | `CometChat.GROUP_TYPE.PRIVATE` | **Add-only.** Users cannot join — not even with a password. An admin or moderator must add them. | + +Create a group with `CometChat.createGroup()`. The `CometChat.Group` constructor takes a **fourth `password` argument** — it is required for password-protected groups and ignored for the other two types. ```tsx -async function createGroup() { +async function createGroup( + name: string, + type: string, + password = "" // only used when type is PASSWORD +) { const group = new CometChat.Group( "group-" + Date.now(), // unique GUID - "My Team Chat", // group name - CometChat.GROUP_TYPE.PUBLIC // public, private, or password + name, + type, // PUBLIC | PASSWORD | PRIVATE + password ); try { @@ -69,13 +87,17 @@ async function createGroup() { } ``` + +For a password-protected group you **must** pass the password as the fourth argument. `new CometChat.Group(guid, name, CometChat.GROUP_TYPE.PASSWORD)` with no password creates a group nobody can join. + + When a group is created through the UI Kit's built-in flow, it publishes the `ui:group/created` event on the [Event System](/ui-kit/react/event-system#user--group-actions). Subscribe with `useCometChatEvents` if other components need to react to new groups being created. -## Step 3: Add members to the group +## Step 3: Add members -After creating a group, add members using `CometChat.addMembersToGroup()`. Each member needs a UID and a scope (admin, moderator, or participant). +The creator becomes the group **owner** (with admin privileges). Add members with `CometChat.addMembersToGroup()` — each member is a `CometChat.GroupMember` with a UID and a scope (`ADMIN`, `MODERATOR`, or `PARTICIPANT`). ```tsx async function addMembers(guid: string, memberUids: string[]) { @@ -93,23 +115,121 @@ async function addMembers(guid: string, memberUids: string[]) { } ``` -## Step 4: Join an existing group + +Adding members requires an **admin** or **moderator** scope in the target group — a **participant** cannot add members. Assign `PARTICIPANT` by default and only grant `ADMIN`/`MODERATOR` when a member needs management rights. For **private** groups this is the *only* way in — there is no join. To let a user pick who to add, render [`CometChatUsers`](/ui-kit/react/components/users) in selection mode and pass the chosen UIDs to `addMembersToGroup()`. + + +## Step 4: Join a group -For public groups, users can join without an invite using `CometChat.joinGroup()`. +How a user joins depends on the group type: ```tsx -async function joinGroup(guid: string) { +async function joinGroup(group: CometChat.Group, password = "") { + const guid = group.getGuid(); + const type = group.getType(); + + // Private groups cannot be joined — the user must be added (Step 3). + if (type === CometChat.GROUP_TYPE.PRIVATE) { + console.warn("Private groups are add-only; joining is not allowed."); + return; + } + try { - const group = await CometChat.joinGroup(guid, CometChat.GROUP_TYPE.PUBLIC); - console.log("Joined group:", group.getName()); - return group; + // Pass the password only for password-protected groups; "" for public. + const joined = await CometChat.joinGroup(guid, type, password); + console.log("Joined group:", joined.getName()); + return joined; } catch (error) { + // A wrong password for a PASSWORD group rejects here. console.error("Failed to join group:", error); } } ``` -## Step 5: Display conversations and select a group + +Only **public** and **password-protected** groups can be joined. A **private** group is add-only — calling `joinGroup()` on it fails; add the user via [Step 3](#step-3-add-members) instead. The built-in [`CometChatGroups`](/ui-kit/react/components/groups) list surfaces a password prompt for password-protected groups automatically. + + +## Step 5: Manage members — remove, ban, and change roles + +The `CometChatGroupMembers` component renders the member list with built-in **kick**, **ban**, and **change-scope** actions. It shows or hides those actions based on the **logged-in user's role**, so you don't have to gate them yourself. + +```tsx +import { CometChatGroupMembers } from "@cometchat/chat-uikit-react"; + +function GroupMembersPanel({ group }: { group: CometChat.Group }) { + return ( + {/* close the panel */}} + /> + ); +} +``` + +Group actions are **scope-based** — a participant can never perform them: + +| Action | Participant | Moderator | Admin / Owner | +| --- | :---: | :---: | :---: | +| Send & receive messages | ✅ | ✅ | ✅ | +| Add members | ❌ | ✅ | ✅ | +| Kick / ban **participants** | ❌ | ✅ | ✅ | +| Kick / ban admins & moderators | ❌ | ❌ | ✅ | +| Change a member's scope | ❌ | participants only | ✅ | +| Update / delete the group | ❌ | update only | ✅ | +| Transfer ownership | ❌ | ❌ | Owner only | + +If you build your own controls instead of using the component's menu, the SDK methods are: + +```tsx +// Remove a member from the group +await CometChat.kickGroupMember(guid, uid); + +// Ban a member (kicked and blocked from rejoining) +await CometChat.banGroupMember(guid, uid); + +// Promote / demote a member +await CometChat.updateGroupMemberScope( + guid, + uid, + CometChat.GROUP_MEMBER_SCOPE.MODERATOR +); +``` + + +Calling these as a participant — or a moderator acting on an admin — rejects with a permission error. Let the acting user's scope drive which controls you render. The component already does this for its default kick/ban/scope menu. + + +## Step 6: Leave a group and transfer ownership + +Any member can leave with `CometChat.leaveGroup()` — **except the owner**. An owner must hand ownership to another member with `CometChat.transferGroupOwnership()` *first*; leaving before transferring rejects with an error. + +```tsx +async function leaveGroup(group: CometChat.Group, loggedInUid: string) { + const guid = group.getGuid(); + const isOwner = group.getOwner() === loggedInUid; + + try { + if (isOwner) { + // Owners cannot leave until ownership is transferred. + const newOwnerUid = await pickAnotherMember(guid); // your UI: choose a member + if (!newOwnerUid) return; // no one to hand off to — block the leave + await CometChat.transferGroupOwnership(guid, newOwnerUid); + } + + await CometChat.leaveGroup(guid); + console.log("Left group:", group.getName()); + } catch (error) { + console.error("Failed to leave group:", error); + } +} +``` + + +Wiring "Leave Group" straight to `leaveGroup()` throws for the owner. Detect the owner (`group.getOwner() === loggedInUser.getUid()`), show an **ownership-transfer** step (a member picker — `CometChatGroupMembers` in selection mode works well), call `transferGroupOwnership()`, and only then `leaveGroup()`. See the SDK [Transfer Group Ownership](/sdk/javascript/transfer-group-ownership) and [Leave Group](/sdk/javascript/leave-group) references. + + +## Step 7: Display conversations and select a group Use `CometChatConversations` to show the user's conversations. When a group conversation is selected, pass the group object to the message components. @@ -139,7 +259,7 @@ function GroupChat() { } ``` -## Step 6: Render the group message view +## Step 8: Render the group message view Combine `CometChatMessageList` and `CometChatMessageComposer` to display messages and allow sending within the selected group. @@ -165,9 +285,9 @@ function GroupMessageView({ group }: { group: CometChat.Group }) { } ``` -## Step 7: Add a create-group form +## Step 9: Add a create-group form -Provide a simple UI for users to create groups on the fly. Wire it to the `createGroup` function from Step 2. +Provide a UI for users to create groups on the fly. Show a password field only when the selected type is password-protected, and pass it through to `createGroup` from Step 2. ```tsx import { useState } from "react"; @@ -176,21 +296,27 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => void }) { const [name, setName] = useState(""); const [type, setType] = useState(CometChat.GROUP_TYPE.PUBLIC); + const [password, setPassword] = useState(""); + + const isPasswordType = type === CometChat.GROUP_TYPE.PASSWORD; async function handleSubmit(e: React.FormEvent) { e.preventDefault(); if (!name.trim()) return; + if (isPasswordType && !password) return; // password is required for this type const group = new CometChat.Group( "group-" + Date.now(), name.trim(), - type as typeof CometChat.GROUP_TYPE.PUBLIC + type, + isPasswordType ? password : "" ); try { const createdGroup = await CometChat.createGroup(group); onCreate(createdGroup); setName(""); + setPassword(""); } catch (error) { console.error("Group creation failed:", error); } @@ -210,9 +336,18 @@ function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => v style={{ width: "100%", marginBottom: "8px", padding: "8px" }} > - + + {isPasswordType && ( + setPassword(e.target.value)} + placeholder="Group password" + style={{ width: "100%", marginBottom: "8px", padding: "8px" }} + /> + )} @@ -237,21 +372,27 @@ import { function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => void }) { const [name, setName] = useState(""); const [type, setType] = useState(CometChat.GROUP_TYPE.PUBLIC); + const [password, setPassword] = useState(""); + + const isPasswordType = type === CometChat.GROUP_TYPE.PASSWORD; async function handleSubmit(e: React.FormEvent) { e.preventDefault(); if (!name.trim()) return; + if (isPasswordType && !password) return; const group = new CometChat.Group( "group-" + Date.now(), name.trim(), - type as typeof CometChat.GROUP_TYPE.PUBLIC + type, + isPasswordType ? password : "" ); try { const createdGroup = await CometChat.createGroup(group); onCreate(createdGroup); setName(""); + setPassword(""); } catch (error) { console.error("Group creation failed:", error); } @@ -271,9 +412,18 @@ function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => v style={{ width: "100%", marginBottom: "8px", padding: "8px" }} > - + + {isPasswordType && ( + setPassword(e.target.value)} + placeholder="Group password" + style={{ width: "100%", marginBottom: "8px", padding: "8px" }} + /> + )} @@ -357,7 +507,8 @@ export default App; ## Next Steps - [Groups](/ui-kit/react/components/groups) — browse and join existing groups -- [Group Members](/ui-kit/react/components/group-members) — manage group membership +- [Group Members](/ui-kit/react/components/group-members) — manage group membership with role-based actions +- [Kick / Ban Members](/sdk/javascript/group-kick-ban-members) · [Change Member Scope](/sdk/javascript/group-change-member-scope) · [Transfer Ownership](/sdk/javascript/transfer-group-ownership) — SDK references - [Message Header](/ui-kit/react/components/message-header) — customize the group header - [Event System](/ui-kit/react/event-system#user--group-actions) — react to `ui:group/created` and other group action events - [CometChatProvider](/ui-kit/react/cometchat-provider) — configure the root provider From 84032eef78a1e1a709dd503ab1fe4506b63bbe24 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Fri, 14 Aug 2026 12:42:54 +0530 Subject: [PATCH 08/63] Fixed Link Rot issue --- ui-kit/react/llms-react-v7.mdx | 144 ++++++++++++++++----------------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/ui-kit/react/llms-react-v7.mdx b/ui-kit/react/llms-react-v7.mdx index 6b69549e0..d5ac71012 100644 --- a/ui-kit/react/llms-react-v7.mdx +++ b/ui-kit/react/llms-react-v7.mdx @@ -22,9 +22,9 @@ description: "Machine-readable, React-v7-scoped index of every UI Kit page as a > agents — a scoped alternative to the site-wide `/docs/llms.txt`. ## How to use this index -Each link below is already a **`.md` twin** (clean Markdown: verbatim code + an -"AI Integration Quick Reference" block with prop names, types, and defaults). Pick the page for -the intent, fetch its `.md`, read the props there. +Each link points to the docs page; **append `.md`** to its URL to fetch the clean Markdown twin +(verbatim code + an "AI Integration Quick Reference" block with prop names, types, and defaults). +Pick the page for the intent, then read the props there. - Convention: any docs page URL + `.md` → raw Markdown. - Fallback: if a `.md` twin 404s, fetch the same URL **without** `.md` (HTML). Never read a package `.d.ts` and never answer props from memory. @@ -33,94 +33,94 @@ the intent, fetch its `.md`, read the props there. For a plain "add chat" the install, `init → login → render`, provider, and the core drop-in props are stable; a well-built agent skill bakes them. Fetch below only for exhaustive props, long-tail components, theming tokens, or feature enablement. -- Setup: [React.js Integration](integration-react.md) -- Provider/lifecycle: [CometChatProvider](cometchat-provider.md) -- Core drop-ins: [Conversations](components/conversations.md) · [Message Header](components/message-header.md) · [Message List](components/message-list.md) · [Message Composer](components/message-composer.md) +- Setup: [React.js Integration](/ui-kit/react/integration-react) +- Provider/lifecycle: [CometChatProvider](/ui-kit/react/cometchat-provider) +- Core drop-ins: [Conversations](/ui-kit/react/components/conversations) · [Message Header](/ui-kit/react/components/message-header) · [Message List](/ui-kit/react/components/message-list) · [Message Composer](/ui-kit/react/components/message-composer) ## Getting started / integration -- [React.js Integration](integration-react.md) -- [Next.js Integration](integration-nextjs.md) -- [React Router Integration](integration-react-router.md) -- [Astro Integration](integration-astro.md) -- [React UI Kit — Overview](overview.md) -- [Components Overview](components-overview.md) +- [React.js Integration](/ui-kit/react/integration-react) +- [Next.js Integration](/ui-kit/react/integration-nextjs) +- [React Router Integration](/ui-kit/react/integration-react-router) +- [Astro Integration](/ui-kit/react/integration-astro) +- [React UI Kit — Overview](/ui-kit/react/overview) +- [Components Overview](/ui-kit/react/components-overview) ## Core & configuration -- [CometChatProvider](cometchat-provider.md) -- [Core Features](core-features.md) -- [Methods](methods.md) -- [Event System](event-system.md) -- [Sound Manager](sound-manager.md) -- [Localization](localization.md) -- [Extensions](extensions.md) -- [Troubleshooting](troubleshooting.md) +- [CometChatProvider](/ui-kit/react/cometchat-provider) +- [Core Features](/ui-kit/react/core-features) +- [Methods](/ui-kit/react/methods) +- [Event System](/ui-kit/react/event-system) +- [Sound Manager](/ui-kit/react/sound-manager) +- [Localization](/ui-kit/react/localization) +- [Extensions](/ui-kit/react/extensions) +- [Troubleshooting](/ui-kit/react/troubleshooting) ## Theming -- [Theming (`--cometchat-*` tokens, light/dark)](theming.md) +- [Theming (`--cometchat-*` tokens, light/dark)](/ui-kit/react/theming) ## Components — conversations & lists -- [Conversations](components/conversations.md) -- [Users](components/users.md) -- [Groups](components/groups.md) -- [Group Members](components/group-members.md) +- [Conversations](/ui-kit/react/components/conversations) +- [Users](/ui-kit/react/components/users) +- [Groups](/ui-kit/react/components/groups) +- [Group Members](/ui-kit/react/components/group-members) ## Components — messages -- [Message Header](components/message-header.md) -- [Message List](components/message-list.md) -- [Message Composer](components/message-composer.md) -- [Message Bubble](components/message-bubble.md) -- [Thread Header](components/thread-header.md) -- [Message Information](components/message-information.md) -- [Reactions](components/reactions.md) -- [Reaction List](components/reaction-list.md) -- [Flag Message Dialog](components/flag-message-dialog.md) +- [Message Header](/ui-kit/react/components/message-header) +- [Message List](/ui-kit/react/components/message-list) +- [Message Composer](/ui-kit/react/components/message-composer) +- [Message Bubble](/ui-kit/react/components/message-bubble) +- [Thread Header](/ui-kit/react/components/thread-header) +- [Message Information](/ui-kit/react/components/message-information) +- [Reactions](/ui-kit/react/components/reactions) +- [Reaction List](/ui-kit/react/components/reaction-list) +- [Flag Message Dialog](/ui-kit/react/components/flag-message-dialog) ## Components — message bubbles -- [Text Bubble](components/text-bubble.md) -- [Image Bubble](components/image-bubble.md) -- [Video Bubble](components/video-bubble.md) -- [Audio Bubble](components/audio-bubble.md) -- [Voice Note Bubble](components/voice-note-bubble.md) -- [File Bubble](components/file-bubble.md) -- [Poll Bubble](components/poll-bubble.md) -- [Sticker Bubble](components/sticker-bubble.md) -- [Card Bubble](components/card-bubble.md) -- [Collaborative Document Bubble](components/collaborative-document-bubble.md) -- [Collaborative Whiteboard Bubble](components/collaborative-whiteboard-bubble.md) -- [Call Bubble](components/call-bubble.md) -- [Call Action Bubble](components/call-action-bubble.md) -- [Group Action Bubble](components/group-action-bubble.md) -- [Delete Bubble](components/delete-bubble.md) +- [Text Bubble](/ui-kit/react/components/text-bubble) +- [Image Bubble](/ui-kit/react/components/image-bubble) +- [Video Bubble](/ui-kit/react/components/video-bubble) +- [Audio Bubble](/ui-kit/react/components/audio-bubble) +- [Voice Note Bubble](/ui-kit/react/components/voice-note-bubble) +- [File Bubble](/ui-kit/react/components/file-bubble) +- [Poll Bubble](/ui-kit/react/components/poll-bubble) +- [Sticker Bubble](/ui-kit/react/components/sticker-bubble) +- [Card Bubble](/ui-kit/react/components/card-bubble) +- [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) +- [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) +- [Call Bubble](/ui-kit/react/components/call-bubble) +- [Call Action Bubble](/ui-kit/react/components/call-action-bubble) +- [Group Action Bubble](/ui-kit/react/components/group-action-bubble) +- [Delete Bubble](/ui-kit/react/components/delete-bubble) ## Components — calling -- [Call Buttons](components/call-buttons.md) -- [Incoming Call](components/incoming-call.md) -- [Outgoing Call](components/outgoing-call.md) -- [Call Logs](components/call-logs.md) -- [Calling Integration](calling-integration.md) -- [Call Features](call-features.md) +- [Call Buttons](/ui-kit/react/components/call-buttons) +- [Incoming Call](/ui-kit/react/components/incoming-call) +- [Outgoing Call](/ui-kit/react/components/outgoing-call) +- [Call Logs](/ui-kit/react/components/call-logs) +- [Calling Integration](/ui-kit/react/calling-integration) +- [Call Features](/ui-kit/react/call-features) ## Components — search, AI & notifications -- [Search](components/search.md) -- [AI Assistant Chat](components/ai-assistant-chat.md) -- [Smart / AI Features](ai-features.md) -- [Notification Feed](components/notification-feed.md) +- [Search](/ui-kit/react/components/search) +- [AI Assistant Chat](/ui-kit/react/components/ai-assistant-chat) +- [Smart / AI Features](/ui-kit/react/ai-features) +- [Notification Feed](/ui-kit/react/components/notification-feed) ## Task guides (recipes) -- [New Chat Creation](guide-new-chat-creation.md) -- [Group Chat Setup](guide-group-chat-setup.md) -- [Search Messages](guide-search-messages.md) -- [Threaded Messages](guide-threaded-messages.md) -- [Message Privately](guide-message-privately.md) -- [Block / Unblock User](guide-block-unblock-user.md) +- [New Chat Creation](/ui-kit/react/guide-new-chat-creation) +- [Group Chat Setup](/ui-kit/react/guide-group-chat-setup) +- [Search Messages](/ui-kit/react/guide-search-messages) +- [Threaded Messages](/ui-kit/react/guide-threaded-messages) +- [Message Privately](/ui-kit/react/guide-message-privately) +- [Block / Unblock User](/ui-kit/react/guide-block-unblock-user) ## Framework recipes (full-page layouts) -- React: [Conversation + Messages](react-conversation.md) · [One-to-One / Group](react-one-to-one-chat.md) · [Tab-Based](react-tab-based-chat.md) -- Next.js: [Conversation + Messages](next-conversation.md) · [One-to-One / Group](next-one-to-one-chat.md) · [Tab-Based](next-tab-based-chat.md) -- React Router: [Conversation + Messages](react-router-conversation.md) · [One-to-One / Group](react-router-one-to-one-chat.md) · [Tab-Based](react-router-tab-based-chat.md) -- Astro: [Conversation + Messages](astro-conversation.md) · [One-to-One / Group](astro-one-to-one-chat.md) · [Tab-Based](astro-tab-based-chat.md) +- React: [Conversation + Messages](/ui-kit/react/react-conversation) · [One-to-One / Group](/ui-kit/react/react-one-to-one-chat) · [Tab-Based](/ui-kit/react/react-tab-based-chat) +- Next.js: [Conversation + Messages](/ui-kit/react/next-conversation) · [One-to-One / Group](/ui-kit/react/next-one-to-one-chat) · [Tab-Based](/ui-kit/react/next-tab-based-chat) +- React Router: [Conversation + Messages](/ui-kit/react/react-router-conversation) · [One-to-One / Group](/ui-kit/react/react-router-one-to-one-chat) · [Tab-Based](/ui-kit/react/react-router-tab-based-chat) +- Astro: [Conversation + Messages](/ui-kit/react/astro-conversation) · [One-to-One / Group](/ui-kit/react/astro-one-to-one-chat) · [Tab-Based](/ui-kit/react/astro-tab-based-chat) ## Migration & misc -- [Upgrading from v6 to v7](migration-overview.md) -- [v6 → v7 Property Changes](migration-property-changes.md) -- [Campaigns](campaigns.md) +- [Upgrading from v6 to v7](/ui-kit/react/migration-overview) +- [v6 → v7 Property Changes](/ui-kit/react/migration-property-changes) +- [Campaigns](/ui-kit/react/campaigns) From 04301fba7b5320af7f20556da6ec875ec8d0b152 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Fri, 14 Aug 2026 12:47:34 +0530 Subject: [PATCH 09/63] Fixed Link Rot Issue --- sdk/javascript/llms-javascript-v4.mdx | 126 +++++++++++++------------- 1 file changed, 63 insertions(+), 63 deletions(-) diff --git a/sdk/javascript/llms-javascript-v4.mdx b/sdk/javascript/llms-javascript-v4.mdx index 48c32d3f3..98f212703 100644 --- a/sdk/javascript/llms-javascript-v4.mdx +++ b/sdk/javascript/llms-javascript-v4.mdx @@ -22,9 +22,9 @@ description: "Machine-readable, JavaScript-SDK-v4-scoped index of every SDK page > AI agents — a scoped alternative to the site-wide `/docs/llms.txt`. ## How to use this index -Each link below is already a **`.md` twin** (clean Markdown: verbatim code + method signatures, -parameters, and listener contracts). Pick the page for the intent, fetch its `.md`, read the API -there. +Each link points to the docs page; **append `.md`** to its URL to fetch the clean Markdown twin +(verbatim code + method signatures, parameters, and listener contracts). Pick the page for the +intent, then read the API there. - Convention: any docs page URL + `.md` → raw Markdown. - Fallback: if a `.md` twin 404s, fetch the same URL **without** `.md` (HTML). Never read a package `.d.ts` and never answer APIs from memory. @@ -33,81 +33,81 @@ there. For a plain "add chat" the install, `init → login`, and the core `sendMessage` / `receive-message` listener flow are stable; a well-built agent skill bakes them. Fetch below only for exhaustive parameters, long-tail methods, group/user management, calling, or edge-case listeners. -- Setup: [Integration / Setup](setup-sdk.md) -- Auth/lifecycle: [Authentication](authentication-overview.md) -- Core send/receive: [Send a Message](send-message.md) · [Receive a Message](receive-message.md) · [Real-time Listeners](all-real-time-listeners.md) +- Setup: [Integration / Setup](/sdk/javascript/setup-sdk) +- Auth/lifecycle: [Authentication](/sdk/javascript/authentication-overview) +- Core send/receive: [Send a Message](/sdk/javascript/send-message) · [Receive a Message](/sdk/javascript/receive-message) · [Real-time Listeners](/sdk/javascript/all-real-time-listeners) ## Getting started / integration -- [Overview](overview.md) -- [Integration / Setup](setup-sdk.md) -- [Authentication](authentication-overview.md) +- [Overview](/sdk/javascript/overview) +- [Integration / Setup](/sdk/javascript/setup-sdk) +- [Authentication](/sdk/javascript/authentication-overview) ## Messaging -- [Send a Message](send-message.md) -- [Media & File Messages](upload-files.md) -- [Receive a Message](receive-message.md) -- [Interactive / Card Messages](card-messages.md) -- [Message Filtering](message-filtering.md) -- [Retrieve Conversations](retrieve-conversations.md) -- [Threaded Messages](threaded-messages.md) -- [Edit a Message](edit-message.md) -- [Delete a Message](delete-message.md) -- [Flag a Message](flag-message.md) -- [Delete a Conversation](delete-conversation.md) -- [Typing Indicators](typing-indicators.md) -- [Transient Messages](transient-messages.md) -- [Delivery & Read Receipts](delivery-read-receipts.md) -- [Mentions](mentions.md) -- [Reactions](reactions.md) +- [Send a Message](/sdk/javascript/send-message) +- [Media & File Messages](/sdk/javascript/upload-files) +- [Receive a Message](/sdk/javascript/receive-message) +- [Interactive / Card Messages](/sdk/javascript/card-messages) +- [Message Filtering](/sdk/javascript/message-filtering) +- [Retrieve Conversations](/sdk/javascript/retrieve-conversations) +- [Threaded Messages](/sdk/javascript/threaded-messages) +- [Edit a Message](/sdk/javascript/edit-message) +- [Delete a Message](/sdk/javascript/delete-message) +- [Flag a Message](/sdk/javascript/flag-message) +- [Delete a Conversation](/sdk/javascript/delete-conversation) +- [Typing Indicators](/sdk/javascript/typing-indicators) +- [Transient Messages](/sdk/javascript/transient-messages) +- [Delivery & Read Receipts](/sdk/javascript/delivery-read-receipts) +- [Mentions](/sdk/javascript/mentions) +- [Reactions](/sdk/javascript/reactions) ## Calling -- [Calling — Overview](calling-overview.md) +- [Calling — Overview](/sdk/javascript/calling-overview) ## Users -- [Users — Overview](users-overview.md) -- [Retrieve Users](retrieve-users.md) -- [User Management](user-management.md) -- [Block Users](block-users.md) -- [User Presence](user-presence.md) +- [Users — Overview](/sdk/javascript/users-overview) +- [Retrieve Users](/sdk/javascript/retrieve-users) +- [User Management](/sdk/javascript/user-management) +- [Block Users](/sdk/javascript/block-users) +- [User Presence](/sdk/javascript/user-presence) ## Groups -- [Groups — Overview](groups-overview.md) -- [Retrieve Groups](retrieve-groups.md) -- [Create a Group](create-group.md) -- [Update a Group](update-group.md) -- [Join a Group](join-group.md) -- [Leave a Group](leave-group.md) -- [Delete a Group](delete-group.md) -- [Retrieve Group Members](retrieve-group-members.md) -- [Add Group Members](group-add-members.md) -- [Kick / Ban Members](group-kick-ban-members.md) -- [Change Member Scope](group-change-member-scope.md) -- [Transfer Group Ownership](transfer-group-ownership.md) +- [Groups — Overview](/sdk/javascript/groups-overview) +- [Retrieve Groups](/sdk/javascript/retrieve-groups) +- [Create a Group](/sdk/javascript/create-group) +- [Update a Group](/sdk/javascript/update-group) +- [Join a Group](/sdk/javascript/join-group) +- [Leave a Group](/sdk/javascript/leave-group) +- [Delete a Group](/sdk/javascript/delete-group) +- [Retrieve Group Members](/sdk/javascript/retrieve-group-members) +- [Add Group Members](/sdk/javascript/group-add-members) +- [Kick / Ban Members](/sdk/javascript/group-kick-ban-members) +- [Change Member Scope](/sdk/javascript/group-change-member-scope) +- [Transfer Group Ownership](/sdk/javascript/transfer-group-ownership) ## AI, campaigns & webhooks -- [AI Moderation](ai-moderation.md) -- [AI Agents](ai-agents.md) -- [AI Copilot](ai-copilot.md) -- [Campaigns](campaigns.md) -- [Webhooks](webhooks.md) +- [AI Moderation](/sdk/javascript/ai-moderation) +- [AI Agents](/sdk/javascript/ai-agents) +- [AI Copilot](/sdk/javascript/ai-copilot) +- [Campaigns](/sdk/javascript/campaigns) +- [Webhooks](/sdk/javascript/webhooks) ## Resources -- [Key Concepts](key-concepts.md) -- [Message Structure & Hierarchy](message-structure-and-hierarchy.md) -- [All Real-time Listeners](all-real-time-listeners.md) -- [Rate Limits](rate-limits.md) -- [Connection Status](connection-status.md) -- [Managing WebSocket Connections Manually](managing-web-sockets-connections-manually.md) +- [Key Concepts](/sdk/javascript/key-concepts) +- [Message Structure & Hierarchy](/sdk/javascript/message-structure-and-hierarchy) +- [All Real-time Listeners](/sdk/javascript/all-real-time-listeners) +- [Rate Limits](/sdk/javascript/rate-limits) +- [Connection Status](/sdk/javascript/connection-status) +- [Managing WebSocket Connections Manually](/sdk/javascript/managing-web-sockets-connections-manually) ## Best practices & troubleshooting -- [Best Practices](best-practices.md) -- [Error Codes](error-codes.md) -- [Troubleshooting](troubleshooting.md) +- [Best Practices](/sdk/javascript/best-practices) +- [Error Codes](/sdk/javascript/error-codes) +- [Troubleshooting](/sdk/javascript/troubleshooting) ## Migration & overviews -- [Upgrading from v3](upgrading-from-v3.md) -- [Extensions — Overview](extensions-overview.md) -- [AI User Copilot — Overview](ai-user-copilot-overview.md) -- [AI Chatbots — Overview](ai-chatbots-overview.md) -- [Webhooks — Overview](webhooks-overview.md) -- [Changelog](changelog.md) +- [Upgrading from v3](/sdk/javascript/upgrading-from-v3) +- [Extensions — Overview](/sdk/javascript/extensions-overview) +- [AI User Copilot — Overview](/sdk/javascript/ai-user-copilot-overview) +- [AI Chatbots — Overview](/sdk/javascript/ai-chatbots-overview) +- [Webhooks — Overview](/sdk/javascript/webhooks-overview) +- [Changelog](/sdk/javascript/changelog) From 134933ec0b8f6f1f3e7a42a120b03d20ed1186d0 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 17 Aug 2026 15:51:07 +0530 Subject: [PATCH 10/63] Updated Code Snippets --- ui-kit/react/astro-tab-based-chat.mdx | 37 +++++++++++++-- ui-kit/react/components/conversations.mdx | 8 +++- ui-kit/react/components/groups.mdx | 1 + ui-kit/react/components/users.mdx | 1 + ui-kit/react/guide-group-chat-setup.mdx | 26 +++++++---- ui-kit/react/guide-new-chat-creation.mdx | 48 ++++++++++++-------- ui-kit/react/next-tab-based-chat.mdx | 39 ++++++++++++++-- ui-kit/react/react-conversation.mdx | 36 ++++++++++++++- ui-kit/react/react-router-tab-based-chat.mdx | 39 ++++++++++++++-- ui-kit/react/react-tab-based-chat.mdx | 39 ++++++++++++++-- 10 files changed, 230 insertions(+), 44 deletions(-) diff --git a/ui-kit/react/astro-tab-based-chat.mdx b/ui-kit/react/astro-tab-based-chat.mdx index 3d6b45ee0..4d5d92e65 100644 --- a/ui-kit/react/astro-tab-based-chat.mdx +++ b/ui-kit/react/astro-tab-based-chat.mdx @@ -53,6 +53,7 @@ import { CometChatConversations, CometChatUsers, CometChatCallLogs, + CometChatGroupMembers, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer, @@ -65,6 +66,8 @@ export default function TabbedChat() { const [activeTab, setActiveTab] = useState("chat"); const [selectedUser, setSelectedUser] = useState(undefined); const [selectedGroup, setSelectedGroup] = useState(undefined); + const [selectedConversation, setSelectedConversation] = useState(undefined); + const [showDetails, setShowDetails] = useState(false); useEffect(() => { const settings = new UIKitSettingsBuilder() @@ -83,6 +86,7 @@ export default function TabbedChat() { if (!ready) return
Loading chat...
; const handleConversationClick = (conversation: CometChat.Conversation) => { + setSelectedConversation(conversation); // highlights the open row in the Conversations list const entity = conversation.getConversationWith(); if (conversation.getConversationType() === "user") { setSelectedUser(entity as CometChat.User); @@ -182,20 +186,27 @@ export default function TabbedChat() {
{activeTab === "chat" && ( - + )} {activeTab === "calls" && ( )} {activeTab === "users" && ( - + )}
{selectedUser || selectedGroup ? (
- + setShowDetails(true)} + />
@@ -212,6 +223,23 @@ export default function TabbedChat() { Select a conversation to start chatting
)} + + {/* Details / members side panel — opened from the header, closed via onBack */} + {showDetails && selectedGroup && ( +
+ setShowDetails(false)} + /> +
+ )} ); @@ -245,6 +273,8 @@ import TabbedChat from '../components/TabbedChat.tsx'; 4. **Conditional rendering** — only the active tab's component mounts. Switching tabs unmounts the previous list and mounts the new one. 5. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel. 6. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components. +7. **Active highlight** — the current selection is passed back to each list as `activeConversation` / `activeUser` (and `activeGroup` on a Groups tab), so the open row stays highlighted while its chat is on screen. +8. **Details panel round-trip** — clicking the message header opens a group details / members side panel (`CometChatGroupMembers`). Its `onBack` sets `showDetails` back to `false`, closing the panel — the full open→close cycle, not just opening it. --- @@ -283,6 +313,7 @@ type Tab = "chat" | "calls" | "users" | "groups"; setSelectedGroup(group); setSelectedUser(undefined); }} + activeGroup={selectedGroup} /> )} ``` diff --git a/ui-kit/react/components/conversations.mdx b/ui-kit/react/components/conversations.mdx index b3af4e9fc..524c4d23f 100644 --- a/ui-kit/react/components/conversations.mdx +++ b/ui-kit/react/components/conversations.mdx @@ -17,6 +17,7 @@ description: "Scrollable list of recent one-on-one and group conversations for t | Events emitted | `ui:conversation/deleted` — see the [Event System](/ui-kit/react/event-system) | | Events received | Subscribes to `ui:message/*`, `ui:conversation/*`, and `ui:group/*` events published by other components — see the [Event System](/ui-kit/react/event-system) | | SDK listeners (automatic) | Messages, typing, receipts, presence, and group membership are handled internally — no wiring needed | +| Active highlight | Pass the selected conversation back as `activeConversation` to highlight the open row — see [activeConversation](#activeconversation) | | Full props | See [Props](#props) | @@ -107,8 +108,10 @@ import { function ChatApp() { const [user, setUser] = useState(); const [group, setGroup] = useState(); + const [activeConversation, setActiveConversation] = useState(); const handleConversationClick = (conversation: CometChat.Conversation) => { + setActiveConversation(conversation); // highlights the open row in the list const entity = conversation.getConversationWith(); if (conversation.getConversationType() === "user") { setUser(entity as CometChat.User); @@ -122,7 +125,10 @@ function ChatApp() { return (
- +
diff --git a/ui-kit/react/components/groups.mdx b/ui-kit/react/components/groups.mdx index 23a3de6bc..cc2b6dd51 100644 --- a/ui-kit/react/components/groups.mdx +++ b/ui-kit/react/components/groups.mdx @@ -16,6 +16,7 @@ description: "Searchable, scrollable list of groups with selection support and r | Stitching | Emits the selected group; wire `onItemClick` to open it (mount MessageHeader/List/Composer) — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) | | Events received | `ui:group/created`, `ui:group/deleted`, `ui:group/left`, and `ui:group/member-*` / `ui:group/ownership-changed` — keeps the list in sync — see the [Event System](/ui-kit/react/event-system#user--group-actions) | | SDK listeners (automatic) | Group membership changes — handled internally | +| Active highlight | Pass the selected group back as `activeGroup` to highlight the open row — see [activeGroup](#activegroup) | | Full props | See [Props](#props) | diff --git a/ui-kit/react/components/users.mdx b/ui-kit/react/components/users.mdx index b5410ff44..11c5157a8 100644 --- a/ui-kit/react/components/users.mdx +++ b/ui-kit/react/components/users.mdx @@ -16,6 +16,7 @@ description: "Searchable, scrollable list of users with selection support and re | Stitching | Emits the selected user; wire `onItemClick` to open a chat (mount MessageHeader/List/Composer) — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) | | Events received | `ui:user/blocked`, `ui:user/unblocked` — see [Event System](/ui-kit/react/event-system) | | SDK listeners (automatic) | User presence (online/offline) | +| Active highlight | Pass the selected user back as `activeUser` to highlight the open row — see [activeUser](#activeuser) | | Full props | See [Props](#props) | diff --git a/ui-kit/react/guide-group-chat-setup.mdx b/ui-kit/react/guide-group-chat-setup.mdx index 930153810..b67873882 100644 --- a/ui-kit/react/guide-group-chat-setup.mdx +++ b/ui-kit/react/guide-group-chat-setup.mdx @@ -358,6 +358,10 @@ function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => v ## Complete Example + +The **"New Group"** button lives in the conversation list's `headerView` slot — not in a separate `
` stacked above the list — so the list header stays intact and the layout doesn't shift. Because `headerView` replaces the entire default header, re-render the default title (**"Chats"**) alongside the button. + + ```tsx GroupChat.tsx import { useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -464,19 +468,21 @@ function GroupChat() { return (
-
- -
- {showCreateForm && }
- + + Chats + +
+ } + />
diff --git a/ui-kit/react/guide-new-chat-creation.mdx b/ui-kit/react/guide-new-chat-creation.mdx index 2572cbc7f..67d708109 100644 --- a/ui-kit/react/guide-new-chat-creation.mdx +++ b/ui-kit/react/guide-new-chat-creation.mdx @@ -49,7 +49,7 @@ export default App; ## Step 2: Add a "New Chat" trigger -Create a button that opens a selection panel. Use component state to toggle between the conversations view and the user/group selection view. +Create a button that opens a selection panel. Use component state to toggle between the conversations view and the user/group selection view. Put the **"New Chat"** trigger in the conversation list's `headerView` slot rather than a separate `
` stacked above the list — that keeps the header intact and the layout stable. Because `headerView` replaces the entire default header, re-render the default title (**"Chats"**) next to the button. ```tsx NewChatApp.tsx import { useState } from "react"; @@ -67,17 +67,9 @@ function NewChatApp() { return (
-
- -
- {showNewChat ? ( setShowNewChat(false)} onSelectUser={(user) => { setActiveChat({ type: "user", entity: user }); setShowNewChat(false); @@ -90,6 +82,13 @@ function NewChatApp() { ) : (
+ Chats + +
+ } onItemClick={(conversation) => { const entity = conversation.getConversationWith(); if (entity instanceof CometChat.User) { @@ -127,9 +126,11 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; import { CometChatUsers, CometChatGroups } from "@cometchat/chat-uikit-react"; function UserGroupSelector({ + onCancel, onSelectUser, onSelectGroup, }: { + onCancel: () => void; onSelectUser: (user: CometChat.User) => void; onSelectGroup: (group: CometChat.Group) => void; }) { @@ -137,6 +138,10 @@ function UserGroupSelector({ return (
+
+ New Chat + +
+
-
- {showNewChat ? ( setShowNewChat(false)} onSelectUser={(user) => { setActiveChat({ type: "user", entity: user }); setShowNewChat(false); @@ -374,6 +377,13 @@ function NewChatApp() { ) : (
+ Chats + +
+ } onItemClick={(conversation) => { const entity = conversation.getConversationWith(); if (entity instanceof CometChat.User) { diff --git a/ui-kit/react/next-tab-based-chat.mdx b/ui-kit/react/next-tab-based-chat.mdx index 35b9649ed..ee8ee4c54 100644 --- a/ui-kit/react/next-tab-based-chat.mdx +++ b/ui-kit/react/next-tab-based-chat.mdx @@ -55,6 +55,7 @@ import { CometChatConversations, CometChatUsers, CometChatCallLogs, + CometChatGroupMembers, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer, @@ -67,6 +68,8 @@ export default function CometChatClient() { const [activeTab, setActiveTab] = useState("chat"); const [selectedUser, setSelectedUser] = useState(undefined); const [selectedGroup, setSelectedGroup] = useState(undefined); + const [selectedConversation, setSelectedConversation] = useState(undefined); + const [showDetails, setShowDetails] = useState(false); useEffect(() => { const settings = new UIKitSettingsBuilder() @@ -85,6 +88,7 @@ export default function CometChatClient() { if (!ready) return
Loading chat...
; const handleConversationClick = (conversation: CometChat.Conversation) => { + setSelectedConversation(conversation); // highlights the open row in the Conversations list const entity = conversation.getConversationWith(); if (conversation.getConversationType() === "user") { setSelectedUser(entity as CometChat.User); @@ -144,20 +148,27 @@ export default function CometChatClient() {
{activeTab === "chat" && ( - + )} {activeTab === "calls" && ( )} {activeTab === "users" && ( - + )}
{selectedUser || selectedGroup ? (
- + setShowDetails(true)} + />
@@ -166,6 +177,16 @@ export default function CometChatClient() { Select a conversation to start chatting
)} + + {/* Details / members side panel — opened from the header, closed via onBack */} + {showDetails && selectedGroup && ( +
+ setShowDetails(false)} + /> +
+ )}
); @@ -228,6 +249,15 @@ export default function CometChatClient() { flex-direction: column; } +.details-panel { + width: 320px; + height: 100%; + border-left: 1px solid #eee; + overflow: hidden; + display: flex; + flex-direction: column; +} + .empty-conversation { flex: 1; display: flex; @@ -259,6 +289,8 @@ export default function ChatPage() { 4. **Conditional rendering** — only the active tab's component mounts. Switching tabs unmounts the previous list and mounts the new one. 5. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel. 6. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components. +7. **Active highlight** — the current selection is passed back to each list as `activeConversation` / `activeUser` (and `activeGroup` on a Groups tab), so the open row stays highlighted while its chat is on screen. +8. **Details panel round-trip** — clicking the message header opens a group details / members side panel (`CometChatGroupMembers`). Its `onBack` sets `showDetails` back to `false`, closing the panel — the full open→close cycle, not just opening it. --- @@ -287,6 +319,7 @@ type Tab = "chat" | "calls" | "users" | "groups"; setSelectedGroup(group); setSelectedUser(undefined); }} + activeGroup={selectedGroup} /> )} ``` diff --git a/ui-kit/react/react-conversation.mdx b/ui-kit/react/react-conversation.mdx index e4f13a2e3..342ffaab5 100644 --- a/ui-kit/react/react-conversation.mdx +++ b/ui-kit/react/react-conversation.mdx @@ -48,6 +48,7 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; import { CometChatProvider, CometChatConversations, + CometChatGroupMembers, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer, @@ -57,8 +58,11 @@ import "./App.css"; function App() { const [selectedUser, setSelectedUser] = useState(undefined); const [selectedGroup, setSelectedGroup] = useState(undefined); + const [selectedConversation, setSelectedConversation] = useState(undefined); + const [showDetails, setShowDetails] = useState(false); const handleConversationClick = (conversation: CometChat.Conversation) => { + setSelectedConversation(conversation); // highlights the open row in the Conversations list const entity = conversation.getConversationWith(); if (conversation.getConversationType() === "user") { setSelectedUser(entity as CometChat.User); @@ -73,12 +77,19 @@ function App() {
- +
{selectedUser || selectedGroup ? (
- + setShowDetails(true)} + />
@@ -87,6 +98,16 @@ function App() { Select a conversation to start chatting
)} + + {/* Details / members side panel — opened from the header, closed via onBack */} + {showDetails && selectedGroup && ( +
+ setShowDetails(false)} + /> +
+ )}
); @@ -118,6 +139,15 @@ export default App; flex-direction: column; } +.details-panel { + width: 320px; + height: 100%; + border-left: 1px solid #eee; + overflow: hidden; + display: flex; + flex-direction: column; +} + .empty-conversation { flex: 1; display: flex; @@ -138,6 +168,8 @@ export default App; 3. **handleConversationClick** extracts the `User` or `Group` from the conversation and stores it in state. 4. **Message components** (`MessageHeader`, `MessageList`, `MessageComposer`) receive either `user` or `group` as a prop — never both at the same time. 5. When the user switches conversations, state updates and the message panel re-renders with the new chat. +6. **Active highlight** — the selected conversation is passed back to the list as `activeConversation`, so the open row stays highlighted while its chat is on screen. +7. **Details panel round-trip** — clicking the message header opens a group details / members side panel (`CometChatGroupMembers`). Its `onBack` sets `showDetails` back to `false` to close it — the full open→close cycle for the side panel, not just opening it. --- diff --git a/ui-kit/react/react-router-tab-based-chat.mdx b/ui-kit/react/react-router-tab-based-chat.mdx index e6ee11cf7..023621579 100644 --- a/ui-kit/react/react-router-tab-based-chat.mdx +++ b/ui-kit/react/react-router-tab-based-chat.mdx @@ -51,6 +51,7 @@ import { CometChatConversations, CometChatUsers, CometChatCallLogs, + CometChatGroupMembers, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer, @@ -63,8 +64,11 @@ export default function TabbedChatPage() { const [activeTab, setActiveTab] = useState("chat"); const [selectedUser, setSelectedUser] = useState(undefined); const [selectedGroup, setSelectedGroup] = useState(undefined); + const [selectedConversation, setSelectedConversation] = useState(undefined); + const [showDetails, setShowDetails] = useState(false); const handleConversationClick = (conversation: CometChat.Conversation) => { + setSelectedConversation(conversation); // highlights the open row in the Conversations list const entity = conversation.getConversationWith(); if (conversation.getConversationType() === "user") { setSelectedUser(entity as CometChat.User); @@ -124,20 +128,27 @@ export default function TabbedChatPage() {
{activeTab === "chat" && ( - + )} {activeTab === "calls" && ( )} {activeTab === "users" && ( - + )}
{selectedUser || selectedGroup ? (
- + setShowDetails(true)} + />
@@ -146,6 +157,16 @@ export default function TabbedChatPage() { Select a conversation to start chatting
)} + + {/* Details / members side panel — opened from the header, closed via onBack */} + {showDetails && selectedGroup && ( +
+ setShowDetails(false)} + /> +
+ )}
); @@ -208,6 +229,15 @@ export default function TabbedChatPage() { flex-direction: column; } +.details-panel { + width: 320px; + height: 100%; + border-left: 1px solid #eee; + overflow: hidden; + display: flex; + flex-direction: column; +} + .empty-conversation { flex: 1; display: flex; @@ -248,6 +278,8 @@ export default App; 3. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel. 4. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components. 5. **React Router** handles navigation — the tabbed chat page is a route component at `/chat`. +6. **Active highlight** — the current selection is passed back to each list as `activeConversation` / `activeUser` (and `activeGroup` on a Groups tab), so the open row stays highlighted while its chat is on screen. +7. **Details panel round-trip** — clicking the message header opens a group details / members side panel (`CometChatGroupMembers`). Its `onBack` sets `showDetails` back to `false`, closing the panel — the full open→close cycle, not just opening it. --- @@ -276,6 +308,7 @@ type Tab = "chat" | "calls" | "users" | "groups"; setSelectedGroup(group); setSelectedUser(undefined); }} + activeGroup={selectedGroup} /> )} ``` diff --git a/ui-kit/react/react-tab-based-chat.mdx b/ui-kit/react/react-tab-based-chat.mdx index ba4b4146d..b4b2b3106 100644 --- a/ui-kit/react/react-tab-based-chat.mdx +++ b/ui-kit/react/react-tab-based-chat.mdx @@ -50,6 +50,7 @@ import { CometChatConversations, CometChatUsers, CometChatCallLogs, + CometChatGroupMembers, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer, @@ -62,8 +63,11 @@ function App() { const [activeTab, setActiveTab] = useState("chat"); const [selectedUser, setSelectedUser] = useState(undefined); const [selectedGroup, setSelectedGroup] = useState(undefined); + const [selectedConversation, setSelectedConversation] = useState(undefined); + const [showDetails, setShowDetails] = useState(false); const handleConversationClick = (conversation: CometChat.Conversation) => { + setSelectedConversation(conversation); // highlights the open row in the Conversations list const entity = conversation.getConversationWith(); if (conversation.getConversationType() === "user") { setSelectedUser(entity as CometChat.User); @@ -123,20 +127,27 @@ function App() {
{activeTab === "chat" && ( - + )} {activeTab === "calls" && ( )} {activeTab === "users" && ( - + )}
{selectedUser || selectedGroup ? (
- + setShowDetails(true)} + />
@@ -145,6 +156,16 @@ function App() { Select a conversation to start chatting )} + + {/* Details / members side panel — opened from the header, closed via onBack */} + {showDetails && selectedGroup && ( +
+ setShowDetails(false)} + /> +
+ )} ); @@ -209,6 +230,15 @@ export default App; flex-direction: column; } +.details-panel { + width: 320px; + height: 100%; + border-left: 1px solid #eee; + overflow: hidden; + display: flex; + flex-direction: column; +} + .empty-conversation { flex: 1; display: flex; @@ -228,6 +258,8 @@ export default App; 2. **Conditional rendering** — only the active tab's component mounts. Switching tabs unmounts the previous list and mounts the new one. 3. **Unified selection** — all three tabs feed into the same `selectedUser` / `selectedGroup` state. Clicking any item (conversation, call log, or user) updates the message panel. 4. **Call log handling** — when a call log is clicked, the receiver (user or group) is extracted and passed to the message components. +5. **Active highlight** — the current selection is passed back to each list as `activeConversation` / `activeUser` (and `activeGroup` on a Groups tab), so the open row stays highlighted while its chat is on screen. +6. **Details panel round-trip** — clicking the message header opens a group details / members side panel (`CometChatGroupMembers`). Its `onBack` sets `showDetails` back to `false`, closing the panel — the full open→close cycle, not just opening it. --- @@ -256,6 +288,7 @@ type Tab = "chat" | "calls" | "users" | "groups"; setSelectedGroup(group); setSelectedUser(undefined); }} + activeGroup={selectedGroup} /> )} ``` From 6c545160a0d9fa13bc853119baf862d39c8a269d Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 17 Aug 2026 16:04:39 +0530 Subject: [PATCH 11/63] Added CLI Docs --- agent-skills.mdx | 166 ++++++++++++++++++++++++++++++++++++++++++++ cli.mdx | 174 +++++++++++++++++++++++++++++++++++++++++++++++ docs.json | 7 ++ 3 files changed, 347 insertions(+) create mode 100644 agent-skills.mdx create mode 100644 cli.mdx diff --git a/agent-skills.mdx b/agent-skills.mdx new file mode 100644 index 000000000..db9ecb38f --- /dev/null +++ b/agent-skills.mdx @@ -0,0 +1,166 @@ +--- +title: "Build CometChat with AI Agent Skills" +sidebarTitle: "Agent Skills" +description: "Install the CometChat agent skills and let your AI coding agent — Claude Code, Cursor, GitHub Copilot, Replit, and more — add production-grade chat and calling to your React app from natural-language prompts." +canonical: "https://www.cometchat.com/docs/agent-skills" +--- + +**CometChat Agent Skills** teach your AI coding agent how to build with CometChat. +Install the skills once, then open your project and say *"add chat to my app"* — +the agent has a short conversation with you (framework, intent, placement, +credentials), then writes production-grade integration code directly into the +files you already have. + +The skills author against the official **React UI Kit v7** task guides and verify +their output against them, so what the agent writes builds and runs against the +current published UI Kit — not a hallucinated API. + + +The skills work **inside your existing project** with your existing agent. They +don't scaffold a throwaway demo — they detect your setup and integrate CometChat +into the app you're already building. + + +## Install + +Run the installer in your project root: + +```bash +npx @cometchat/skills add +``` + +It detects your React setup and opens a picker to install the skills for the AI +agent(s) you use. To pin a single agent — useful in CI or a Dockerfile — pass +`--ide`: + +```bash +npx @cometchat/skills add --ide claude # Claude Code → .claude/skills/ +npx @cometchat/skills add --ide cursor # Cursor → ./.cometchat/skills + router +npx @cometchat/skills add --ide replit # Replit Agent → .agents/skills/ +npx @cometchat/skills add --ide all # every supported agent +``` + +### Supported agents + +| Agent | Install with | +| --- | --- | +| Claude Code | `--ide claude` | +| Cursor | `--ide cursor` | +| GitHub Copilot | `--ide copilot` | +| Windsurf | `--ide windsurf` | +| Replit Agent | `--ide replit` | +| Cline | `--ide cline` | +| Codex | `--ide codex` | +| Gemini | `--ide gemini` | +| Continue | `--ide continue` | +| Aider | `--ide aider` | +| Kiro | `--ide kiro` | +| Antigravity | `--ide antigravity` | + + +Claude Code, Kiro, and Replit get a native `SKILL.md` tree. The other agents get +an orienting router plus a `./.cometchat/skills` tree. Add `--global` (Claude +Code, Kiro, and Replit only) to install into your user-level directory instead of +the project. + + +## Use it + +Open your project in your agent and prompt it: + +``` +add chat to my app +``` + +or type the dispatcher directly: + +``` +/cometchat +``` + +The `cometchat` dispatcher detects React and routes to `cometchat-onboarding`, +which walks a short **discover → understand → plan → approve** flow. Once you +approve the plan, it hands a scoped build directive to `cometchat-react-v7-core` +and pulls in the other skills as the plan needs them (components, placement, +theming, features, calls, push). + +Keep iterating in plain language afterward: + +- *"Add message reactions and threaded replies."* +- *"Switch the chat to dark mode and match my brand color."* +- *"Add a group details side panel."* +- *"Set up production authentication."* + +## Connect your credentials + +The skills can pull your **App ID / Region / Auth Key** from the CometChat +dashboard through the companion CLI, so you never paste them by hand: + +```bash +npx @cometchat/skills-cli auth login +npx @cometchat/skills-cli provision run +``` + +`provision run` fetches your credentials and writes a neutral +`.cometchat/config.json` that the skills read when they wire up init and login. +The CLI is dashboard/API-only — the skills do all framework detection, +env-file writing, and code generation. See the [CLI reference](/cli) for the +full command surface. + +## What's in the pack + +Eleven task-shaped skills the agent loads on demand: + +| Skill | Purpose | +| --- | --- | +| `cometchat` | Thin dispatcher — detect React and route | +| `cometchat-onboarding` | Discover → understand → plan → approve (the front door) | +| `cometchat-react-v7-core` | Install · credentials · init → login → render · the golden-path chat surface | +| `cometchat-react-v7-components` | The v7 component catalog + props / slots | +| `cometchat-react-v7-placement` | Where chat lives — full app / sidebar / popup / embed | +| `cometchat-react-v7-customization` | Theming · brand · light/dark · view slots | +| `cometchat-react-v7-patterns` | Vite / Next.js / React Router / Astro glue (env · SSR · routing) | +| `cometchat-react-v7-features` | Enable a feature — reactions · polls · AI · moderation · … | +| `cometchat-react-v7-calls` | Voice / video calling | +| `cometchat-react-v7-push` | Web push (Notifications product) | +| `cometchat-react-v7-migration` | Upgrade a v6 UI Kit → v7 | + +## Example prompts + +Once the skills are installed, try prompts like these in a fresh agent conversation: + +- *"Add a two-panel chat — conversation list on the left, messages on the right."* +- *"Put a Chats / Calls / Users tab bar in my React app."* +- *"Add voice and video calling with a click-to-call button."* +- *"Let project members talk in a group chat with file sharing."* +- *"Add presence indicators and typing dots to my conversation list."* +- *"Migrate my v6 UI Kit to v7."* + +The agent plans the change with you, then writes the integration into your +existing files. + +## Compatibility + +| Dependency | Version | +| --- | --- | +| `@cometchat/chat-uikit-react` | `7.x` (verified 7.1.x) | +| `@cometchat/chat-sdk-javascript` | `4.x` | +| `@cometchat/calls-sdk-javascript` | `5.x` (calling) | +| React | `≥ 18` | + +## Next steps + + + + Authenticate, provision credentials, and manage the skills from your terminal + + + Connect CometChat to any Model Context Protocol–compatible agent + + + The manual React UI Kit setup the skills automate + + + Browse all prebuilt UI components + + diff --git a/cli.mdx b/cli.mdx new file mode 100644 index 000000000..0888642a7 --- /dev/null +++ b/cli.mdx @@ -0,0 +1,174 @@ +--- +title: "CometChat CLI" +sidebarTitle: "CLI" +description: "Authenticate against the CometChat dashboard, provision app credentials, toggle features, and manage the AI agent skills — all from your terminal, with JSON output for scripting and CI." +canonical: "https://www.cometchat.com/docs/cli" +--- + +CometChat ships two complementary command-line tools: + +| CLI | Package | What it does | +| --- | --- | --- | +| **Credentials CLI** | `@cometchat/skills-cli` | Dashboard authentication + app-credential provisioning + feature toggles | +| **Skills CLI** | `@cometchat/skills` | Install, list, and verify the [AI Agent Skills](/agent-skills) | + + +Neither CLI writes framework code. The credentials CLI is a pure dashboard/API +client — it authenticates and hands your app credentials to the +[agent skills](/agent-skills), which own all framework detection, env-file +writing, and code generation. + + +Both run through `npx` with no global install, and every command accepts `--json` +for machine-readable output. + +--- + +## Credentials CLI — `@cometchat/skills-cli` + +Its only job is authenticating against the CometChat dashboard and fetching your +**App ID / Region / Auth Key**, then writing a neutral `.cometchat/config.json` +the skills build on. + +### Quick start + +```bash +# 1. Authenticate against the dashboard (opens your browser) +npx @cometchat/skills-cli auth login + +# 2. List the apps on your account +npx @cometchat/skills-cli provision list --json + +# 3. Pick or create an app, fetch creds, write .cometchat/config.json +npx @cometchat/skills-cli provision run + +# 4. Inspect the local config the skills read +npx @cometchat/skills-cli config show --json +``` + +### Authenticate + +```bash +npx @cometchat/skills-cli auth login +``` + +Opens your browser at the CometChat dashboard for device authentication and +stores the bearer token in your OS keychain (falling back to a `chmod 600` file). + +| Command | Purpose | +| --- | --- | +| `auth login` | Sign in via the dashboard (device auth) | +| `auth status` | Show whether you're signed in | +| `auth me` | Print the authenticated account | +| `auth logout` | Clear the stored token | +| `auth signup` | Create a CometChat account | + +### Provision credentials + +```bash +npx @cometchat/skills-cli provision run +``` + +Fetches your **App ID / Region / Auth Key**, prints them as JSON, and writes a +neutral `.cometchat/config.json`. It writes **no** framework env file — the skill +reads `config.json` and writes the framework-specific env (`.env` / `VITE_` / +`NEXT_PUBLIC_` …) itself. + +| Command | Purpose | +| --- | --- | +| `provision run` | Interactive: pick or create an app, fetch creds, write config | +| `provision list` | List the apps on your account | +| `provision create` | Create a new app | +| `provision use --app-id ` | Select a specific app by id | + +The config file `provision` writes: + +```json +{ + "version": 1, + "appId": "…", + "region": "us", + "authKey": "…", + "appName": "My Chat", + "plan": "…", + "industry": "…" +} +``` + +### Manage config + +Read and edit the local `.cometchat/config.json` (credential/app state only): + +| Command | Purpose | +| --- | --- | +| `config init` | Create an empty config | +| `config get ` | Read a single value | +| `config set ` | Write a single value | +| `config show` | Print the full config | +| `config path` | Print the config file location | + +### Toggle features + +Enable or disable app features from the terminal: + +| Command | Purpose | +| --- | --- | +| `features list` | List available features and their state | +| `features enable ` | Turn a feature on | +| `features disable ` | Turn a feature off | +| `features ai-key` | Manage the AI provider key | + +--- + +## Skills CLI — `@cometchat/skills` + +Installs and manages the [AI Agent Skills](/agent-skills) that let your coding +agent build with CometChat. + +```bash +npx @cometchat/skills add +``` + +| Command | Purpose | +| --- | --- | +| `detect` | Probe the current project (framework, UI Kit, version conflicts) | +| `add [--ide ]` | Install the skills for an AI agent (default: Claude Code) | +| `list` | List the skills this pack ships | +| `info ` | Show a skill's triggers + compatibility | +| `verify [tier]` | Run the skill quality gates | +| `catalog` | Refresh the component catalog from the installed UI Kit | +| `doctor` | Environment health check | + +See [Agent Skills](/agent-skills) for the install picker, supported agents, and +the prompt-driven workflow. + +--- + +## Scripting and CI + +Every command supports `--json`, and `add` can be pinned to one agent with +`--ide`, so the whole flow runs non-interactively: + +```bash +# Authenticate, select a known app, and install the skills for Claude Code +npx @cometchat/skills-cli auth login +npx @cometchat/skills-cli provision use --app-id "$COMETCHAT_APP_ID" --json +npx @cometchat/skills add --ide claude +``` + +## Next steps + + + + Install the skills and build CometChat from natural-language prompts + + + Connect CometChat to any Model Context Protocol–compatible agent + + + The manual React UI Kit setup, credentials and all + + + Open the CometChat dashboard + + diff --git a/docs.json b/docs.json index cb43da08b..af1d5ab9b 100644 --- a/docs.json +++ b/docs.json @@ -42,6 +42,13 @@ "product": "Home", "pages": [ "index", + { + "group": "Developer Tools", + "pages": [ + "agent-skills", + "cli" + ] + }, { "group": "Docs MCP", "hidden": true, From 00e320395d626b3104809c87bf7bf0ab1b59dd09 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 17 Aug 2026 16:21:42 +0530 Subject: [PATCH 12/63] Added CLI Docs --- docs.json | 30 +++++++++++++++--------------- index.mdx | 8 ++++++++ 2 files changed, 23 insertions(+), 15 deletions(-) diff --git a/docs.json b/docs.json index af1d5ab9b..5cb0ba072 100644 --- a/docs.json +++ b/docs.json @@ -41,27 +41,27 @@ { "product": "Home", "pages": [ - "index", - { - "group": "Developer Tools", - "pages": [ - "agent-skills", - "cli" - ] - }, - { - "group": "Docs MCP", - "hidden": true, - "pages": [ - "mcp-server" - ] - } + "index" ] }, { "product": "Home", "hidden": true, "tabs": [ + { + "tab": "Developer Tools", + "hidden": true, + "pages": [ + { + "group": "Developer Tools", + "pages": [ + "agent-skills", + "cli", + "mcp-server" + ] + } + ] + }, { "tab": "On-Premise Deployment", "hidden": true, diff --git a/index.mdx b/index.mdx index bdfa093c2..2ae62f464 100644 --- a/index.mdx +++ b/index.mdx @@ -141,6 +141,14 @@ canonical: "https://cometchat.com/docs" Add CometChat Docs MCP to your AI tools for instant documentation access. + + Let your AI coding agent add CometChat chat & calling to your React app. + + + + Authenticate, provision credentials, and manage the skills from your terminal. + + From bfda1f194284c7ca61f4b7f41ec32d3b2d4279e3 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 17 Aug 2026 16:39:14 +0530 Subject: [PATCH 13/63] Added CLI Docs --- agent-skills.mdx | 73 ++++++++++++++++++++++++++++++++++++++++-------- cli.mdx | 17 +++++++++++ 2 files changed, 78 insertions(+), 12 deletions(-) diff --git a/agent-skills.mdx b/agent-skills.mdx index db9ecb38f..3afdf18d0 100644 --- a/agent-skills.mdx +++ b/agent-skills.mdx @@ -21,6 +21,19 @@ don't scaffold a throwaway demo — they detect your setup and integrate CometCh into the app you're already building. +## Prerequisites + +- **Node.js 18+** — the installer runs through `npx`, so there's nothing to install globally. +- A **CometChat account** — [sign up free](https://app.cometchat.com) to get an app's App ID, Region, and Auth Key. +- An **existing React app** on React 18 or newer. Supported setups: **Vite**, **Create React App**, **Next.js**, **React Router**, and **Astro**. +- One of the [supported AI coding agents](#supported-agents) below. + + +The skills target the **React UI Kit v7** today. The installer tells you if it +can't detect a supported React setup — it never guesses or scaffolds a throwaway +project. + + ## Install Run the installer in your project root: @@ -93,19 +106,37 @@ Keep iterating in plain language afterward: ## Connect your credentials -The skills can pull your **App ID / Region / Auth Key** from the CometChat -dashboard through the companion CLI, so you never paste them by hand: - -```bash -npx @cometchat/skills-cli auth login -npx @cometchat/skills-cli provision run -``` +You don't paste your **App ID / Region / Auth Key** by hand. During the build, +when the skill notices they're missing, it offers two paths and defaults to +fetching them from your dashboard: + +- **Fetch from your dashboard (recommended)** — the skill **installs and runs the + CometChat CLI for you, on demand**. It opens the dashboard login in your + browser, lets you pick one of your **existing** apps, pulls the credentials, + and writes a neutral `.cometchat/config.json`. You don't install or run the CLI + yourself. +- **Paste manually** — copy App ID, Region, and Auth Key from **Dashboard → Your + App → Credentials** if you'd rather not log in. + +Either way, the **skill** then writes the framework env file (`.env` / `VITE_` / +`NEXT_PUBLIC_` …) from those credentials — the CLI only fetches them and never +touches your framework code. + + +**Keep credentials out of version control.** Both `.cometchat/config.json` and +the generated env file contain your **Auth Key**. Make sure they're in +`.gitignore` — Vite, CRA, and Astro ignore only `*.local` (not `.env`), so add +`.env` yourself; Next.js ignores `.env.local` by default. The Auth Key is for +**development only**: in production, mint a short-lived per-user **auth token** on +your backend and log in with `loginWithAuthToken()` — never ship the Auth Key to +a production client. + -`provision run` fetches your credentials and writes a neutral -`.cometchat/config.json` that the skills read when they wire up init and login. -The CLI is dashboard/API-only — the skills do all framework detection, -env-file writing, and code generation. See the [CLI reference](/cli) for the -full command surface. + +Prefer to drive it yourself? The credential CLI is also a standalone tool — +`npx @cometchat/skills-cli auth login`, then `provision run`. See the +[CLI reference](/cli) for the full command surface. + ## What's in the pack @@ -139,6 +170,24 @@ Once the skills are installed, try prompts like these in a fresh agent conversat The agent plans the change with you, then writes the integration into your existing files. +## Manage the skills + +- **Update** — re-run `npx @cometchat/skills add` to pull the latest skills; it overwrites the installed skill tree in place. +- **Inspect** — `npx @cometchat/skills list` shows the installed skills, and `npx @cometchat/skills doctor` runs an environment health check. +- **Uninstall** — delete the installed skill directory for your agent (for example `.claude/skills/cometchat*`, `.agents/skills/`, or `./.cometchat/skills`). +- **Version control** — commit the skill files so your whole team shares the same setup. Do **not** commit `.cometchat/config.json` or the generated env file — they hold your Auth Key. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +| --- | --- | --- | +| The agent doesn't pick up the skills | Installed for a different agent, or a router-based agent needs pointing at the tree | Re-run `npx @cometchat/skills add --ide `. For router agents (Cursor, Copilot, …) open `.cometchat/skills/cometchat/SKILL.md` to orient it. | +| Blank screen, no errors | A UI Kit component rendered before `init()` + `login()` resolved, or the wrong Region / env prefix | The `init → login → render` order is required. Check that the Region matches your dashboard app and the env prefix matches your bundler (`VITE_` / `NEXT_PUBLIC_` / `PUBLIC_`). | +| `login()` fails — "user not found" | Logging in a UID that doesn't exist in the app | Use a UID that exists (Dashboard → your app → **Users**; fresh apps seed `cometchat-uid-1`). | +| Auth error on init / login | Region mismatch between your code and the dashboard app | Re-check the Region (`us` / `eu` / `in`) in both the dashboard and your env file. | +| `ERROR_API_KEY_NOT_FOUND` | An env var is empty or not picked up by the bundler | Confirm the env file uses the right prefix for your bundler, then restart the dev server. | +| Version conflict during install | An older **v6** UI Kit is already installed | Ask the agent to migrate — the `cometchat-react-v7-migration` skill upgrades v6 → v7. | + ## Compatibility | Dependency | Version | diff --git a/cli.mdx b/cli.mdx index 0888642a7..c1bf3f938 100644 --- a/cli.mdx +++ b/cli.mdx @@ -22,6 +22,11 @@ writing, and code generation. Both run through `npx` with no global install, and every command accepts `--json` for machine-readable output. +## Prerequisites + +- **Node.js 18+** — both CLIs run through `npx`. +- A **CometChat account** — [sign up free](https://app.cometchat.com). `auth login` opens the dashboard in your browser to authenticate. + --- ## Credentials CLI — `@cometchat/skills-cli` @@ -95,6 +100,13 @@ The config file `provision` writes: } ``` + +`.cometchat/config.json` contains your **Auth Key** — add it to `.gitignore`. The +Auth Key is for **development only**; in production, mint a per-user **auth +token** on your backend and log in with `loginWithAuthToken()` instead of +shipping the Auth Key to a client. + + ### Manage config Read and edit the local `.cometchat/config.json` (credential/app state only): @@ -156,6 +168,11 @@ npx @cometchat/skills-cli provision use --app-id "$COMETCHAT_APP_ID" --json npx @cometchat/skills add --ide claude ``` +Commands **exit non-zero on failure** and surface dashboard errors verbatim (for +example `ACCESS_DENIED`, `EXPIRED`, `TIMEOUT`, `ABORTED`), so a broken auth or +provisioning step fails the CI job loudly instead of continuing with empty +credentials. + ## Next steps From 9b3c325adec40d687a6cad980bccea242d9a68f8 Mon Sep 17 00:00:00 2001 From: Shagun Date: Mon, 17 Aug 2026 18:46:16 +0530 Subject: [PATCH 14/63] docs(ui-kit/angular): add scoped Angular v5 LLM docs index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds ui-kit/angular/llms-angular-v5.mdx — a machine-readable, Angular-v5-scoped routing index of all 91 v5 pages as .md twins, for AI coding agents. Mirrors the shape of ui-kit/react/llms-react-v7.mdx (branch docs/react-v7-feature-guides). - Unlisted, NOT hidden: omitted from docs.json navigation so it never shows in the human sidebar, but still built, served as a .md twin, and indexed. Using `hidden: true` would auto-apply noindex and drop it from search + the global llms.txt, which defeats the purpose. docs.json is deliberately untouched. - Scoped to v5 only; the 2.0/, 3.0/ and v4/ trees are excluded so agents are never routed at dead API surfaces. - Angular-specific framing the React index has no equivalent for: kebab-case selectors, @Input() rather than props, content-projection/TemplateRef rather than render props, and env config in src/environments/environment.ts. Also fixes four content defects surfaced while building the index: - api-reference/formatter-config-service.mdx, api-reference/ rich-text-editor-service.mdx and guides/rich-text-formatting.mdx shipped with NO frontmatter at all despite being in docs.json navigation, so they rendered untitled. Adds title/description per house style (see api-reference/chat-state-service.mdx) and drops the two leading H1s that would now duplicate the frontmatter title. - overview.mdx "AI Integration Quick Reference" listed peer deps as @cometchat/chat-sdk-javascript + dompurify, missing @cometchat/cards-angular@^1.0.0 which @cometchat/chat-uikit-angular@5.1.0 added. Verified against the published package. NOT fixed here, needs an owner decision: the same accordion claims Angular "v18, v19, v20, v21, v22" but the published peer range at 5.1.0 is @angular/core ">=17.0.0 <22.0.0" — v22 is excluded (install hard-fails with ERESOLVE) and v17 is supported but undocumented. Either the docs or the peer range is wrong; that is a support-policy call, not a typo. Co-Authored-By: Claude Opus 5 --- .../formatter-config-service.mdx | 4 + .../rich-text-editor-service.mdx | 5 +- .../angular/guides/rich-text-formatting.mdx | 6 +- ui-kit/angular/llms-angular-v5.mdx | 156 ++++++++++++++++++ ui-kit/angular/overview.mdx | 2 +- 5 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 ui-kit/angular/llms-angular-v5.mdx diff --git a/ui-kit/angular/api-reference/formatter-config-service.mdx b/ui-kit/angular/api-reference/formatter-config-service.mdx index a2cdc3eb6..9c09c96ab 100644 --- a/ui-kit/angular/api-reference/formatter-config-service.mdx +++ b/ui-kit/angular/api-reference/formatter-config-service.mdx @@ -1,3 +1,7 @@ +--- +title: "Formatter Config Service" +description: "Service Reference for the centralized text-formatter configuration service in CometChat Angular UIKit" +--- The `FormatterConfigService` is a centralized Angular service for managing default text formatters across the CometChat UIKit. It provides a single source of truth for formatter configuration, allowing you to set formatters once and have them automatically applied across all text-displaying components. diff --git a/ui-kit/angular/api-reference/rich-text-editor-service.mdx b/ui-kit/angular/api-reference/rich-text-editor-service.mdx index ebcb49dc5..70b488a6f 100644 --- a/ui-kit/angular/api-reference/rich-text-editor-service.mdx +++ b/ui-kit/angular/api-reference/rich-text-editor-service.mdx @@ -1,4 +1,7 @@ -# RichTextEditorService API Reference +--- +title: "Rich Text Editor Service" +description: "Service Reference for the native-API rich text editor service in CometChat Angular UIKit" +--- The `RichTextEditorService` is an Angular service that provides rich text editing capabilities using native browser APIs. It is a lightweight, custom implementation with no external dependencies. diff --git a/ui-kit/angular/guides/rich-text-formatting.mdx b/ui-kit/angular/guides/rich-text-formatting.mdx index b81bd7ebc..016a50e1d 100644 --- a/ui-kit/angular/guides/rich-text-formatting.mdx +++ b/ui-kit/angular/guides/rich-text-formatting.mdx @@ -1,4 +1,8 @@ -# Rich Text Formatting Guide +--- +title: "Rich Text Formatting" +sidebarTitle: "Rich Text Formatting" +description: "Apply rich text formatting — bold, italic, links and mentions — in the CometChat Angular UIKit." +--- This guide explains how to use rich text formatting in the CometChat Angular V5 UIKit, including text formatting, mentions, links, and more. diff --git a/ui-kit/angular/llms-angular-v5.mdx b/ui-kit/angular/llms-angular-v5.mdx new file mode 100644 index 000000000..4be4c090f --- /dev/null +++ b/ui-kit/angular/llms-angular-v5.mdx @@ -0,0 +1,156 @@ +--- +title: "Angular UI Kit v5 — LLM docs index" +description: "Machine-readable, Angular-v5-scoped index of every UI Kit page as a clean .md twin. Built for AI coding agents; kept out of the human sidebar." +--- + +{/* + SCOPED LLM INDEX for the Angular v5 UI Kit. + - UNLISTED, NOT hidden: intentionally omitted from docs.json navigation so it never shows in + the human sidebar — but it IS built, served as a clean .md twin, and INDEXED for search + + AI assistants (so AI tools, and the skills pack via its docs-map, can discover and read it). + - We deliberately do NOT use `hidden: true`/`noindex` here: in Mintlify `hidden` auto-applies + noindex, which would drop this page from search AND the auto global llms.txt / AI context. + We want it discoverable, so it stays indexable. + - Scope is v5 ONLY. The 2.0/, 3.0/ and v4/ trees are deliberately excluded — linking them + would route agents at dead API surfaces. +*/} + +# Angular UI Kit v5 — LLM docs index (Latest) + +> Stateful, drop-in Angular chat/calling UI. Package `@cometchat/chat-uikit-angular@5` + +> `@cometchat/chat-sdk-javascript@4` (peers also include `@cometchat/cards-angular@^1` and +> `dompurify@^3`). This page is an **Angular-v5-only** routing index for AI agents — a scoped +> alternative to the site-wide `/docs/llms.txt`. + +## How to use this index +Each link points to the docs page; **append `.md`** to its URL to fetch the clean Markdown twin +(verbatim code + an "AI Integration Quick Reference" block with input/output names, types, and +defaults). Pick the page for the intent, then read the API there. +- Convention: any docs page URL + `.md` → raw Markdown. +- Fallback: if a `.md` twin 404s, fetch the same URL **without** `.md` (HTML). Never read a + package `.d.ts` and never answer inputs/outputs from memory. +- Angular specifics: components are used as kebab-case selectors in templates + (``), configured via `@Input()`, and customized through + content-projection slots / `TemplateRef` — not React-style render props. + +## Hot path — usually no fetch needed +For a plain "add chat" the install, `init → login → render` ordering, standalone/NgModule imports, +and the core drop-in inputs are stable; a well-built agent skill bakes them. Fetch below only for +exhaustive inputs, long-tail components, theming tokens, or feature enablement. +- Setup: [Integration](/ui-kit/angular/integration) · [Quickstart](/ui-kit/angular/quickstart) +- Environment config lives in `src/environments/environment.ts` (not `.env`). +- Core drop-ins: [Conversations](/ui-kit/angular/components/cometchat-conversations) · [Message Header](/ui-kit/angular/components/cometchat-message-header) · [Message List](/ui-kit/angular/components/cometchat-message-list) · [Message Composer](/ui-kit/angular/components/cometchat-message-composer) + +## Getting started / integration +- [Angular UI Kit](/ui-kit/angular/overview) +- [Quickstart](/ui-kit/angular/quickstart) +- [Integration](/ui-kit/angular/integration) + +## Core & configuration +- [Core Features](/ui-kit/angular/core-features) +- [Methods](/ui-kit/angular/methods) +- [Events](/ui-kit/angular/events) +- [Sound Manager](/ui-kit/angular/sound-manager) +- [Extensions](/ui-kit/angular/extensions) +- [Campaigns](/ui-kit/angular/campaigns) +- [Accessibility](/ui-kit/angular/accessibility) +- [Troubleshooting](/ui-kit/angular/troubleshooting) +- [Services](/ui-kit/angular/api-reference/introduction) +- [Chat State Service](/ui-kit/angular/api-reference/chat-state-service) +- [CometChat Templates Service](/ui-kit/angular/api-reference/templates-service) +- [Formatter Config Service](/ui-kit/angular/api-reference/formatter-config-service) +- [Message Bubble Config Service](/ui-kit/angular/api-reference/message-bubble-config-service) +- [Rich Text Editor Service](/ui-kit/angular/api-reference/rich-text-editor-service) +- [Search Conversations Service](/ui-kit/angular/api-reference/search-conversations-service) +- [Search Messages Service](/ui-kit/angular/api-reference/search-messages-service) + +## Theming & customization +- [Theming](/ui-kit/angular/customization/theming) +- [Global Configuration](/ui-kit/angular/customization/global-config) +- [Localization](/ui-kit/angular/customization/localization) +- [Date & Time Formatting](/ui-kit/angular/customization/date-time-formatting) +- [Message Bubble Styling](/ui-kit/angular/message-bubble-styling) + +## Components — conversations & lists +- [Overview](/ui-kit/angular/components/components-overview) +- [Conversations](/ui-kit/angular/components/cometchat-conversations) +- [Conversation Item](/ui-kit/angular/components/cometchat-conversation-item) +- [Users](/ui-kit/angular/components/cometchat-users) +- [User Item](/ui-kit/angular/components/cometchat-user-item) +- [Groups](/ui-kit/angular/components/cometchat-groups) +- [Group Item](/ui-kit/angular/components/cometchat-group-item) +- [Group Members](/ui-kit/angular/components/cometchat-group-members) +- [Group Member Item](/ui-kit/angular/components/cometchat-group-member-item) + +## Components — messages +- [Message List](/ui-kit/angular/components/cometchat-message-list) +- [Message Composer](/ui-kit/angular/components/cometchat-message-composer) +- [Message Header](/ui-kit/angular/components/cometchat-message-header) +- [Message Information](/ui-kit/angular/components/cometchat-message-information) +- [Thread Header](/ui-kit/angular/components/cometchat-thread-header) +- [Reactions](/ui-kit/angular/components/cometchat-reactions) +- [Reaction Info](/ui-kit/angular/components/cometchat-reaction-info) +- [Reaction List](/ui-kit/angular/components/cometchat-reaction-list) +- [Stickers Keyboard](/ui-kit/angular/components/cometchat-stickers-keyboard) + +## Components — message bubbles +- [Action Bubble](/ui-kit/angular/components/cometchat-action-bubble) +- [Audio Bubble](/ui-kit/angular/components/cometchat-audio-bubble) +- [Call Bubble](/ui-kit/angular/components/cometchat-call-bubble) +- [Card Bubble](/ui-kit/angular/components/cometchat-card-bubble) +- [Collaborative Document Bubble](/ui-kit/angular/components/cometchat-collaborative-document-bubble) +- [Collaborative Whiteboard Bubble](/ui-kit/angular/components/cometchat-collaborative-whiteboard-bubble) +- [Delete Bubble](/ui-kit/angular/components/cometchat-delete-bubble) +- [File Bubble](/ui-kit/angular/components/cometchat-file-bubble) +- [Image Bubble](/ui-kit/angular/components/cometchat-image-bubble) +- [CometChatMarkdownRenderer](/ui-kit/angular/components/cometchat-markdown-renderer) +- [Message Bubble](/ui-kit/angular/components/cometchat-message-bubble) +- [Poll Bubble](/ui-kit/angular/components/cometchat-poll-bubble) +- [Sticker Bubble](/ui-kit/angular/components/cometchat-sticker-bubble) +- [Text Bubble](/ui-kit/angular/components/cometchat-text-bubble) +- [Video Bubble](/ui-kit/angular/components/cometchat-video-bubble) + +## Components — calling +- [Call Features](/ui-kit/angular/call-features) +- [Call Buttons](/ui-kit/angular/components/cometchat-call-buttons) +- [Call Logs](/ui-kit/angular/components/cometchat-call-logs) +- [Incoming Call](/ui-kit/angular/components/cometchat-incoming-call) +- [Outgoing Call](/ui-kit/angular/components/cometchat-outgoing-call) + +## Components — search, AI & notifications +- [AI Smart Chat Features](/ui-kit/angular/ai-features) +- [CometChatSearch](/ui-kit/angular/components/cometchat-search) +- [CometChatAIAssistantChat](/ui-kit/angular/components/cometchat-ai-assistant-chat) +- [Smart Replies](/ui-kit/angular/components/cometchat-smart-replies) +- [Conversation Starter](/ui-kit/angular/components/cometchat-conversation-starter) +- [Conversation Summary](/ui-kit/angular/components/cometchat-conversation-summary) +- [Notification Feed](/ui-kit/angular/components/notification-feed) + +## Task guides (recipes) +- [Block/Unblock Users](/ui-kit/angular/guides/block-unblock-user) +- [Call Log Details](/ui-kit/angular/guides/call-log-details) +- [Card Messages](/ui-kit/angular/guides/card-messages) +- [Custom Message Types](/ui-kit/angular/guides/custom-message-types) +- [Custom Text Formatter](/ui-kit/angular/guides/custom-text-formatter) +- [Group Chat](/ui-kit/angular/guides/group-chat) +- [Hashtag Formatter](/ui-kit/angular/guides/hashtag-formatter) +- [Mentions Formatter](/ui-kit/angular/guides/mentions-formatter) +- [Message Privately](/ui-kit/angular/guides/message-privately) +- [New Chat](/ui-kit/angular/guides/new-chat) +- [Rich Text Formatting](/ui-kit/angular/guides/rich-text-formatting) +- [Search Messages](/ui-kit/angular/guides/search-messages) +- [ShortCut Formatter](/ui-kit/angular/guides/shortcut-formatter) +- [State Management](/ui-kit/angular/guides/state-management) +- [RxJS Subscription Patterns](/ui-kit/angular/guides/subscription-patterns) +- [Threaded Messages](/ui-kit/angular/guides/threaded-messages) +- [URL Formatter](/ui-kit/angular/guides/url-formatter) + +## Framework recipes (full-page layouts) +- [Conversation List + Message View](/ui-kit/angular/angular-conversation) +- [One-to-One / Group Chat](/ui-kit/angular/angular-one-to-one-chat) +- [Tab-Based Chat](/ui-kit/angular/angular-tab-based-chat) + +## Migration & misc +- [Guides](/ui-kit/angular/guides/guides-overview) +- [Upgrading From V4](/ui-kit/angular/customization/migration-guide) + diff --git a/ui-kit/angular/overview.mdx b/ui-kit/angular/overview.mdx index a363c55c2..ee0f4ebb8 100644 --- a/ui-kit/angular/overview.mdx +++ b/ui-kit/angular/overview.mdx @@ -9,7 +9,7 @@ description: "Use CometChat Angular UI Kit to add standalone chat components, vo | Field | Value | | --- | --- | | Package | `@cometchat/chat-uikit-angular` v5.x | -| Peer deps | `@cometchat/chat-sdk-javascript`, `dompurify` | +| Peer deps | `@cometchat/chat-sdk-javascript`, `@cometchat/cards-angular`, `dompurify` | | Calling | Optional — `@cometchat/calls-sdk-javascript` | | Angular | v18, v19, v20, v21, v22 (v22 requires Node.js 24+) | | Localization | 19 languages built-in | From f21c6afd7c61018ee89e34b4ae1d7c13a6ee1516 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 17 Aug 2026 20:36:26 +0530 Subject: [PATCH 15/63] Added CLI Docs --- agent-skills.mdx | 48 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/agent-skills.mdx b/agent-skills.mdx index 3afdf18d0..55100a1b2 100644 --- a/agent-skills.mdx +++ b/agent-skills.mdx @@ -158,17 +158,51 @@ Eleven task-shaped skills the agent loads on demand: ## Example prompts -Once the skills are installed, try prompts like these in a fresh agent conversation: +Everything starts from one prompt — **"add chat to my app"** — then you refine in +plain language. Example prompts, grouped by goal: + +**Get started** + +- *"Add chat to my app."* — the default: a conversation list + message view +- *"Add 1:1 direct messaging between my users."* +- *"Add group chat with file sharing."* +- *"Build a full chat app with Chats, Users, and Calls tabs."* + +**Where chat lives** + +- *"Add a support chat widget in the bottom-right corner."* +- *"Add a floating chat popup I can toggle open and closed."* +- *"Put chat in a sidebar next to my app."* +- *"Embed a chat panel on my dashboard page."* + +**Features** + +- *"Add message reactions, typing indicators, and read receipts."* +- *"Add threaded replies and @mentions."* +- *"Add image and file sharing."* +- *"Add message search."* +- *"Add polls and stickers."* + +**Calling & AI** -- *"Add a two-panel chat — conversation list on the left, messages on the right."* -- *"Put a Chats / Calls / Users tab bar in my React app."* - *"Add voice and video calling with a click-to-call button."* -- *"Let project members talk in a group chat with file sharing."* -- *"Add presence indicators and typing dots to my conversation list."* +- *"Add smart replies and conversation summaries."* +- *"Add an AI assistant to the chat."* +- *"Turn on moderation so banned words are blocked before delivery."* + +**Look & feel** + +- *"Switch the chat to dark mode and match my brand color."* +- *"Make the chat follow the user's system light/dark setting."* + +**Ship it** + +- *"Set up production authentication with auth tokens."* +- *"Add web push notifications."* - *"Migrate my v6 UI Kit to v7."* -The agent plans the change with you, then writes the integration into your -existing files. +The agent plans each change with you, then writes the integration into your +existing files — you don't have to know the component or prop names. ## Manage the skills From 501fa6f59a54b333352c310ea67f8dd145a1100e Mon Sep 17 00:00:00 2001 From: rajdubey Date: Tue, 18 Aug 2026 13:14:58 +0530 Subject: [PATCH 16/63] Added CLI Docs --- agent-skills.mdx | 8 ++++---- cli.mdx | 21 ++++++++++++--------- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/agent-skills.mdx b/agent-skills.mdx index 55100a1b2..b769cd5b1 100644 --- a/agent-skills.mdx +++ b/agent-skills.mdx @@ -110,11 +110,11 @@ You don't paste your **App ID / Region / Auth Key** by hand. During the build, when the skill notices they're missing, it offers two paths and defaults to fetching them from your dashboard: -- **Fetch from your dashboard (recommended)** — the skill **installs and runs the - CometChat CLI for you, on demand**. It opens the dashboard login in your +- **Fetch from your dashboard (recommended)** — the skill runs the standalone + [CometChat CLI](/cli) for you, on demand: it opens the dashboard login in your browser, lets you pick one of your **existing** apps, pulls the credentials, - and writes a neutral `.cometchat/config.json`. You don't install or run the CLI - yourself. + and writes a neutral `.cometchat/config.json`. You can also run the CLI yourself + — it works on its own, in a script, or in CI. - **Paste manually** — copy App ID, Region, and Auth Key from **Dashboard → Your App → Credentials** if you'd rather not log in. diff --git a/cli.mdx b/cli.mdx index c1bf3f938..81a578721 100644 --- a/cli.mdx +++ b/cli.mdx @@ -13,10 +13,13 @@ CometChat ships two complementary command-line tools: | **Skills CLI** | `@cometchat/skills` | Install, list, and verify the [AI Agent Skills](/agent-skills) | -Neither CLI writes framework code. The credentials CLI is a pure dashboard/API -client — it authenticates and hands your app credentials to the -[agent skills](/agent-skills), which own all framework detection, env-file -writing, and code generation. +The credentials CLI is **standalone** — use it on its own, in a script, or in CI. +It's a pure dashboard/API client: it authenticates, fetches your app credentials +(App ID / Region / Auth Key), and writes a neutral `.cometchat/config.json`. By +design it does **not** detect your framework, write env files, or generate code, +so it stays framework-agnostic and works with any stack. The +[agent skills](/agent-skills) are one consumer that can run it for you — but the +CLI doesn't require them. Both run through `npx` with no global install, and every command accepts `--json` @@ -33,7 +36,7 @@ for machine-readable output. Its only job is authenticating against the CometChat dashboard and fetching your **App ID / Region / Auth Key**, then writing a neutral `.cometchat/config.json` -the skills build on. +that any tool — your own scripts, a CI job, or the agent skills — can read. ### Quick start @@ -47,7 +50,7 @@ npx @cometchat/skills-cli provision list --json # 3. Pick or create an app, fetch creds, write .cometchat/config.json npx @cometchat/skills-cli provision run -# 4. Inspect the local config the skills read +# 4. Inspect the local config you just wrote npx @cometchat/skills-cli config show --json ``` @@ -75,9 +78,9 @@ npx @cometchat/skills-cli provision run ``` Fetches your **App ID / Region / Auth Key**, prints them as JSON, and writes a -neutral `.cometchat/config.json`. It writes **no** framework env file — the skill -reads `config.json` and writes the framework-specific env (`.env` / `VITE_` / -`NEXT_PUBLIC_` …) itself. +neutral `.cometchat/config.json`. It writes **no** framework env file — read +`config.json` and set your framework's env vars (`.env` / `VITE_` / +`NEXT_PUBLIC_` …) yourself, or let the agent skills do it. | Command | Purpose | | --- | --- | From 46bd5e398837c0892a2819e7740a640ebd63156c Mon Sep 17 00:00:00 2001 From: rajdubey Date: Tue, 18 Aug 2026 19:45:04 +0530 Subject: [PATCH 17/63] Added CLI Docs --- cli.mdx | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/cli.mdx b/cli.mdx index 81a578721..85f7d8c24 100644 --- a/cli.mdx +++ b/cli.mdx @@ -22,8 +22,9 @@ so it stays framework-agnostic and works with any stack. The CLI doesn't require them. -Both run through `npx` with no global install, and every command accepts `--json` -for machine-readable output. +Both run through `npx` with no global install, and most commands accept `--json` +for machine-readable output (the exceptions are `config set` and `config path`, +which print plain text). ## Prerequisites @@ -86,13 +87,21 @@ neutral `.cometchat/config.json`. It writes **no** framework env file — read | --- | --- | | `provision run` | Interactive: pick or create an app, fetch creds, write config | | `provision list` | List the apps on your account | -| `provision create` | Create a new app | +| `provision create --name ` | Create a new app (`--name` required) | | `provision use --app-id ` | Select a specific app by id | +Create a new app non-interactively — `--name` is required, `--region` and +`--industry` are optional: + +```bash +npx @cometchat/skills-cli provision create --name "My Chat" --region us +``` + The config file `provision` writes: ```json { + "$schema": "https://cometchat.com/schemas/config.json", "version": 1, "appId": "…", "region": "us", @@ -131,7 +140,14 @@ Enable or disable app features from the terminal: | `features list` | List available features and their state | | `features enable ` | Turn a feature on | | `features disable ` | Turn a feature off | -| `features ai-key` | Manage the AI provider key | +| `features ai-key ` | Set the app's OpenAI key that AI features need | + +Set the OpenAI key AI features require before they can run — the key is a +required argument: + +```bash +npx @cometchat/skills-cli features ai-key +``` --- @@ -161,7 +177,8 @@ the prompt-driven workflow. ## Scripting and CI -Every command supports `--json`, and `add` can be pinned to one agent with +Most commands support `--json` (the exceptions are `config set` and +`config path`, which print plain text), and `add` can be pinned to one agent with `--ide`, so the whole flow runs non-interactively: ```bash From 774afba3f64dc7f8a4378b0b890e5386ede2398a Mon Sep 17 00:00:00 2001 From: ashfaqcometchat Date: Tue, 18 Aug 2026 19:08:38 +0000 Subject: [PATCH 18/63] docs(android): update UI Kit v6 docs to 6.0.5 --- .../android/v6/ai-assistant-chat-history.mdx | 357 ++++ ui-kit/android/v6/ai-features.mdx | 59 + ui-kit/android/v6/architecture-data-flow.mdx | 521 +++++ ui-kit/android/v6/call-buttons.mdx | 304 +++ ui-kit/android/v6/call-features.mdx | 200 ++ ui-kit/android/v6/call-logs.mdx | 862 ++++++++ ui-kit/android/v6/calling-integration.mdx | 123 ++ ui-kit/android/v6/color-resources.mdx | 219 +++ ui-kit/android/v6/component-styling.mdx | 1731 +++++++++++++++++ ui-kit/android/v6/components-overview.mdx | 248 +++ .../android/v6/conversation-message-view.mdx | 446 +++++ ui-kit/android/v6/conversations.mdx | 952 +++++++++ ui-kit/android/v6/core-features.mdx | 244 +++ .../v6/custom-text-formatter-guide.mdx | 174 ++ ui-kit/android/v6/customization-events.mdx | 227 +++ .../android/v6/customization-menu-options.mdx | 182 ++ ui-kit/android/v6/customization-overview.mdx | 235 +++ .../android/v6/customization-state-views.mdx | 189 ++ ui-kit/android/v6/customization-styles.mdx | 231 +++ .../v6/customization-text-formatters.mdx | 176 ++ .../android/v6/customization-view-slots.mdx | 263 +++ .../v6/customization-viewmodel-data.mdx | 339 ++++ ui-kit/android/v6/events.mdx | 535 +++++ ui-kit/android/v6/extensions.mdx | 105 + ui-kit/android/v6/getting-started-jetpack.mdx | 257 +++ ui-kit/android/v6/getting-started-kotlin.mdx | 231 +++ ui-kit/android/v6/getting-started.mdx | 219 +++ ui-kit/android/v6/group-members.mdx | 966 +++++++++ ui-kit/android/v6/groups.mdx | 974 ++++++++++ ui-kit/android/v6/guide-ai-agent.mdx | 419 ++++ .../android/v6/guide-block-unblock-user.mdx | 277 +++ ui-kit/android/v6/guide-call-log-details.mdx | 291 +++ ui-kit/android/v6/guide-group-chat.mdx | 299 +++ ui-kit/android/v6/guide-message-privately.mdx | 218 +++ ui-kit/android/v6/guide-new-chat.mdx | 296 +++ ui-kit/android/v6/guide-overview.mdx | 67 + ui-kit/android/v6/guide-search-messages.mdx | 235 +++ ui-kit/android/v6/guide-threaded-messages.mdx | 294 +++ ui-kit/android/v6/incoming-call.mdx | 422 ++++ ui-kit/android/v6/link/changelog.mdx | 4 + ui-kit/android/v6/link/figma.mdx | 4 + ui-kit/android/v6/link/sample.mdx | 4 + ui-kit/android/v6/localize.mdx | 173 ++ .../android/v6/mentions-formatter-guide.mdx | 304 +++ ui-kit/android/v6/message-bubble-styling.mdx | 531 +++++ ui-kit/android/v6/message-composer.mdx | 475 +++++ ui-kit/android/v6/message-header.mdx | 450 +++++ ui-kit/android/v6/message-list.mdx | 1072 ++++++++++ ui-kit/android/v6/message-template.mdx | 636 ++++++ ui-kit/android/v6/methods.mdx | 432 ++++ ui-kit/android/v6/one-to-one-chat.mdx | 417 ++++ ui-kit/android/v6/outgoing-call.mdx | 374 ++++ ui-kit/android/v6/overview copy.mdx | 105 + ui-kit/android/v6/overview.mdx | 106 + ui-kit/android/v6/search.mdx | 1136 +++++++++++ .../android/v6/shortcut-formatter-guide.mdx | 158 ++ ui-kit/android/v6/sound-manager.mdx | 109 ++ ui-kit/android/v6/tab-based-chat.mdx | 502 +++++ ui-kit/android/v6/theme-introduction.mdx | 339 ++++ .../android/v6/threaded-messages-header.mdx | 224 +++ ui-kit/android/v6/troubleshooting.mdx | 171 ++ ui-kit/android/v6/upgrading-from-v5.mdx | 896 +++++++++ ui-kit/android/v6/users.mdx | 967 +++++++++ 63 files changed, 23976 insertions(+) create mode 100644 ui-kit/android/v6/ai-assistant-chat-history.mdx create mode 100644 ui-kit/android/v6/ai-features.mdx create mode 100644 ui-kit/android/v6/architecture-data-flow.mdx create mode 100644 ui-kit/android/v6/call-buttons.mdx create mode 100644 ui-kit/android/v6/call-features.mdx create mode 100644 ui-kit/android/v6/call-logs.mdx create mode 100644 ui-kit/android/v6/calling-integration.mdx create mode 100644 ui-kit/android/v6/color-resources.mdx create mode 100644 ui-kit/android/v6/component-styling.mdx create mode 100644 ui-kit/android/v6/components-overview.mdx create mode 100644 ui-kit/android/v6/conversation-message-view.mdx create mode 100644 ui-kit/android/v6/conversations.mdx create mode 100644 ui-kit/android/v6/core-features.mdx create mode 100644 ui-kit/android/v6/custom-text-formatter-guide.mdx create mode 100644 ui-kit/android/v6/customization-events.mdx create mode 100644 ui-kit/android/v6/customization-menu-options.mdx create mode 100644 ui-kit/android/v6/customization-overview.mdx create mode 100644 ui-kit/android/v6/customization-state-views.mdx create mode 100644 ui-kit/android/v6/customization-styles.mdx create mode 100644 ui-kit/android/v6/customization-text-formatters.mdx create mode 100644 ui-kit/android/v6/customization-view-slots.mdx create mode 100644 ui-kit/android/v6/customization-viewmodel-data.mdx create mode 100644 ui-kit/android/v6/events.mdx create mode 100644 ui-kit/android/v6/extensions.mdx create mode 100644 ui-kit/android/v6/getting-started-jetpack.mdx create mode 100644 ui-kit/android/v6/getting-started-kotlin.mdx create mode 100644 ui-kit/android/v6/getting-started.mdx create mode 100644 ui-kit/android/v6/group-members.mdx create mode 100644 ui-kit/android/v6/groups.mdx create mode 100644 ui-kit/android/v6/guide-ai-agent.mdx create mode 100644 ui-kit/android/v6/guide-block-unblock-user.mdx create mode 100644 ui-kit/android/v6/guide-call-log-details.mdx create mode 100644 ui-kit/android/v6/guide-group-chat.mdx create mode 100644 ui-kit/android/v6/guide-message-privately.mdx create mode 100644 ui-kit/android/v6/guide-new-chat.mdx create mode 100644 ui-kit/android/v6/guide-overview.mdx create mode 100644 ui-kit/android/v6/guide-search-messages.mdx create mode 100644 ui-kit/android/v6/guide-threaded-messages.mdx create mode 100644 ui-kit/android/v6/incoming-call.mdx create mode 100644 ui-kit/android/v6/link/changelog.mdx create mode 100644 ui-kit/android/v6/link/figma.mdx create mode 100644 ui-kit/android/v6/link/sample.mdx create mode 100644 ui-kit/android/v6/localize.mdx create mode 100644 ui-kit/android/v6/mentions-formatter-guide.mdx create mode 100644 ui-kit/android/v6/message-bubble-styling.mdx create mode 100644 ui-kit/android/v6/message-composer.mdx create mode 100644 ui-kit/android/v6/message-header.mdx create mode 100644 ui-kit/android/v6/message-list.mdx create mode 100644 ui-kit/android/v6/message-template.mdx create mode 100644 ui-kit/android/v6/methods.mdx create mode 100644 ui-kit/android/v6/one-to-one-chat.mdx create mode 100644 ui-kit/android/v6/outgoing-call.mdx create mode 100644 ui-kit/android/v6/overview copy.mdx create mode 100644 ui-kit/android/v6/overview.mdx create mode 100644 ui-kit/android/v6/search.mdx create mode 100644 ui-kit/android/v6/shortcut-formatter-guide.mdx create mode 100644 ui-kit/android/v6/sound-manager.mdx create mode 100644 ui-kit/android/v6/tab-based-chat.mdx create mode 100644 ui-kit/android/v6/theme-introduction.mdx create mode 100644 ui-kit/android/v6/threaded-messages-header.mdx create mode 100644 ui-kit/android/v6/troubleshooting.mdx create mode 100644 ui-kit/android/v6/upgrading-from-v5.mdx create mode 100644 ui-kit/android/v6/users.mdx diff --git a/ui-kit/android/v6/ai-assistant-chat-history.mdx b/ui-kit/android/v6/ai-assistant-chat-history.mdx new file mode 100644 index 000000000..00d8de003 --- /dev/null +++ b/ui-kit/android/v6/ai-assistant-chat-history.mdx @@ -0,0 +1,357 @@ +--- +title: "AI Assistant Chat History" +description: "Displays the conversation history between users and an AI assistant for easy review of past interactions." +--- + + +```json +{ + "component": "CometChatAIAssistantChatHistory", + "package": "com.cometchat.uikit.kotlin.presentation.aiassistantchathistory", + "xmlElement": "", + "description": "Displays the conversation history between users and an AI assistant for easy review of past interactions.", + "primaryOutput": { + "method": "setOnItemClickListener", + "type": "OnItemClickListener" + }, + "methods": { + "data": { + "setUser": { + "type": "User", + "required": true, + "note": "User must have role set to @agentic" + } + }, + "callbacks": { + "setOnItemClickListener": "OnItemClickListener", + "setOnItemLongClickListener": "OnItemLongClickListener", + "setOnNewChatClickListener": "OnClick", + "setOnCloseClickListener": "OnClick" + }, + "visibility": { + "setErrorStateVisibility": { "type": "int (View.VISIBLE | View.GONE)", "default": "View.VISIBLE" }, + "setEmptyStateVisibility": { "type": "int (View.VISIBLE | View.GONE)", "default": "View.VISIBLE" } + }, + "style": { + "setStyle": { + "type": "@StyleRes int", + "parent": "CometChatAIAssistantChatHistoryStyle" + } + } + }, + "events": [], + "sdkListeners": [] +} +``` + + + +## Quick Start + +1. Open your layout XML file. +2. Add the `CometChatAIAssistantChatHistory` XML element: + +```xml lines + +``` + +> **What this does:** Adds the `CometChatAIAssistantChatHistory` component to your layout. It fills the available width and height and renders the AI assistant chat history list. + +3. In your Activity or Fragment, create a `User` object with the role set to `@agentic` and pass it to the component: + + + + +```kotlin lines +val user = User() +user.uid = "userId" +user.name = "User Name" +user.role = "@agentic" // User role must be @agentic to use AI Assistant features + +binding.cometChatAiAssistantChatHistory.setUser(user) +``` + + + + +```kotlin lines +import com.cometchat.uikit.compose.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory + +@Composable +fun AIAssistantChatHistoryScreen() { + CometChatAIAssistantChatHistory( + modifier = Modifier.fillMaxSize(), + onCloseClick = { /* handle close */ }, + onNewChatClick = { /* handle new chat */ }, + onItemClick = { message -> /* handle item click */ } + ) +} +``` + + + + + +> **What this does:** Creates a `User` object with the `@agentic` role and sets it on the `CometChatAIAssistantChatHistory` component. This is required for the component to fetch and display the AI assistant chat histories for that user. + +4. Build and run your app. +5. Verify that the AI assistant chat history list appears with past conversation items. + + + + + +## Core Concepts + +- **`CometChatAIAssistantChatHistory`**: The main component class that renders the AI assistant chat history list. It is a Composite Component that can be launched via button clicks or any user-triggered action. +- **Actions**: Callbacks such as `setOnItemClickListener`, `setOnItemLongClickListener`, `setOnNewChatClickListener`, and `setOnCloseClickListener` that let you respond to user interactions. +- **Style**: XML theme styles applied via `setStyle()` to customize colors, fonts, and visual appearance of the chat history. +- **Functionality**: Methods like `setUser`, `setErrorStateVisibility`, and `setEmptyStateVisibility` that configure the component's behavior and state visibility. + +## Actions and Events + +### Callback Methods + +What you're changing: How the component responds to user interactions such as taps, long-presses, new chat clicks, and close clicks. + +- **Where**: Activity or Fragment where you hold a reference to `CometChatAIAssistantChatHistory`. +- **Applies to**: `CometChatAIAssistantChatHistory`. +- **Default behavior**: Predefined actions execute automatically when the user interacts with the component. +- **Override**: Call the corresponding setter method to replace the default behavior with your own logic. + +#### `setOnItemClickListener` + +Function invoked when a chat history item is clicked, used to open an AI assistant chat screen. + + + + +```kotlin YourActivity.kt lines +binding.cometchatAiAssistantChatHistory.setOnItemClickListener { view, position, message -> + + } +``` + + + +```kotlin lines +import com.cometchat.uikit.compose.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory + +CometChatAIAssistantChatHistory( + onItemClick = { message -> + Log.i(TAG, "Item clicked: ${message.id}") + } +) +``` + + + +> **What this does:** Replaces the default item-click behavior. When a user taps a chat history item, your custom lambda executes instead of the built-in navigation. + +#### `setOnItemLongClickListener` + +Function executed when a chat history item is long-pressed, allowing additional actions like delete or block. + + + + +```kotlin YourActivity.kt lines +binding.cometchatAiAssistantChatHistory.setOnItemLongClickListener { view, position, message -> + + } +``` + + + +```kotlin lines +CometChatAIAssistantChatHistory( + onItemLongClick = { message -> + Log.i(TAG, "Item long clicked: ${message.id}") + } +) +``` + + + +> **What this does:** Replaces the default long-press behavior. When a user long-presses a chat history item, your custom lambda executes. + +#### `setOnNewChatClickListener` + +Function triggered when the new chat button is clicked, used to start a new conversation with the AI assistant. + + + + +```kotlin YourActivity.kt lines +binding.cometchatAiAssistantChatHistory.setOnNewChatClickListener { + + } +``` + + + +```kotlin lines +CometChatAIAssistantChatHistory( + onNewChatClick = { + Log.i(TAG, "New chat clicked") + } +) +``` + + + +> **What this does:** Replaces the default new-chat-click behavior. When the user taps the new chat button, your custom logic runs instead of the built-in action. + +#### `setOnCloseClickListener` + +Function activated when the close button is clicked, used to exit the chat history view. + + + + +```kotlin YourActivity.kt lines +binding.cometchatAiAssistantChatHistory.setOnCloseClickListener { + + } +``` + + + +```kotlin lines +CometChatAIAssistantChatHistory( + onCloseClick = { + Log.i(TAG, "Close clicked") + } +) +``` + + + +> **What this does:** Replaces the default close-click behavior. When the user taps the close button, your custom logic runs instead of the built-in exit action. + +- **Verify**: After setting an action callback, trigger the corresponding user interaction (tap, long-press, new chat, close) and confirm your custom logic executes instead of the default behavior. + +## Styling + +What you're changing: The visual appearance of the AI Assistant Chat History component using XML theme styles. + +- **Where**: `themes.xml` for style definitions, and your Activity/Fragment for applying the style. +- **Applies to**: `CometChatAIAssistantChatHistory`. +- **Default behavior**: The component uses its default style. +- **Override**: Define a custom style in `themes.xml`, then call `setStyle()` on the component. + + + + + +- **Code**: + +```xml themes.xml lines + + + +``` + +> **What this does:** Defines a custom style `CustomAIAssistantChatHistoryStyle` that sets the background color to `#FFFAF6` for the component, header, new chat area, date separator, and items. It applies a Times New Roman font to the header, new chat text, date separator, and item text. A helper style `textStyleTimesNewRoman` defines the font family. + + + + +```kotlin lines +binding.cometchatAiAssistantChatHistory.setStyle(R.style.CustomAIAssistantChatHistoryStyle); +``` + + + +```kotlin lines +import com.cometchat.uikit.compose.presentation.aiassistantchathistory.style.CometChatAIAssistantChatHistoryStyle + +CometChatAIAssistantChatHistory( + style = CometChatAIAssistantChatHistoryStyle.default().copy( + chatHistoryBackgroundColor = Color(0xFFEDEAFA) + ) +) +``` + + + +> **What this does:** Applies the `CustomAIAssistantChatHistoryStyle` theme to the `CometChatAIAssistantChatHistory` component, changing the background colors and fonts. + +To know more such attributes, visit the [attributes file](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_assistant_chat_history.xml). + +- **Verify**: The chat history component displays with the `#FFFAF6` background color and Times New Roman font for header text, new chat text, date separator text, and item text. + +## Functionality + +What you're changing: Small functional customizations such as setting the user and toggling visibility of UI states. + +- **Where**: Activity or Fragment where you hold a reference to `CometChatAIAssistantChatHistory`. +- **Applies to**: `CometChatAIAssistantChatHistory`. +- **Default behavior**: All UI states are visible with default settings. +- **Override**: Call the corresponding method on the component instance. + +| Methods | Description | Code | +| --- | --- | --- | +| `setUser` | Sets the user whose chat histories with the AI assistant need to be fetched. This is a required property for the component to function. The user's role must be `@agentic`. | `.setUser(user);` | +| `setErrorStateVisibility` | Toggles the visibility of the error state of the component | `.setErrorStateVisibility(View.GONE);` | +| `setEmptyStateVisibility` | Toggles the visibility of the empty state of the component | `.setEmptyStateVisibility(View.GONE);` | + +- **Verify**: After calling `setUser(user)`, confirm the component fetches and displays the AI assistant chat histories for that user. After calling a visibility method, confirm the corresponding UI state is shown or hidden. + +## Customization Matrix + +| What you want to change | Where | Property/API | Example | +| --- | --- | --- | --- | +| Component background color | `themes.xml` | `cometChatAIAssistantChatHistoryBackgroundColor` | `#FFFAF6` | +| Header background color | `themes.xml` | `cometChatAIAssistantChatHistoryHeaderBackgroundColor` | `#FFFAF6` | +| Header text color | `themes.xml` | `cometChatAIAssistantChatHistoryHeaderTextColor` | `?attr/cometchatTextColorPrimary` | +| Header text appearance | `themes.xml` | `cometChatAIAssistantChatHistoryHeaderTextAppearance` | `@style/textStyleTimesNewRoman` | +| New chat background color | `themes.xml` | `cometChatAIAssistantChatHistoryNewChatBackgroundColor` | `#FFFAF6` | +| New chat text color | `themes.xml` | `cometChatAIAssistantChatHistoryNewChatTextColor` | `?attr/cometchatTextColorPrimary` | +| New chat text appearance | `themes.xml` | `cometChatAIAssistantChatHistoryNewChatTextAppearance` | `@style/textStyleTimesNewRoman` | +| Date separator text appearance | `themes.xml` | `cometChatAIAssistantChatHistoryDateSeparatorTextAppearance` | `@style/textStyleTimesNewRoman` | +| Date separator text color | `themes.xml` | `cometChatAIAssistantChatHistoryDateSeparatorTextColor` | `?attr/cometchatTextColorTertiary` | +| Date separator background color | `themes.xml` | `cometChatAIAssistantChatHistoryDateSeparatorBackgroundColor` | `#FFFAF6` | +| Item background color | `themes.xml` | `cometChatAIAssistantChatHistoryItemBackgroundColor` | `#FFFAF6` | +| Item text appearance | `themes.xml` | `cometChatAIAssistantChatHistoryItemTextAppearance` | `@style/textStyleTimesNewRoman` | +| Item text color | `themes.xml` | `cometChatAIAssistantChatHistoryItemTextColor` | `?attr/cometchatTextColorPrimary` | +| Apply a custom style | Activity/Fragment | `setStyle(int styleRes)` | `binding.cometchatAiAssistantChatHistory.setStyle(R.style.CustomAIAssistantChatHistoryStyle);` | +| Set the user for fetching history | Activity/Fragment | `setUser(User)` | `.setUser(user);` | +| Error state visibility | Activity/Fragment | `setErrorStateVisibility(int)` | `.setErrorStateVisibility(View.GONE);` | +| Empty state visibility | Activity/Fragment | `setEmptyStateVisibility(int)` | `.setEmptyStateVisibility(View.GONE);` | + +## Next Steps + + + + Display messages in a conversation + + + Browse recent conversations + + + Browse and search available users + + + Search across conversations and messages + + \ No newline at end of file diff --git a/ui-kit/android/v6/ai-features.mdx b/ui-kit/android/v6/ai-features.mdx new file mode 100644 index 000000000..d9e7c149a --- /dev/null +++ b/ui-kit/android/v6/ai-features.mdx @@ -0,0 +1,59 @@ +--- +title: "Smart Chat Features" +description: "Integrate AI-powered conversation starters, smart replies, and conversation summaries into your Android chat app." +--- + + + +| Field | Value | +| --- | --- | +| Packages | `com.cometchat:chatuikit-kotlin-android` (Java), `com.cometchat:chatuikit-kotlin-android` (Kotlin XML), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) | +| Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` + AI features enabled in [CometChat Dashboard](/fundamentals/ai-user-copilot/overview) | +| AI features | Conversation Starter, Smart Replies, Conversation Summary | +| Key components | [Message List](/ui-kit/android/v6/message-list) (Conversation Starter), [Message Composer](/ui-kit/android/v6/message-composer) (Smart Replies, Summary) | +| Activation | Enable each AI feature from the CometChat Dashboard — UI Kit auto-integrates them, no additional code required | +| Related | [Core Features](/ui-kit/android/v6/core-features), [Extensions](/ui-kit/android/v6/extensions), [AI Agent Guide](/ui-kit/android/v6/guide-ai-agent) | + + + +CometChat's AI capabilities greatly enhance user interaction and engagement in your application. Here's how the Android UI Kit integrates these features. + + + + + +## Conversation Starter + +When a user initiates a new chat, the UI kit displays a list of suggested opening lines that users can select, making it easier for them to start a conversation. These suggestions are powered by CometChat's AI, which predicts contextually relevant conversation starter options. + +For a comprehensive understanding and guide on implementing and using the Conversation Starter, refer to our specific guide on the [Conversation Starter](/fundamentals/ai-user-copilot/conversation-starter). + +Once you have successfully activated the [Conversation Starter](/fundamentals/ai-user-copilot/conversation-starter) from your CometChat Dashboard, the feature will automatically be incorporated into the [MessageList](/ui-kit/android/v6/message-list) Component of UI Kits. + + + + + +## Smart Replies + +Smart Replies are AI-generated responses to messages. They can predict what a user might want to say next by analyzing the context of the conversation. This allows for quicker and more convenient responses, especially on mobile devices. + +For a comprehensive understanding and guide on implementing and using the Smart Replies, refer to our specific guide on the [Smart Replies](/fundamentals/ai-user-copilot/smart-replies). + +Once you have successfully activated the [Smart Replies](/fundamentals/ai-user-copilot/smart-replies) from your CometChat Dashboard, the feature will automatically be incorporated into the Action sheet of [MessageComposer](/ui-kit/android/v6/message-composer) Component of UI Kits. + + + + + +## Conversation Summary + +The Conversation Summary feature provides concise summaries of long conversations, allowing users to catch up quickly on missed chats. This feature uses natural language processing to determine the main points in a conversation. + +For a comprehensive understanding and guide on implementing and using the Conversation Summary, refer to our specific guide on the [Conversation Summary](/fundamentals/ai-user-copilot/conversation-summary). + +Once you have successfully activated the [Conversation Summary](/fundamentals/ai-user-copilot/conversation-summary) from your CometChat Dashboard, the feature will automatically be incorporated into the Action sheet of [MessageComposer](/ui-kit/android/v6/message-composer) Component of UI Kits. + + + + diff --git a/ui-kit/android/v6/architecture-data-flow.mdx b/ui-kit/android/v6/architecture-data-flow.mdx new file mode 100644 index 000000000..dc8a3a4ad --- /dev/null +++ b/ui-kit/android/v6/architecture-data-flow.mdx @@ -0,0 +1,521 @@ +--- +title: "Architecture & Data Flow" +description: "How chatuikit-core, chatuikit-jetpack, and chatuikit-kotlin modules are structured using Clean Architecture." +--- + +The UI Kit is split into three modules that follow Clean Architecture principles. `chatuikit-core` holds all business logic, data access, and state management. The UI modules (`chatuikit-jetpack` and `chatuikit-kotlin`) provide platform-specific rendering on top of the shared core. + +## Module Structure + +```mermaid +graph TD + subgraph UI["UI Modules"] + A["chatuikit-jetpack
Jetpack Compose UI
Composables, Themes"] + B["chatuikit-kotlin
XML Views / ViewBinding
Custom Views, Adapters"] + end + + subgraph Core["chatuikit-core"] + D["domain/ — usecase, repository interfaces, models"] + E["data/ — datasource, repository implementations"] + F["viewmodel/ — shared ViewModels"] + G["state/ — sealed UIState classes"] + H["events/ — CometChatEvents SharedFlow bus"] + I["factory/ — ViewModel factories"] + J["formatter, mentions, resources, utils"] + end + + K["CometChat SDK
Chat SDK 4.x · Calls SDK 4.x"] + + A -->|depends on| Core + B -->|depends on| Core + Core -->|calls| K + +``` + +## 4-Layer Architecture + +Every feature follows the same layered flow: **View → ViewModel → Repository → DataSource**. + +```mermaid +block-beta + columns 1 + A["View / Composable\nchatuikit-kotlin or chatuikit-jetpack"] + B["ViewModel\nchatuikit-core"] + C["Repository\nchatuikit-core"] + D["DataSource\nchatuikit-core → CometChat SDK"] + + A --> B + B --> C + C --> D +``` + +The ViewModel lives in `chatuikit-core` and is shared by both UI modules. This means the same `CometChatConversationsViewModel` drives both the XML View and the Composable — only the rendering layer differs. + +## Clean Architecture Layers (chatuikit-core) + +### Data Layer + +The data layer wraps the CometChat SDK behind interfaces, making it swappable and testable. + +**DataSource** — defines the contract for raw SDK operations: + +```kotlin +// Interface (contract) +interface ConversationsDataSource { + suspend fun fetchConversations(request: ConversationsRequest): List + suspend fun deleteConversation(conversationWith: String, conversationType: String): String + suspend fun markAsDelivered(message: BaseMessage) +} + +// Implementation (calls CometChat SDK) +class ConversationsDataSourceImpl : ConversationsDataSource { + override suspend fun fetchConversations(request: ConversationsRequest): List { + // Wraps CometChat.fetchConversations() in a coroutine + } +} +``` + +Every feature has a DataSource pair: `ConversationsDataSource` / `ConversationsDataSourceImpl`, `UsersDataSource` / `UsersDataSourceImpl`, etc. + +**Repository Implementation** — coordinates data sources and handles error wrapping: + +```kotlin +class ConversationsRepositoryImpl( + private val dataSource: ConversationsDataSource +) : ConversationsRepository { + + private var hasMore = true + + override suspend fun getConversations( + request: ConversationsRequest + ): Result> { + return try { + val conversations = dataSource.fetchConversations(request) + hasMore = conversations.isNotEmpty() + Result.success(conversations) + } catch (e: CometChatException) { + Result.failure(e) + } + } +} +``` + +Repositories wrap raw SDK exceptions into Kotlin `Result` types, track pagination state, and coordinate between data sources. + +### Domain Layer + +The domain layer defines contracts and single-purpose use cases. It has no dependency on the SDK or Android framework. + +**Repository Interfaces** — contracts that the data layer implements: + +```kotlin +interface ConversationsRepository { + suspend fun getConversations(request: ConversationsRequest): Result> + suspend fun deleteConversation(conversationWith: String, conversationType: String): Result + suspend fun markAsDelivered(conversation: Conversation): Result + fun hasMoreConversations(): Boolean +} +``` + +**Use Cases** — encapsulate a single business action: + +```kotlin +open class GetConversationsUseCase( + private val repository: ConversationsRepository +) { + open suspend operator fun invoke( + request: ConversationsRequest + ): Result> { + return repository.getConversations(request) + } + + open fun hasMore(): Boolean = repository.hasMoreConversations() +} +``` + +Use cases are `open` so they can be overridden for testing or custom behavior. Each use case does one thing: + +| Use Case | Action | +|---|---| +| `GetConversationsUseCase` | Fetch paginated conversations | +| `DeleteConversationUseCase` | Delete a conversation | +| `RefreshConversationsUseCase` | Clear and re-fetch | +| `FetchUsersUseCase` / `SearchUsersUseCase` | Fetch or search users | +| `FetchGroupsUseCase` | Fetch groups | +| `FetchGroupMembersUseCase` / `SearchGroupMembersUseCase` | Fetch or search group members | +| `BanGroupMemberUseCase` / `KickGroupMemberUseCase` | Member moderation | +| `ChangeMemberScopeUseCase` | Change member role | +| `SendTextMessageUseCase` / `SendMediaMessageUseCase` / `SendCustomMessageUseCase` | Send messages | +| `EditMessageUseCase` | Edit a sent message | +| `FetchCallLogsUseCase` | Fetch call history | +| `InitiateCallUseCase` / `InitiateUserCallUseCase` / `StartGroupCallUseCase` | Start calls | +| `FetchReactionsUseCase` / `RemoveReactionUseCase` | Reaction management | +| `CreatePollUseCase` | Create a poll | +| `GetStickersUseCase` | Fetch sticker sets | +| `JoinGroupUseCase` / `GetGroupUseCase` / `GetUserUseCase` | Entity lookups | + +### ViewModel Layer + +ViewModels receive use cases via constructor injection and expose `StateFlow` / sealed `UIState` classes to the UI: + +```kotlin +class CometChatConversationsViewModel( + private val getConversationsUseCase: GetConversationsUseCase, + private val deleteConversationUseCase: DeleteConversationUseCase, + private val refreshConversationsUseCase: RefreshConversationsUseCase, + private val enableListeners: Boolean = true +) : ViewModel() { + + // UI observes this sealed state + private val _uiState = MutableStateFlow(UIState.Loading) + val uiState: StateFlow = _uiState + + fun fetchConversations() { + viewModelScope.launch { + getConversationsUseCase(request) + .onSuccess { conversations -> + _uiState.value = if (conversations.isEmpty()) UIState.Empty + else UIState.Content(conversations) + } + .onFailure { _uiState.value = UIState.Error(it) } + } + } +} +``` + +### State Management (StateFlow + Sealed Classes) + +Each feature has a dedicated sealed UIState class. All state is exposed via `StateFlow` — not LiveData: + +```kotlin +sealed class UIState { + object Loading : UIState() + object Empty : UIState() + data class Error(val exception: CometChatException) : UIState() + data class Content(val conversations: List) : UIState() +} +``` + +Feature-specific states include additional fields: + +| State Class | Feature | Extra Fields | +|---|---|---| +| `ConversationStarterUIState` | Conversation list | — | +| `MessageListUIState` | Message list | scroll position, reply state | +| `MessageComposerUIState` | Composer | attachment state, edit mode | +| `MessageHeaderUIState` | Header | typing indicator, user status | +| `GroupsUIState` | Groups | — | +| `UsersUIState` | Users | — | +| `GroupMembersUIState` | Group members | scope change state | +| `CallLogsUIState` | Call logs | — | +| `CallButtonsUIState` | Call buttons | call initiation state | +| `IncomingCallUIState` / `OutgoingCallUIState` / `OngoingCallUIState` | Calls | call session state | +| `ReactionListUIState` | Reactions | — | +| `CreatePollUIState` | Polls | form validation state | +| `StickerKeyboardUIState` | Stickers | sticker sets | + +### ListOperations Interface + +List-based ViewModels implement the `ListOperations` interface, which provides a standard contract for manipulating list data: + +```kotlin +interface ListOperations { + fun addAtIndex(index: Int, item: T) + fun updateAtIndex(index: Int, item: T) + fun removeAtIndex(index: Int) + fun moveToTop(item: T) +} +``` + +This ensures consistent list manipulation across Conversations, Users, Groups, Group Members, and Call Logs. + +## Dependency Injection via Factories + +ViewModels are created through `ViewModelProvider.Factory` classes that wire up the dependency chain: + +```kotlin +class CometChatConversationsViewModelFactory( + private val repository: ConversationsRepository = ConversationsRepositoryImpl( + ConversationsDataSourceImpl() + ), + private val enableListeners: Boolean = true +) : ViewModelProvider.Factory { + + override fun create(modelClass: Class): T { + val getUseCase = GetConversationsUseCase(repository) + val deleteUseCase = DeleteConversationUseCase(repository) + val refreshUseCase = RefreshConversationsUseCase(repository) + + return CometChatConversationsViewModel( + getConversationsUseCase = getUseCase, + deleteConversationUseCase = deleteUseCase, + refreshConversationsUseCase = refreshUseCase, + enableListeners = enableListeners + ) as T + } +} +``` + +Default implementations are provided, but you can inject custom repositories: + +```kotlin +// Custom repository for testing or caching +val factory = CometChatConversationsViewModelFactory( + repository = MyCustomConversationRepository(), + enableListeners = false // disable for previews +) +``` + +## Data Flow: End to End + +### Fetching Conversations + +```mermaid +graph TD + A["UI — Composable / View
collects uiState"] --> B["CometChatConversationsViewModel
calls getConversationsUseCase"] + B --> C["GetConversationsUseCase
calls repository.getConversations"] + C --> D["ConversationsRepositoryImpl
calls dataSource, wraps Result, tracks pagination"] + D --> E["ConversationsDataSourceImpl
calls CometChat SDK"] + E --> F["CometChat SDK → REST API → Response"] + +``` + +### Real-Time Updates + +```mermaid +graph TD + A["CometChat SDK — WebSocket
onTextMessageReceived / onTypingStarted"] --> B["ViewModel — SDK listener
processes event, updates internal list"] + B --> C["Emits new UIState.Content — updatedList"] + C --> D["UI recomposes / rebinds automatically"] + +``` + +### User Action (Delete Conversation) + +```mermaid +graph TD + A["UI — user swipes to delete"] --> B["ViewModel.deleteConversation"] + B --> C["DeleteConversationUseCase"] + C --> D["ConversationsRepositoryImpl"] + D --> E["DataSource → CometChat SDK → REST API → 200 OK"] + E --> F["ViewModel removes item → emits updated UIState"] + +``` + +## Component ↔ Core Mapping + +| UI Component | Core ViewModel | Use Cases | Repository | DataSource | +|---|---|---|---|---| +| Conversation List | `CometChatConversationsViewModel` | Get, Delete, Refresh | `ConversationsRepository` | `ConversationsDataSource` | +| Message List | `CometChatMessageListViewModel` | (message fetching) | `MessageListRepository` | `MessageListDataSource` | +| Message Composer | `CometChatMessageComposerViewModel` | SendText, SendMedia, SendCustom, Edit | `MessageComposerRepository` | `MessageComposerDataSource` | +| Message Header | `CometChatMessageHeaderViewModel` | — | `MessageHeaderRepository` | `MessageHeaderDataSource` | +| Users | `CometChatUsersViewModel` | FetchUsers, SearchUsers | `UsersRepository` | `UsersDataSource` | +| Groups | `CometChatGroupsViewModel` | FetchGroups, JoinGroup | `GroupsRepository` | `GroupsDataSource` | +| Group Members | `CometChatGroupMembersViewModel` | FetchMembers, Search, Ban, Kick, ChangeScope | `GroupMembersRepository` | `GroupMembersDataSource` | +| Call Logs | `CometChatCallLogsViewModel` | FetchCallLogs | `CallLogsRepository` | `CallLogsDataSource` | +| Call Buttons | `CometChatCallButtonsViewModel` | InitiateCall, StartGroupCall | `CallButtonsRepository` | `CallButtonsDataSource` | +| Reactions | `CometChatReactionListViewModel` | FetchReactions, RemoveReaction | `ReactionListRepository` | `ReactionListDataSource` | +| Message Info | `CometChatMessageInformationViewModel` | — | `MessageInformationRepository` | `MessageInformationDataSource` | + +## Events (Cross-Component Communication) + +The `CometChatEvents` singleton in `chatuikit-core` provides a typed event bus using Kotlin `SharedFlow` for communication between components that don't share a ViewModel: + +| Event Flow | Emitted When | +|---|---| +| `CometChatEvents.messageEvents` | Message sent, edited, deleted, reacted | +| `CometChatEvents.conversationEvents` | Conversation deleted | +| `CometChatEvents.groupEvents` | Group created, member added/removed/banned | +| `CometChatEvents.userEvents` | User blocked/unblocked | +| `CometChatEvents.callEvents` | Call initiated, accepted, rejected | +| `CometChatEvents.uiEvents` | UI-level events (show dialog, navigate) | + +See the [Events reference](/ui-kit/android/v6/events) for sealed class types and subscription examples. + +## Component-Level Overrides + +Every layer in the architecture is designed to be replaceable. You can override at the level that makes sense for your use case — from swapping the entire data source to just tweaking a single use case. + +### Override Points + +```mermaid +graph TD + A["UI Component"] --> B["ViewModel ← inject via custom Factory"] + B --> C["UseCase ← subclass (open classes)"] + C --> D["Repository ← implement interface"] + D --> E["DataSource ← implement interface"] +``` + +### 1. Custom Repository + +The most common override. Implement the repository interface and pass it to the factory. + +```kotlin +class OfflineUsersRepository : UsersRepository { + + private val cachedUsers = listOf(/* local data */) + + override suspend fun getUsers(request: UsersRequest): Result> { + return Result.success(cachedUsers) + } + + override fun hasMoreUsers(): Boolean = false +} +``` + +Wire it in: + + + +```kotlin +val factory = CometChatUsersViewModelFactory( + repository = OfflineUsersRepository(), + enableListeners = false +) +val viewModel = ViewModelProvider(this, factory)[CometChatUsersViewModel::class.java] + +val usersView = findViewById(R.id.users) +usersView.setViewModel(viewModel) +``` + + + +```kotlin +val factory = CometChatUsersViewModelFactory( + repository = OfflineUsersRepository(), + enableListeners = false +) +val viewModel: CometChatUsersViewModel = viewModel(factory = factory) + +CometChatUsers( + usersViewModel = viewModel +) +``` + + + +### 2. Custom DataSource + +Override at the lowest level to change how SDK calls are made — useful for caching, offline support, or wrapping a different backend. + +```kotlin +class CachedUsersDataSource( + private val sdkDataSource: UsersDataSourceImpl = UsersDataSourceImpl(), + private val cache: UserCache +) : UsersDataSource { + + override suspend fun fetchUsers(request: UsersRequest): List { + val cached = cache.get(request) + if (cached != null) return cached + + val users = sdkDataSource.fetchUsers(request) + cache.put(request, users) + return users + } +} +``` + +Then wrap it in the default repository implementation: + +```kotlin +val dataSource = CachedUsersDataSource(cache = myCache) +val repository = UsersRepositoryImpl(dataSource) +val factory = CometChatUsersViewModelFactory(repository = repository) +``` + +### 3. Custom Use Cases + +Use cases are `open` classes, so you can subclass them to add validation, logging, or transformation: + +```kotlin +class LoggingGetConversationsUseCase( + repository: ConversationsRepository +) : GetConversationsUseCase(repository) { + + override suspend operator fun invoke( + request: ConversationsRequest + ): Result> { + Log.d("Conversations", "Fetching conversations...") + val result = super.invoke(request) + result.onSuccess { Log.d("Conversations", "Fetched ${it.size} items") } + result.onFailure { Log.e("Conversations", "Fetch failed", it) } + return result + } +} +``` + +### 4. Passing a Custom ViewModel to the UI Component + +Both `chatuikit-jetpack` (Compose) and `chatuikit-kotlin` (XML Views) accept a pre-built ViewModel. This is the entry point for all overrides. + + + +```kotlin +class MyUsersActivity : AppCompatActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(R.layout.activity_users) + + val factory = CometChatUsersViewModelFactory( + repository = MyCustomUsersRepository() + ) + val viewModel = ViewModelProvider(this, factory)[CometChatUsersViewModel::class.java] + + val usersView = findViewById(R.id.users) + usersView.setViewModel(viewModel) + } +} +``` + + + +```kotlin +@Composable +fun MyUsersScreen() { + val factory = CometChatUsersViewModelFactory( + repository = MyCustomUsersRepository(), + enableListeners = true + ) + val viewModel: CometChatUsersViewModel = viewModel(factory = factory) + + CometChatUsers( + usersViewModel = viewModel, + style = CometChatUsersStyle.default(), + hideToolbar = false, + hideSearchBox = false + ) +} +``` + + + +### 5. Disabling Listeners for Previews and Testing + +Every factory accepts `enableListeners = false`. When disabled, the ViewModel won't register SDK listeners or UIKit event subscriptions — useful for Compose previews, unit tests, or showcase screens: + +```kotlin +val factory = CometChatConversationsViewModelFactory( + repository = FakeConversationRepository(), + enableListeners = false // No WebSocket listeners, no event subscriptions +) +``` + +### Override Summary by Component + +| Component | Factory Class | Repository Interface | Key Use Cases | +|---|---|---|---| +| Conversation List | `CometChatConversationsViewModelFactory` | `ConversationsRepository` | Get, Delete, Refresh | +| Users | `CometChatUsersViewModelFactory` | `UsersRepository` | FetchUsers, SearchUsers | +| Groups | `CometChatGroupsViewModelFactory` | `GroupsRepository` | FetchGroups, JoinGroup | +| Group Members | `CometChatGroupMembersViewModelFactory` | `GroupMembersRepository` | FetchMembers, Search, Ban, Kick, ChangeScope | +| Message List | `CometChatMessageListViewModelFactory` | `MessageListRepository` | (message fetching) | +| Message Composer | `CometChatMessageComposerViewModelFactory` | `MessageComposerRepository` | SendText, SendMedia, SendCustom, Edit | +| Call Logs | `CometChatCallLogsViewModelFactory` | `CallLogsRepository` | FetchCallLogs | +| Call Buttons | `CometChatCallButtonsViewModelFactory` | `CallButtonsRepository` | InitiateCall, StartGroupCall | +| Reactions | `CometChatReactionListViewModelFactory` | `ReactionListRepository` | FetchReactions, RemoveReaction | + +## Related + +- [Events](/ui-kit/android/v6/events) — Cross-component communication via `CometChatEvents` SharedFlow +- [Methods](/ui-kit/android/v6/methods) — UI Kit wrapper methods for init, auth, and messaging diff --git a/ui-kit/android/v6/call-buttons.mdx b/ui-kit/android/v6/call-buttons.mdx new file mode 100644 index 000000000..93d396843 --- /dev/null +++ b/ui-kit/android/v6/call-buttons.mdx @@ -0,0 +1,304 @@ +--- +title: "Call Buttons" +description: "Voice and video call buttons that initiate calls for a given user or group." +--- + +`CometChatCallButtons` renders voice and video call buttons and initiates calls for the bound `User` or `Group`. Place it in a `CometChatMessageHeader` or anywhere a call action is needed. + +--- + +## Where It Fits + +`CometChatCallButtons` is a utility component. Wire it into a `CometChatMessageHeader` or place it standalone wherever a call action is needed. + + + + +```xml activity_chat.xml lines + +``` + +```kotlin lines +val callButtons = findViewById(R.id.call_buttons) +callButtons.setUser(user) +``` + + + + +```kotlin lines +CometChatCallButtons( + user = user +) +``` + + + + +--- + +## Quick Start + + + + +Add to your layout XML: + +```xml lines + +``` + +Set a `User` or `Group` — required before calls can be initiated: + +```kotlin lines +override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(R.layout.your_layout) + + val callButtons = findViewById(R.id.call_buttons) + callButtons.setUser(user) + // or callButtons.setGroup(group) +} +``` + +Or programmatically: + +```kotlin lines +override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + val callButtons = CometChatCallButtons(this) + callButtons.setUser(user) + setContentView(callButtons) +} +``` + + + + +```kotlin lines +@Composable +fun CallButtonsScreen() { + CometChatCallButtons( + user = user + // or group = group + ) +} +``` + + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + +> You must call `setUser(User)` or `setGroup(Group)` before the buttons can initiate a call. Without a target, button clicks have no effect. + +--- + +## Actions and Events + +### Callback Methods + +#### `onVoiceCallClick` + +Fires when the voice call button is tapped. Replaces the default behavior of initiating an audio call. + + + + +```kotlin lines +callButtons.setOnVoiceCallClick { user, group -> + // Custom voice call logic +} +``` + + + + +```kotlin lines +CometChatCallButtons( + user = user, + onVoiceCallClick = { u, g -> + // Custom voice call logic + } +) +``` + + + + +#### `onVideoCallClick` + +Fires when the video call button is tapped. Replaces the default behavior of initiating a video call. + + + + +```kotlin lines +callButtons.setOnVideoCallClick { user, group -> + // Custom video call logic +} +``` + + + + +```kotlin lines +CometChatCallButtons( + user = user, + onVideoCallClick = { u, g -> + // Custom video call logic + } +) +``` + + + + +#### `onError` + +Fires on internal errors (network failure, auth issue, SDK exception). + + + + +```kotlin lines +callButtons.setOnError { exception -> + Log.e("CallButtons", "Error: ${exception.message}") +} +``` + + + + +```kotlin lines +CometChatCallButtons( + user = user, + onError = { exception -> + Log.e("CallButtons", "Error: ${exception.message}") + } +) +``` + + + + +### Global UI Events (CometChatCallEvents) + +| Event | Fires when | Payload | +| --- | --- | --- | +| `ccOutgoingCall` | An outgoing call is initiated | `Call` | +| `ccCallAccepted` | A call is accepted by the recipient | `Call` | +| `ccCallRejected` | A call is rejected by the recipient | `Call` | +| `ccCallEnded` | A call is ended | `Call` | + +--- + +## Functionality + +| Method (Kotlin XML) | Compose Parameter | Description | +| --- | --- | --- | +| `setUser(user)` | `user = user` | Set the user to call (required for 1-on-1) | +| `setGroup(group)` | `group = group` | Set the group to call (required for group calls) | +| `setOnVoiceCallClick { }` | `onVoiceCallClick = { }` | Override voice call button behavior | +| `setOnVideoCallClick { }` | `onVideoCallClick = { }` | Override video call button behavior | +| `setOnError { }` | `onError = { }` | Error callback | +| `setVoiceCallButtonVisibility(View.GONE)` | `hideVoiceCallButton = true` | Toggle voice call button | +| `setVideoCallButtonVisibility(View.GONE)` | `hideVideoCallButton = true` | Toggle video call button | + +--- + +## Style + + + + +Define a custom style in `themes.xml`: + +```xml themes.xml lines + +``` + +```kotlin lines +callButtons.setStyle(R.style.CustomCallButtonsStyle) +``` + + + + +```kotlin lines +CometChatCallButtons( + user = user, + style = CometChatCallButtonsStyle.default().copy( + voiceCallIconTint = Color(0xFF4CAF50), + videoCallIconTint = Color(0xFF2196F3), + voiceCallBackgroundColor = Color(0xFFE8F5E9), + videoCallBackgroundColor = Color(0xFFE3F2FD) + ) +) +``` + + + + +See [Component Styling](/ui-kit/android/v6/component-styling) for the full reference. + +--- + +## ViewModel + +```kotlin lines +val viewModel = ViewModelProvider(this) + .get(CometChatCallButtonsViewModel::class.java) +``` + + + + +```kotlin lines +callButtons.setViewModel(viewModel) +``` + + + + +```kotlin lines +CometChatCallButtons( + user = user, + callButtonsViewModel = viewModel +) +``` + + + + +See [ViewModel & Data](/ui-kit/android/v6/customization-viewmodel-data) for state observation and custom repositories. + +--- + +## Next Steps + + + + View call history + + + Incoming call notification with accept/reject + + + Outgoing call screen with end-call button + + + Display user/group info in the toolbar + + diff --git a/ui-kit/android/v6/call-features.mdx b/ui-kit/android/v6/call-features.mdx new file mode 100644 index 000000000..ad738b447 --- /dev/null +++ b/ui-kit/android/v6/call-features.mdx @@ -0,0 +1,200 @@ +--- +title: "Call" +description: "Add one-on-one and group audio/video calling to your Android app using the CometChat Calls SDK and UI Kit." +--- + + + +| Field | Value | +| --- | --- | +| Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` + `com.cometchat:calls-sdk-android` | +| Jetpack Compose | `com.cometchat:chatuikit-compose-android` + `com.cometchat:calls-sdk-android` | +| Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` — Calls SDK must also be installed | +| Call features | Incoming Call, Outgoing Call, Call Logs, Call Buttons, Ongoing Call | +| Key components | `CometChatCallButtons`, `CometChatIncomingCall`, `CometChatOutgoingCall`, `CometChatCallLogs`, `CometChatOngoingCall` | +| Auto-detection | UI Kit automatically detects the Calls SDK and enables call UI components | +| Related | [Getting Started](/ui-kit/android/v6/getting-started), [Core Features](/ui-kit/android/v6/core-features), [Call Log Details Guide](/ui-kit/android/v6/guide-call-log-details) | + + + +CometChat's Calls feature allows you to seamlessly integrate one-on-one as well as group audio and video calling capabilities into your application. This document provides a technical overview of these features, as implemented in the Android UI Kit. + +## Integration + +First, make sure that you've correctly integrated the UI Kit library into your project. If you haven't done this yet or are facing difficulties, refer to our [Getting Started](/ui-kit/android/v6/getting-started) guide. + +Once you've successfully integrated the UI Kit, the next step is to add the CometChat Calls SDK to your project. This is necessary to enable the calling features in the UI Kit. + +### Step 1: Add Calls SDK Dependency + +Add the following dependency to your `build.gradle.kts` file: + + + +```kotlin build.gradle.kts +dependencies { + implementation("com.cometchat:chatuikit-kotlin-android:6.0.0") + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + + + +```kotlin build.gradle.kts +dependencies { + implementation("com.cometchat:chatuikit-compose-android:6.0.0") + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + + + +After adding this dependency, sync your project. The Android UI Kit will automatically detect the Calls SDK and activate the calling features. + +### Step 2: Verify Call Buttons Appear + +Once the Calls SDK is integrated, you will see the `CometChatCallButtons` component automatically rendered in the [MessageHeader](/ui-kit/android/v6/message-header) component. This provides users with quick access to initiate audio and video calls. + + + + + +### Step 3: Add Call Listener for Incoming Calls + +To receive incoming calls globally in your app, you will need to add a `CallListener`. This should be added before you initialize the CometChat UI Kit. We recommend creating a custom Application class and adding the call listener there. + +When an incoming call is received, you can display the `CometChatIncomingCall` component using the current activity context. + + + +```kotlin +class BaseApplication : Application() { + + companion object { + private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}" + } + + override fun onCreate() { + super.onCreate() + + CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener { + override fun onIncomingCallReceived(call: Call) { + // Get the current activity context + val currentActivity = getCurrentActivity() // Implement this method + + currentActivity?.let { + // Create and display the incoming call component + val incomingCallView = CometChatIncomingCall(it) + incomingCallView.call = call + incomingCallView.fitsSystemWindows = true + incomingCallView.onError = OnError { exception -> + // Handle errors + } + + // Display the component (e.g., as dialog or snackbar) + } + } + + override fun onOutgoingCallAccepted(call: Call) { + // Handle outgoing call acceptance + } + + override fun onOutgoingCallRejected(call: Call) { + // Handle outgoing call rejection + } + + override fun onIncomingCallCancelled(call: Call) { + // Handle incoming call cancellation + } + }) + } +} +``` + + + +```kotlin +class BaseApplication : Application() { + + companion object { + private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}" + } + + override fun onCreate() { + super.onCreate() + + CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener { + override fun onIncomingCallReceived(call: Call) { + CometChatCallActivity.launchIncomingCallScreen(this@BaseApplication, call, null) + // Pass null or IncomingCallConfiguration if need to configure CometChatIncomingCall component + } + + override fun onOutgoingCallAccepted(call: Call) { + // Handle outgoing call acceptance + } + + override fun onOutgoingCallRejected(call: Call) { + // Handle outgoing call rejection + } + + override fun onIncomingCallCancelled(call: Call) { + // Handle incoming call cancellation + } + }) + } +} +``` + + + +## Call Components + +The CometChat Android UI Kit provides five main components for implementing calling features in your app. Each component handles a specific part of the calling experience. + +### Call Buttons + +The `CometChatCallButtons` component provides users with quick access to initiate audio and video calls. This component is automatically rendered in the [MessageHeader](/ui-kit/android/v6/message-header) when the Calls SDK is integrated. + + + + + +[Learn more about Call Buttons →](/ui-kit/android/v6/call-buttons) + +### Incoming Call + +The `CometChatIncomingCall` component displays when a user receives an incoming call. It provides a full-screen interface showing caller information and call controls. + + + + + +[Learn more about Incoming Call →](/ui-kit/android/v6/incoming-call) + +### Outgoing Call + +The `CometChatOutgoingCall` component manages the outgoing call experience. It displays while waiting for the recipient to answer and automatically transitions to the active call screen once accepted. + + + + + +[Learn more about Outgoing Call →](/ui-kit/android/v6/outgoing-call) + +### Call Logs + +The `CometChatCallLogs` component displays a history of all call activities, including missed, received, and dialed calls. Users can view call details and initiate new calls from the log. + + + + + +[Learn more about Call Logs →](/ui-kit/android/v6/call-logs) + +### Ongoing Call + +The `CometChatOngoingCall` component renders the active call screen with video feeds, mute/unmute controls, camera toggle, and end-call actions. + +### Call Log Details + +For detailed information about individual calls, including participants, join/leave history, and recordings, see the [Call Log Details](/ui-kit/android/v6/guide-call-log-details) guide. diff --git a/ui-kit/android/v6/call-logs.mdx b/ui-kit/android/v6/call-logs.mdx new file mode 100644 index 000000000..c15a0a8b2 --- /dev/null +++ b/ui-kit/android/v6/call-logs.mdx @@ -0,0 +1,862 @@ +--- +title: "Call Logs" +description: "Scrollable list of call logs for the logged-in user with caller names, avatars, call status, and timestamps." +--- + +`CometChatCallLogs` renders a scrollable list of call logs for the logged-in user with caller names, avatars, call status indicators, and timestamps. + + + + + +--- + +## Where It Fits + +`CometChatCallLogs` is a list component. It renders the user's call history and emits the selected `CallLog` via `onItemClick`. Use it as a standalone call history screen or as a tab in a tabbed layout alongside conversations and contacts. + + + + +```xml activity_call_logs.xml lines + +``` + +```kotlin lines +val callLogs = findViewById(R.id.call_logs) + +callLogs.setOnItemClick { callLog -> + // Navigate to call detail or initiate call +} +``` + + + + +```kotlin lines +CometChatCallLogs( + modifier = Modifier.fillMaxSize(), + onItemClick = { callLog -> + // Navigate to call detail or initiate call + } +) +``` + + + + +--- + +## Quick Start + + + + +Add to your layout XML: + +```xml lines + +``` + +Or programmatically: + +```kotlin lines +override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(CometChatCallLogs(this)) +} +``` + + + + +```kotlin lines +@Composable +fun CallLogsScreen() { + CometChatCallLogs( + modifier = Modifier.fillMaxSize() + ) +} +``` + + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, the UI Kit dependency added, and the CometChat Calls SDK configured. + +Or in a Fragment: + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + return CometChatCallLogs(requireContext()) +} +``` + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + return ComposeView(requireContext()).apply { + setContent { CometChatCallLogs() } + } +} +``` + + + + +--- + +## Filtering Call Logs + + + + +Pass a `CallLogRequest.CallLogRequestBuilder` to control what loads: + +```kotlin lines +callLogs.setCallLogRequestBuilder( + CallLogRequest.CallLogRequestBuilder() + .setLimit(20) + .setCallCategory(CometChatConstants.CALL_CATEGORY_CALL) +) +``` + + + + +```kotlin lines +CometChatCallLogs( + callLogRequestBuilder = CallLogRequest.CallLogRequestBuilder() + .setLimit(20) + .setCallCategory(CometChatConstants.CALL_CATEGORY_CALL) +) +``` + + + + +### Filter Recipes + +| Recipe | Builder method | +| --- | --- | +| Limit per page | `.setLimit(10)` | +| Audio calls only | `.setCallType(CometChatConstants.CALL_TYPE_AUDIO)` | +| Video calls only | `.setCallType(CometChatConstants.CALL_TYPE_VIDEO)` | +| Call category | `.setCallCategory(CometChatConstants.CALL_CATEGORY_CALL)` | + + +Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll. + + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemClick` + +Fires when a call log row is tapped. Primary navigation hook. + + + + +```kotlin lines +callLogs.setOnItemClick { callLog -> + // Navigate to call detail +} +``` + + + + +```kotlin lines +CometChatCallLogs( + onItemClick = { callLog -> + // Navigate to call detail + } +) +``` + + + + +> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation. + +#### `onItemLongClick` + +Fires when a call log row is long-pressed. + + + + +```kotlin lines +callLogs.setOnItemLongClick { callLog -> + // Show context menu +} +``` + + + + +```kotlin lines +CometChatCallLogs( + onItemLongClick = { callLog -> + // Show context menu + } +) +``` + + + + +#### `onBackPress` + +Fires when the user presses the back button in the toolbar. + + + + +```kotlin lines +callLogs.setOnBackPress { + finish() +} +``` + + + + +```kotlin lines +CometChatCallLogs( + onBackPress = { /* navigate back */ } +) +``` + + + + +#### `onError` + +Fires on internal errors (network failure, auth issue, SDK exception). + + + + +```kotlin lines +callLogs.setOnError { exception -> + Log.e("CallLogs", "Error: ${exception.message}") +} +``` + + + + +```kotlin lines +CometChatCallLogs( + onError = { exception -> + Log.e("CallLogs", "Error: ${exception.message}") + } +) +``` + + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + + +```kotlin lines +callLogs.setOnLoad { callLogList -> + Log.d("CallLogs", "Loaded ${callLogList.size}") +} +``` + + + + +```kotlin lines +CometChatCallLogs( + onLoad = { callLogList -> + Log.d("CallLogs", "Loaded ${callLogList.size}") + } +) +``` + + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + + +```kotlin lines +callLogs.setOnEmpty { + Log.d("CallLogs", "No call logs") +} +``` + + + + +```kotlin lines +CometChatCallLogs( + onEmpty = { /* no call logs */ } +) +``` + + + + +--- + +## Functionality + +| Method (Kotlin XML) | Compose Parameter | Description | +| --- | --- | --- | +| `setBackIconVisibility(View.VISIBLE)` | `hideBackIcon = false` | Toggle back button | +| `setToolbarVisibility(View.GONE)` | `hideToolbar = true` | Toggle toolbar | +| `setSeparatorVisibility(View.GONE)` | `hideSeparator = true` | Toggle list separators | +| `setTitle("Call History")` | `title = "Call History"` | Custom toolbar title | + +--- + +## Custom View Slots + +### Leading View + +Replace the avatar / left section. + + + + + + + + +```kotlin lines +callLogs.setLeadingView(object : CallLogsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return ImageView(context).apply { + layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp) + } + } + + override fun bindView( + context: Context, createdView: View, callLog: CallLog, + holder: RecyclerView.ViewHolder, callLogList: List, position: Int + ) { + val imageView = createdView as ImageView + // Load caller avatar + } +}) +``` + + + + +```kotlin lines +CometChatCallLogs( + leadingView = { callLog -> + CometChatAvatar( + imageUrl = callLog.initiator?.avatar, + name = callLog.initiator?.name + ) + } +) +``` + + + + +### Title View + +Replace the name / title text. + + + + + + + + +```kotlin lines +callLogs.setTitleView(object : CallLogsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, callLog: CallLog, + holder: RecyclerView.ViewHolder, callLogList: List, position: Int + ) { + (createdView as TextView).text = callLog.initiator?.name ?: "" + } +}) +``` + + + + +```kotlin lines +CometChatCallLogs( + titleView = { callLog -> + Text( + text = callLog.initiator?.name ?: "", + style = CometChatTheme.typography.heading4Medium + ) + } +) +``` + + + + +### Subtitle View + +Replace the subtitle text below the caller's name. + + + + + + + + +```kotlin lines +callLogs.setSubtitleView(object : CallLogsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END } + } + + override fun bindView( + context: Context, createdView: View, callLog: CallLog, + holder: RecyclerView.ViewHolder, callLogList: List, position: Int + ) { + (createdView as TextView).text = callLog.status ?: "Unknown" + } +}) +``` + + + + +```kotlin lines +CometChatCallLogs( + subtitleView = { callLog -> + Text( + text = callLog.status ?: "Unknown", + maxLines = 1, + overflow = TextOverflow.Ellipsis + ) + } +) +``` + + + + +### Trailing View + +Replace the right section of each call log item. + + + + + + + + +```kotlin lines +callLogs.setTrailingView(object : CallLogsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, callLog: CallLog, + holder: RecyclerView.ViewHolder, callLogList: List, position: Int + ) { + (createdView as TextView).text = SimpleDateFormat("h:mm a", Locale.getDefault()) + .format(Date(callLog.initiatedAt * 1000)) + } +}) +``` + + + + +```kotlin lines +CometChatCallLogs( + trailingView = { callLog -> + Text( + text = SimpleDateFormat("h:mm a", Locale.getDefault()) + .format(Date(callLog.initiatedAt * 1000)) + ) + } +) +``` + + + + +### Item View + +Replace the entire list item row. + + + + + + + + +```kotlin lines +callLogs.setItemView(object : CallLogsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return LayoutInflater.from(context).inflate(R.layout.custom_call_log_item, null) + } + + override fun bindView( + context: Context, createdView: View, callLog: CallLog, + holder: RecyclerView.ViewHolder, callLogList: List, position: Int + ) { + val avatar = createdView.findViewById(R.id.custom_avatar) + val title = createdView.findViewById(R.id.tvName) + title.text = callLog.initiator?.name + avatar.setAvatar(callLog.initiator?.name, callLog.initiator?.avatar) + } +}) +``` + + + + +```kotlin lines +CometChatCallLogs( + itemView = { callLog -> + Row( + modifier = Modifier.fillMaxWidth().padding(12.dp), + verticalAlignment = Alignment.CenterVertically + ) { + CometChatAvatar(imageUrl = callLog.initiator?.avatar, name = callLog.initiator?.name) + Spacer(Modifier.width(12.dp)) + Column(modifier = Modifier.weight(1f)) { + Text(callLog.initiator?.name ?: "", style = CometChatTheme.typography.heading4Medium) + Text(callLog.status ?: "", style = CometChatTheme.typography.body3Regular) + } + } + } +) +``` + + + + +### State Views + + + + +```kotlin lines +callLogs.setEmptyView(R.layout.custom_empty_view) +callLogs.setErrorView(R.layout.custom_error_view) +callLogs.setLoadingView(R.layout.custom_loading_view) +``` + + + + +```kotlin lines +CometChatCallLogs( + emptyView = { Text("No call logs") }, + errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } }, + loadingView = { CircularProgressIndicator() } +) +``` + + + + +### Overflow Menu + + + + +```kotlin lines +callLogs.setOverflowMenu(ImageButton(context).apply { + setImageResource(R.drawable.ic_filter) + setOnClickListener { /* show filter */ } +}) +``` + + + + +```kotlin lines +CometChatCallLogs( + overflowMenu = { + IconButton(onClick = { /* show filter */ }) { + Icon(painterResource(R.drawable.ic_filter), "Filter") + } + } +) +``` + + + + +--- + +## Menu Options + + + + +```kotlin lines +// Replace all options +callLogs.setOptions { context, callLog -> + listOf( + CometChatPopupMenu.MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ }), + CometChatPopupMenu.MenuItem(id = "callback", name = "Call Back", onClick = { /* ... */ }) + ) +} + +// Append to defaults +callLogs.setAddOptions { context, callLog -> + listOf( + CometChatPopupMenu.MenuItem(id = "info", name = "Info", onClick = { /* ... */ }) + ) +} +``` + + + + +```kotlin lines +CometChatCallLogs( + options = { context, callLog -> + listOf( + MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ }), + MenuItem(id = "callback", name = "Call Back", onClick = { /* ... */ }) + ) + }, + addOptions = { context, callLog -> + listOf(MenuItem(id = "info", name = "Info", onClick = { /* ... */ })) + } +) +``` + + + + +--- + +## Common Patterns + +### Minimal list — hide all chrome + + + + +```kotlin lines +callLogs.setToolbarVisibility(View.GONE) +callLogs.setSeparatorVisibility(View.GONE) +``` + + + + +```kotlin lines +CometChatCallLogs( + hideToolbar = true, + hideSeparator = true +) +``` + + + + +### Audio calls only + + + + +```kotlin lines +callLogs.setCallLogRequestBuilder( + CallLogRequest.CallLogRequestBuilder() + .setCallType(CometChatConstants.CALL_TYPE_AUDIO) +) +``` + + + + +```kotlin lines +CometChatCallLogs( + callLogRequestBuilder = CallLogRequest.CallLogRequestBuilder() + .setCallType(CometChatConstants.CALL_TYPE_AUDIO) +) +``` + + + + +### Video calls only + + + + +```kotlin lines +callLogs.setCallLogRequestBuilder( + CallLogRequest.CallLogRequestBuilder() + .setCallType(CometChatConstants.CALL_TYPE_VIDEO) +) +``` + + + + +```kotlin lines +CometChatCallLogs( + callLogRequestBuilder = CallLogRequest.CallLogRequestBuilder() + .setCallType(CometChatConstants.CALL_TYPE_VIDEO) +) +``` + + + + +--- + +## Advanced Methods + +### ViewModel Access + +```kotlin lines +val factory = CometChatCallLogsViewModelFactory() +val viewModel = ViewModelProvider(this, factory) + .get(CometChatCallLogsViewModel::class.java) +``` + + + + +```kotlin lines +callLogs.setViewModel(viewModel) +``` + + + + +```kotlin lines +CometChatCallLogs( + callLogsViewModel = viewModel +) +``` + + + + +See [ViewModel & Data](/ui-kit/android/v6/customization-viewmodel-data) for ListOperations, state observation, and custom repositories. + +--- + +## Style + + + + + + + + +Define a custom style in `themes.xml`: + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +CometChatCallLogs( + style = CometChatCallLogsStyle.default().copy( + backgroundColor = Color(0xFFF5F5F5), + titleTextColor = Color(0xFF141414), + itemStyle = CometChatCallLogsItemStyle.default().copy( + backgroundColor = Color.White, + titleTextColor = Color(0xFF141414), + subtitleTextColor = Color(0xFF727272), + avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp) + ) + ) +) +``` + + + + +### Style Properties + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background color | +| `titleTextColor` | Toolbar title color | +| `itemStyle.backgroundColor` | Row background | +| `itemStyle.titleTextColor` | Caller name color | +| `itemStyle.subtitleTextColor` | Call status text color | +| `itemStyle.separatorColor` | Row separator color | +| `itemStyle.avatarStyle` | Avatar appearance | + +See [Component Styling](/ui-kit/android/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + Voice and video calling overview + + + Browse recent conversations + + + Detailed styling reference with screenshots + + + Custom ViewModels, repositories, and ListOperations + + diff --git a/ui-kit/android/v6/calling-integration.mdx b/ui-kit/android/v6/calling-integration.mdx new file mode 100644 index 000000000..825f1692a --- /dev/null +++ b/ui-kit/android/v6/calling-integration.mdx @@ -0,0 +1,123 @@ +--- +title: "Calling Integration" +description: "Add voice and video calling to your Android UI Kit application using chatuikit-kotlin or chatuikit-jetpack." +--- + +## Overview + +This guide walks you through adding voice and video calling capabilities to your Android application using the CometChat UI Kit. + + +Make sure you've completed the [Getting Started](/ui-kit/android/v6/getting-started) guide before proceeding. + + +## Add the Calls SDK + +Add the CometChat Calls SDK dependency alongside your chosen UI Kit module: + + + +```kotlin build.gradle.kts +dependencies { + implementation("com.cometchat:chatuikit-kotlin-android:6.0.0") + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + + + +```kotlin build.gradle.kts +dependencies { + implementation("com.cometchat:chatuikit-compose-android:6.0.0") + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + + + +After adding this dependency, the Android UI Kit will automatically detect it and activate the calling features. You will see the `CometChatCallButtons` component rendered in the [MessageHeader](/ui-kit/android/v6/message-header) component. + + + + + +## Set Up Call Listener + +To receive incoming calls globally in your app, add a `CallListener` before initializing the CometChat UI Kit. We recommend creating a custom Application class: + + + +```kotlin +class BaseApplication : Application() { + companion object { + private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}" + } + + override fun onCreate() { + super.onCreate() + CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener { + override fun onIncomingCallReceived(call: Call) { + // Get the current activity context + val currentActivity = getCurrentActivity() // Implement this method + + currentActivity?.let { + val incomingCallView = CometChatIncomingCall(it) + incomingCallView.call = call + incomingCallView.fitsSystemWindows = true + incomingCallView.onError = OnError { exception -> + // Handle errors + } + + // Display the component (e.g., as dialog or full-screen overlay) + } + } + + override fun onOutgoingCallAccepted(call: Call) { + // Handle accepted outgoing call + } + + override fun onOutgoingCallRejected(call: Call) { + // Handle rejected outgoing call + } + + override fun onIncomingCallCancelled(call: Call) { + // Handle cancelled incoming call + } + }) + } +} +``` + + + +```kotlin +class BaseApplication : Application() { + companion object { + private val LISTENER_ID = "${BaseApplication::class.java.simpleName}${System.currentTimeMillis()}" + } + + override fun onCreate() { + super.onCreate() + CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener { + override fun onIncomingCallReceived(call: Call) { + CometChatCallActivity.launchIncomingCallScreen(this@BaseApplication, call, null) + // Pass null or IncomingCallConfiguration if need to configure CometChatIncomingCall component + } + + override fun onOutgoingCallAccepted(call: Call) { + // Handle accepted outgoing call + } + + override fun onOutgoingCallRejected(call: Call) { + // Handle rejected outgoing call + } + + override fun onIncomingCallCancelled(call: Call) { + // Handle cancelled incoming call + } + }) + } +} +``` + + diff --git a/ui-kit/android/v6/color-resources.mdx b/ui-kit/android/v6/color-resources.mdx new file mode 100644 index 000000000..89d9e8684 --- /dev/null +++ b/ui-kit/android/v6/color-resources.mdx @@ -0,0 +1,219 @@ +--- +title: "Color Resources" +description: "Review and override the default UI Kit color palette for consistent light and dark mode styling." +--- + + + +| Field | Value | +| --- | --- | +| Kotlin XML Views | Colors defined in `res/values/color.xml` (light) and `res/values-night/color.xml` (dark), overridable via theme attributes or `CometChatTheme.set*()` | +| Jetpack Compose | Colors provided via `lightColorScheme()` and `darkColorScheme()` factory functions, customizable via `.copy()` | +| Key tokens | `primary`, `backgroundColor1–4`, `textColorPrimary/Secondary/Tertiary`, `strokeColorDefault/Light/Dark`, `successColor`, `errorColor`, `warningColor`, `infoColor` | +| Related | [Theme Introduction](/ui-kit/android/v6/theme-introduction) · [Component Styling](/ui-kit/android/v6/component-styling) | + + + +The UI Kit ships with a complete color palette for light and dark modes. This page documents the default values and how to override them. + +--- + +## Color Categories + +The palette is organized into these groups: + +| Category | Tokens | Purpose | +| --- | --- | --- | +| Primary | `primary` | Brand color for buttons, highlights, interactive elements | +| Neutral | `neutral50` – `neutral900` | Grayscale ramp for backgrounds, text, borders | +| Alert | `success`, `error`, `warning`, `info`, `messageRead` | Status indicators | +| Background | `backgroundColor1` – `backgroundColor4` | Surface/panel backgrounds (derived from neutrals) | +| Stroke | `strokeColorDefault`, `strokeColorLight`, `strokeColorDark`, `strokeColorHighlight` | Borders and dividers | +| Text | `textColorPrimary`, `textColorSecondary`, `textColorTertiary`, `textColorDisabled`, `textColorWhite`, `textColorHighlight` | Typography colors | +| Icon | `iconTintPrimary`, `iconTintSecondary`, `iconTintTertiary`, `iconTintWhite`, `iconTintHighlight` | Icon tints | +| Button | `primaryButtonBackground`, `primaryButtonText`, `secondaryButtonBackground`, `secondaryButtonText` | Button colors | + +--- + +## Default Light Mode Palette + + + + +Defined in `chatuikit-kotlin/src/main/res/values/color.xml`: + +```xml color.xml lines + +#6852D6 + + +#FFFFFF +#FAFAFA +#F5F5F5 +#E8E8E8 +#DCDCDC +#A1A1A1 +#727272 +#5B5B5B +#434343 +#141414 + + +#0B7BEA +#09C26F +#FFAB00 +#F44649 +#56E8A7 +``` + + + + +Provided by `lightColorScheme()` in `CometChatColorScheme.kt`: + +```kotlin lines +import com.cometchat.uikit.compose.theme.lightColorScheme + +// Default light color scheme +val colors = lightColorScheme() + +// Key defaults: +// primary = Color(0xFF6852D6) +// neutralColor50 = Color(0xFFFFFFFF) +// neutralColor900 = Color(0xFF141414) +// successColor = Color(0xFF09C26F) +// errorColor = Color(0xFFF44649) +// warningColor = Color(0xFFFFAB00) +// infoColor = Color(0xFF0B7BEA) +``` + + + + +--- + +## Default Dark Mode Palette + + + + +Defined in `chatuikit-kotlin/src/main/res/values-night/color.xml`. Note how neutral values are inverted: + +```xml values-night/color.xml lines + +#6852D6 + + +#141414 +#1A1A1A +#272727 +#383838 +#4C4C4C +#858585 +#989898 +#A8A8A8 +#C8C8C8 +#FFFFFF + + +#0D66BF +#0B9F5D +#D08D04 +#C73C3E +#56E8A7 +``` + +Android automatically uses `values-night` resources when the system is in dark mode. + + + + +Provided by `darkColorScheme()`: + +```kotlin lines +import com.cometchat.uikit.compose.theme.darkColorScheme + +// Default dark color scheme +val colors = darkColorScheme() + +// Key defaults (neutrals inverted): +// primary = Color(0xFF6852D6) +// neutralColor50 = Color(0xFF141414) +// neutralColor900 = Color(0xFFFFFFFF) +// successColor = Color(0xFF0B9F5D) +// errorColor = Color(0xFFC73C3E) +``` + + + + +--- + +## Override Colors + + + + +Override via XML theme attributes in `themes.xml`: + +```xml themes.xml lines + +``` + +Or programmatically via `CometChatTheme`: + +```kotlin lines +CometChatTheme.setPrimaryColor(Color.parseColor("#F76808")) +CometChatTheme.setBackgroundColor1(Color.parseColor("#FFFFFF")) +CometChatTheme.setTextColorPrimary(Color.parseColor("#000000")) +CometChatTheme.setStrokeColorDefault(Color.parseColor("#E0E0E0")) +``` + + + + +Customize via `.copy()` on the factory functions: + +```kotlin lines +val customColors = lightColorScheme().copy( + primary = Color(0xFFF76808), + backgroundColor1 = Color(0xFFFFFFFF), + textColorPrimary = Color(0xFF000000), + strokeColorDefault = Color(0xFFE0E0E0) +) + +CometChatTheme(colorScheme = customColors) { + // Your content +} +``` + + + + + + + + +--- + +## Derived Colors + +Background, stroke, text, and icon colors are derived from the neutral scale by default: + +| Token | Light Mode Default | Dark Mode Default | +| --- | --- | --- | +| `backgroundColor1` | `neutral50` (#FFFFFF) | `neutral50` (#141414) | +| `backgroundColor2` | `neutral100` (#FAFAFA) | `neutral100` (#1A1A1A) | +| `textColorPrimary` | `neutral900` (#141414) | `neutral900` (#FFFFFF) | +| `textColorSecondary` | `neutral600` (#727272) | `neutral600` (#989898) | +| `strokeColorDefault` | `neutral200` (#F5F5F5) | `neutral200` (#272727) | +| `strokeColorLight` | `neutral300` (#E8E8E8) | `neutral300` (#383838) | +| `iconTintPrimary` | `neutral900` (#141414) | `neutral900` (#FFFFFF) | +| `iconTintHighlight` | `primary` (#6852D6) | `primary` (#6852D6) | + +This means overriding a neutral color automatically updates all tokens that reference it. diff --git a/ui-kit/android/v6/component-styling.mdx b/ui-kit/android/v6/component-styling.mdx new file mode 100644 index 000000000..d1313cc3b --- /dev/null +++ b/ui-kit/android/v6/component-styling.mdx @@ -0,0 +1,1731 @@ +--- +title: "Component Styling" +description: "Style CometChat UI Kit components using XML theme attributes or Compose style data classes." +--- + + + +| Field | Value | +| --- | --- | +| Kotlin XML Views | Override XML styles in `themes.xml` extending component parent styles (e.g., `CometChatConversationsStyle`), assign via theme attributes | +| Jetpack Compose | Pass style data classes as parameters (e.g., `CometChatConversationsStyle`, `CometChatMessageListStyle`) with `.default()` and `.copy()` | +| Pattern (XML) | Create custom style → extend parent → assign to `AppTheme` via theme attribute | +| Pattern (Compose) | Call `ComponentStyle.default().copy(property = value)` → pass as `style` parameter | +| Related | [Theme Introduction](/ui-kit/android/v6/theme-introduction) · [Color Resources](/ui-kit/android/v6/color-resources) · [Message Bubble Styling](/ui-kit/android/v6/message-bubble-styling) | + + + +This page shows how to style CometChat UI Kit components in Android. It is written for Android developers customizing UI Kit v6. + +## When to use this + +- You want UI Kit screens (lists, headers, and message UI) to match your brand colors and typography. +- You need to customize calling and AI UI components without rebuilding UI from scratch. +- You prefer centralized styling through `res/values/themes.xml` (XML Views) or style data classes (Compose). +- You want consistent iconography by supplying your own vector drawables. +- You need a repeatable pattern that can be applied across components. + +## Prerequisites + +- CometChat Android UI Kit v6 installed in your app. +- Your app theme extends `CometChatTheme.DayNight` (for XML Views). +- You can edit `res/values/themes.xml` in your Android module. +- You can add drawable resources to `res/drawable/` when needed. +- You rebuild or sync Gradle after updating styles. + +## Styling Pattern + + + + +Components read styles from XML theme attributes. The pattern is: + +1. Open `res/values/themes.xml`. +2. Create a custom style that extends the component's parent style (for example, `CometChatConversationsStyle`). +3. Assign your custom style to `AppTheme` using the component's theme attribute (for example, `cometchatConversationsStyle`). +4. Sync Gradle and rebuild the app. +5. Navigate to the screen that uses the component and confirm the visual change. + +```xml themes.xml lines + + + + + +``` + +You can also set fonts globally: + +```xml themes.xml lines + +``` + + + + +Components accept a `style` parameter — a data class with `.default()` factory and `.copy()` for overrides: + +```kotlin lines +CometChatConversations( + style = CometChatConversationsStyle.default().copy( + backgroundColor = Color(0xFFFFF9F5), + titleTextColor = Color(0xFFF76808) + ) +) +``` + +Nested styles (e.g., avatar inside conversations) are overridden the same way: + +```kotlin lines +CometChatConversations( + style = CometChatConversationsStyle.default().copy( + avatarStyle = CometChatAvatarStyle.default().copy( + backgroundColor = Color(0xFFFBAA75), + cornerRadius = 8.dp + ) + ) +) +``` + + + + +## Core concepts + +- `AppTheme` is the single place where UI Kit style hooks are wired (XML Views). +- Each UI Kit component has a parent style (for example, `CometChatMessageListStyle`) and a theme attribute (for example, `cometchatMessageListStyle`). +- Custom styles must extend the correct parent style to inherit default behavior. +- Drawable overrides (for example, custom icons) live in `res/drawable/` and are referenced from styles. +- Fonts can be set once at the theme level and reused across components. + +--- + +## Implementation + +Use the following sections to style each component. Each section lists what changes, where to change it, the exact code to paste, and how to verify the result. + +### Chat Lists & Messaging + +#### Conversations + +The `CometChatConversations` component renders the recent chats list. + + + + + +What you're changing: avatar and badge styling in the conversation list. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatConversations` +- **Default behavior**: UI Kit default avatar and badge styles. +- **Override**: set `cometchatConversationsStyle` in `AppTheme` or pass a style object. + + + + + +```xml themes.xml lines + + + + + + + + + +``` + + + + +```kotlin lines +CometChatConversations( + style = CometChatConversationsStyle.default().copy( + avatarStyle = CometChatAvatarStyle.default().copy( + backgroundColor = Color(0xFFFBAA75), + cornerRadius = 8.dp + ), + badgeStyle = CometChatBadgeStyle.default().copy( + backgroundColor = Color(0xFFF76808), + textColor = Color.White + ) + ) +) +``` + + + + +- **What this does**: applies custom avatar and badge styles to conversation list items. +- **Verify**: the Conversations list shows updated avatar backgrounds and badge colors. + +Attribute references: +- [Conversations attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_conversations.xml) +- [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml) +- [Badge attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_badge.xml) + +#### Users + +The `CometChatUsers` component renders a list of users for selection or navigation. + + + + + +What you're changing: user list avatar and separator styling. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatUsers` +- **Default behavior**: UI Kit default avatar and list styling. +- **Override**: set `cometchatUsersStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + +``` + + + + +```kotlin lines +CometChatUsers( + style = CometChatUsersStyle.default().copy( + separatorColor = Color(0xFFF76808), + titleTextColor = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: applies avatar and separator color overrides to the user list. +- **Verify**: the Users list shows updated avatar backgrounds and separator color. + +Attribute references: +- [Users attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_users.xml) +- [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml) + +#### Groups + +The `CometChatGroups` component renders group items and their summary data. + + + + + +What you're changing: group list avatar and typography colors. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatGroups` +- **Default behavior**: UI Kit default group item styling. +- **Override**: set `cometchatGroupsStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + +``` + + + + +```kotlin lines +CometChatGroups( + style = CometChatGroupsStyle.default().copy( + separatorColor = Color(0xFFF76808), + titleTextColor = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: styles group avatars and separators in the Groups list. +- **Verify**: the Groups list shows the updated avatar background and title color. + +Attribute references: +- [Groups attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_groups.xml) +- [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml) + +#### Message Header + +The `CometChatMessageHeader` component renders the title, avatar, and action icons for a chat. + + + + + +What you're changing: title text color, avatar styling, and call button icons. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatMessageHeader` +- **Default behavior**: UI Kit default header typography and icons. +- **Override**: set `cometchatMessageHeaderStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + + + +``` + + + + +```kotlin lines +CometChatMessageHeader( + style = CometChatMessageHeaderStyle.default().copy( + titleTextColor = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: applies custom title color, avatar styling, and call button tints in the message header. +- **Verify**: open a conversation and check the header text and call button icons. + +Attribute references: +- [Message Header attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_header.xml) +- [Call Buttons attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_call_buttons.xml) + +#### Message List + +The `CometChatMessageList` component renders conversation messages and their bubble styles. + + + + + +What you're changing: message list background and outgoing bubble styling. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatMessageList` +- **Default behavior**: UI Kit default message list background and bubble colors. +- **Override**: set `cometchatMessageListStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + +``` + + + + +```kotlin lines +CometChatMessageList( + style = CometChatMessageListStyle.default().copy( + backgroundColor = Color(0xFFFEEDE1), + outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy( + backgroundColor = Color(0xFFF76808) + ) + ) +) +``` + + + + +- **What this does**: changes the message list background and outgoing bubble color. +- **Verify**: open a conversation and check outgoing message bubble colors. + +Attribute references: +- [Message List attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_list.xml) +- [Message Bubble attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_bubble.xml) + +#### Message Composer + +The `CometChatMessageComposer` component renders the input box and action buttons. + + + + + +What you're changing: send button icon and composer icon tints. + +- **Where to change it**: `res/drawable/active_send_button.xml` and `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatMessageComposer` +- **Default behavior**: UI Kit default composer icons and send button drawable. +- **Override**: set `cometchatMessageComposerStyle` in `AppTheme` or pass a style object. + + + + +```xml res/drawable/active_send_button.xml lines + + + + + + + +``` + +```xml res/values/themes.xml lines + + + + + +``` + + + + +```kotlin lines +CometChatMessageComposer( + style = CometChatMessageComposerStyle.default().copy( + attachmentIconTint = Color(0xFFF76808), + voiceRecordingIconTint = Color(0xFFF76808), + aiIconTint = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: applies custom icon tints and the active send button drawable to the composer. +- **Verify**: the composer shows the custom send button and tinted icons. + +Attribute references: +- [Message Composer attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_composer.xml) + +#### Group Members + +The `CometChatGroupMembers` component lists users inside a group. + + + + + +What you're changing: group member list avatars, separators, and back icon tint. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatGroupMembers` +- **Default behavior**: UI Kit default list styling. +- **Override**: set `cometchatGroupMembersStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + +``` + + + + +```kotlin lines +CometChatGroupMembers( + style = CometChatGroupMembersStyle.default().copy( + separatorColor = Color(0xFFF76808), + titleTextColor = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: applies custom avatar and separator styling to the group members list. +- **Verify**: the group members screen shows updated avatar and separator colors. + +Attribute references: +- [Group Members attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_group_members.xml) +- [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml) + +#### Thread Header + +The `CometChatThreadHeader` component renders the parent message preview in threaded views. + + + + + +What you're changing: thread header bubble colors and reply count styling. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatThreadHeader` +- **Default behavior**: UI Kit default thread header styling. +- **Override**: set `cometchatThreadHeaderStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + + + +``` + + + + +```kotlin lines +CometChatThreadHeader( + style = CometChatThreadHeaderStyle.default().copy( + backgroundColor = Color(0xFFFEEDE1), + replyCountTextColor = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: customizes thread header bubble colors and reply count styling. +- **Verify**: open a thread and confirm the header background and reply count colors. + +Attribute references: +- [Thread Header attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_thread_header.xml) +- [Message Bubble attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_bubble.xml) + +#### Mentions + +The `CometChatMentions` styling controls how user mentions appear inside messages. + + + + + +What you're changing: mention text and background styles for incoming and outgoing bubbles. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatMentions` +- **Default behavior**: UI Kit default mention styling. +- **Override**: set `cometchatMessageBubbleMentionsStyle` in both incoming and outgoing bubble styles. + + + + +```xml themes.xml lines + + + + + + + + + + + +``` + + + + +```kotlin lines +CometChatMessageList( + style = CometChatMessageListStyle.default().copy( + incomingMessageBubbleStyle = CometChatIncomingMessageBubbleStyle.default().copy( + mentionTextColor = Color(0xFFD6409F) + ), + outgoingMessageBubbleStyle = CometChatOutgoingMessageBubbleStyle.default().copy( + mentionTextColor = Color.White + ) + ) +) +``` + + + + +- **What this does**: customizes mention colors for incoming and outgoing message bubbles. +- **Verify**: send a mention in a chat and check the mention highlight colors. + +Attribute references: +- [Mentions attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_mentions.xml) +- [Message Bubble attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_message_bubble.xml) + +#### Search + +The `CometChatSearch` component provides cross-conversation and message search UI. + + + + + +What you're changing: search background and typography styles. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatSearch` + +- **Default behavior**: UI Kit default search colors and text appearance. + +- **Override**: set `cometchatSearchStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + + + +``` + +- **What this does**: applies custom search colors and text styles across search UI sections. + +- **Verify**: open Search and check section headers, chips, and list items. + +Attribute references: +- [Search attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_search.xml) + + +#### Message Information + +The `CometChatMessageInformation` component displays message metadata such as delivery and read status. + + + + + +What you're changing: message information styling for metadata views. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatMessageInformation` + +- **Default behavior**: UI Kit default metadata styling. + +- **Override**: set `cometchatMessageInformationStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: wires a custom Message Information style so you can override specific metadata attributes. + +- **Verify**: open Message Information and confirm your overrides apply. + +Attribute references: +- [Message Information attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_message_information.xml) + + +#### Message Option Sheet + +The `CometChatMessageOptionSheet` component is the action menu for message-level actions. + + + + + +What you're changing: option sheet background and icon tint. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatMessageOptionSheet` + +- **Default behavior**: UI Kit default option sheet styling. + +- **Override**: set `cometchatPopupMenuStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: updates message option sheet icon tint and background color. + +- **Verify**: long-press a message and confirm the option sheet styling. + +Attribute references: +- [Message Option Sheet attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_message_option_sheet.xml) + + +#### Attachment Option Sheet + +The `CometChatAttachmentOptionSheet` component renders the attachment picker. + + + + + +What you're changing: attachment option sheet background and icon tint. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatAttachmentOptionSheet` + +- **Default behavior**: UI Kit default attachment sheet styling. + +- **Override**: set `cometchatAttachmentOptionSheetStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: applies custom colors to the attachment picker sheet. + +- **Verify**: open the attachment menu and confirm background and icons. + +Attribute references: +- [Attachment Option Sheet attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_attachment_option_sheet.xml) + + +--- + +### Calling UI + +#### Call Logs + +The `CometChatCallLogs` component renders recent call history. + + + + + +What you're changing: call log list separators and title colors. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatCallLogs` +- **Default behavior**: UI Kit default call log styling. +- **Override**: set `cometchatCallLogsStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + +``` + + + + +```kotlin lines +CometChatCallLogs( + style = CometChatCallLogsStyle.default().copy( + separatorColor = Color(0xFFF76808), + titleTextColor = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: applies custom avatar and text colors to the call logs list. +- **Verify**: open Call Logs and confirm the separator and title colors. + +Attribute references: +- [Call Logs attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_call_logs.xml) + +#### Incoming Call + +The `CometChatIncomingCall` component renders the incoming call UI. + + + + + +What you're changing: incoming call background, buttons, and avatar styling. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatIncomingCall` +- **Default behavior**: UI Kit default incoming call layout and colors. +- **Override**: set `cometchatIncomingCallStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +CometChatIncomingCall( + call = call, + style = CometChatIncomingCallStyle.default().copy( + backgroundColor = Color(0xFFAA9EE8) + ) +) +``` + + + + +- **What this does**: customizes the incoming call screen background and action buttons. +- **Verify**: trigger an incoming call and confirm the background and button colors. + +Attribute references: +- [Incoming Call attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_incoming_call.xml) +- [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml) + +#### Outgoing Call + +The `CometChatOutgoingCall` component renders the outgoing call UI. + + + + + +What you're changing: outgoing call avatar styling. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatOutgoingCall` +- **Default behavior**: UI Kit default outgoing call styling. +- **Override**: set `cometchatOutgoingCallStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + + + +``` + + + + +```kotlin lines +CometChatOutgoingCall( + call = call, + style = CometChatOutgoingCallStyle.default().copy( + avatarStyle = CometChatAvatarStyle.default().copy( + backgroundColor = Color(0xFFFBAA75) + ) + ) +) +``` + + + + +- **What this does**: applies a custom avatar style to the outgoing call screen. +- **Verify**: place a call and confirm the avatar styling. + +Attribute references: +- [Outgoing Call attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_outgoing_call.xml) +- [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml) + +#### Call Buttons + +The `CometChatCallButton` component renders voice and video call buttons. + + + + + +What you're changing: button background, stroke, and icon tint. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatCallButtons` + +- **Default behavior**: UI Kit default call button styling. + +- **Override**: set `cometchatCallButtonsStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: customizes call button padding, background, and icon colors. + +- **Verify**: open a chat header and confirm button styling. + +Attribute references: +- [Call Buttons attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_call_buttons.xml) + + +--- + +### AI UI +#### AI Assistant Chat History + +The `CometChatAIAssistantChatHistory` component renders the AI conversation history view. + + + + + +What you're changing: background, header, and list typography. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatAIAssistantChatHistory` + +- **Default behavior**: UI Kit default AI history styling. + +- **Override**: set `cometChatAIAssistantChatHistoryStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + + + +``` + +- **What this does**: applies custom colors and font styling to the AI Assistant history screen. + +- **Verify**: open AI Assistant history and confirm background and header styling. + +Attribute references: +- [AI Assistant Chat History attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_assistant_chat_history.xml) + +#### AI Option Sheet + +The `CometChatAIOptionSheet` component renders AI action options. + + + + + +What you're changing: AI option sheet background and icon tint. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatAIOptionSheet` + +- **Default behavior**: UI Kit default AI option sheet styling. + +- **Override**: set `cometchatAIOptionSheetStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: customizes AI option sheet colors. + +- **Verify**: open AI actions and confirm the option sheet styling. + +Attribute references: +- [AI Option Sheet attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_option_sheet.xml) + +#### Conversation Starter + +The `CometChatConversationStarter` component renders AI-powered conversation starters. + + + + + +What you're changing: conversation starter item backgrounds. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatConversationStarter` + +- **Default behavior**: UI Kit default conversation starter styling. + +- **Override**: set `cometchatAIConversationStarterStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: applies a custom background color to AI conversation starter items. + +- **Verify**: open a new chat and confirm the conversation starter chip color. + +Attribute references: +- [AI Conversation Starter attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_conversation_starter.xml) + +#### Conversation Summary + +The `CometChatConversationSummary` component renders AI-generated summaries of chats. + + + + + +What you're changing: conversation summary background color. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatConversationSummary` + +- **Default behavior**: UI Kit default conversation summary styling. + +- **Override**: set `cometchatAIConversationSummaryStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: applies a custom background color to conversation summary cards. + +- **Verify**: open a chat summary and confirm the background color. + +Attribute references: +- [AI Conversation Summary attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_conversation_summary.xml) + +#### Smart Replies + +The `CometChatSmartReplies` component renders AI-generated reply suggestions. + + + + + +What you're changing: smart reply background, item color, and stroke. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatSmartReplies` + +- **Default behavior**: UI Kit default smart replies styling. + +- **Override**: set `cometchatAISmartRepliesStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: customizes smart reply container and chip styling. + +- **Verify**: open a conversation with smart replies enabled and confirm chip styling. + +Attribute references: +- [AI Smart Replies attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_ai_smart_replies.xml) + + +--- + +### Base Components + +#### Avatar + +The `CometChatAvatar` component is used across lists and headers. + + + + + +What you're changing: avatar shape and background color. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatAvatar` +- **Default behavior**: UI Kit default avatar styling. +- **Override**: set `cometchatAvatarStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +// Globally via CometChatConversations, CometChatUsers, etc. +style = ComponentStyle.default().copy( + avatarStyle = CometChatAvatarStyle.default().copy( + backgroundColor = Color(0xFFFBAA75), + cornerRadius = 8.dp + ) +) +``` + + + + +- **What this does**: applies a consistent avatar style across UI Kit components. +- **Verify**: open any list with avatars and confirm the style. + +Attribute references: +- [Avatar attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_avatar.xml) + +#### Badge + +The `CometChatBadge` component shows unread or notification counts. + + + + + +What you're changing: badge background, text color, and corner radius. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatBadge` +- **Default behavior**: UI Kit default badge styling. +- **Override**: set `cometchatBadgeStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +// Via parent component style +style = CometChatConversationsStyle.default().copy( + badgeStyle = CometChatBadgeStyle.default().copy( + backgroundColor = Color(0xFFF44649), + textColor = Color.White, + cornerRadius = 4.dp + ) +) +``` + + + + +- **What this does**: applies a custom badge appearance across UI Kit lists. +- **Verify**: check any unread badge to confirm colors and radius. + +Attribute references: +- [Badge attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_badge.xml) + +#### Status Indicator + +The `CometChatStatusIndicator` component shows user presence status. + + + + + +What you're changing: status indicator icon shape and drawable. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatStatusIndicator` +- **Default behavior**: UI Kit default presence icon. +- **Override**: set `cometchatStatusIndicatorStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +// Via parent component style +style = ComponentStyle.default().copy( + statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy( + cornerRadius = 8.dp + ) +) +``` + + + + +- **What this does**: applies the custom status indicator in UI Kit components. +- **Verify**: check any user list to confirm the presence icon. + +Attribute references: +- [Status Indicator attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_status_indicator.xml) + +#### Reaction List + +The `CometChatReactionList` component renders reactions on messages. + + + + + +What you're changing: active tab color in the reaction list. + +- **Where to change it**: `res/values/themes.xml` (XML Views) or `style` parameter (Compose) +- **Applies to**: `CometChatReactionList` +- **Default behavior**: UI Kit default reaction list styling. +- **Override**: set `cometchatReactionListStyle` in `AppTheme` or pass a style object. + + + + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +CometChatReactionList( + style = CometChatReactionListStyle.default().copy( + tabTextActiveColor = Color(0xFFF76808) + ) +) +``` + + + + +- **What this does**: applies a custom active tab color in the reaction list. +- **Verify**: open reactions and confirm the active tab color. + +Attribute references: +- [Reaction List attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit-kotlin/src/main/res/values/attr_cometchat_reaction_list.xml) + +#### Date + +The `CometChatDate` component formats timestamps in lists and message threads. + + + + + +What you're changing: date text color. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatDate` + +- **Default behavior**: UI Kit default date styling. + +- **Override**: set `cometchatDateStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: customizes date text color in UI Kit lists and headers. + +- **Verify**: check any timestamp and confirm the color. + +Attribute references: +- [Date attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_date.xml) + + +#### Receipts + +The `CometChatReceipts` component renders read and delivered status icons. + + + + + +What you're changing: read receipt icon drawable. + +- **Where to change it**: `res/drawable/read_receipts.xml` and `res/values/themes.xml` + +- **Applies to**: `CometChatReceipts` + +- **Default behavior**: UI Kit default receipt icons. + +- **Override**: set `cometchatMessageReceiptStyle` in `AppTheme` and reference a custom drawable. + +- **Code**: +```xml res/drawable/read_receipts.xml lines + + + + +``` + +- **What this does**: defines a custom read receipt icon. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: applies the custom receipt icon to message status indicators. + +- **Verify**: send a message and check the receipt icon for read status. + +Attribute references: +- [Message Receipt attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_message_receipt.xml) + + +#### Media Recorder + +The `CometChatMediaRecorder` component controls audio and video message recording. + + + + + +What you're changing: recorder icon sizes and recording button background color. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatMediaRecorder` + +- **Default behavior**: UI Kit default media recorder styling. + +- **Override**: set `cometchatMediaRecorderStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: applies custom sizing and color to the media recorder UI. + +- **Verify**: open the recorder and check icon sizes and record button color. + +Attribute references: +- [Media Recorder attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_media_recorder.xml) + + +#### Sticker Keyboard + +The `CometChatStickerKeyboard` component renders the sticker picker UI. + + + + + +What you're changing: sticker keyboard background color. + +- **Where to change it**: `res/values/themes.xml` + +- **Applies to**: `CometChatStickerKeyboard` + +- **Default behavior**: UI Kit default sticker keyboard styling. + +- **Override**: set `cometchatStickerKeyboardStyle` in `AppTheme`. + +- **Code**: +```xml res/values/themes.xml lines + + + + + +``` + +- **What this does**: applies a custom background color to the sticker keyboard. + +- **Verify**: open the sticker keyboard and confirm the background color. + +Attribute references: +- [Sticker Keyboard attributes](https://github.com/cometchat/cometchat-uikit-android/blob/v6/chatuikit/src/main/res/values/attr_cometchat_sticker_keyboard.xml) + + +--- + +## Customization matrix + +| What you want to change | Where | Property or API | Example | +| --- | --- | --- | --- | +| Conversations avatar and badge | `themes.xml` / style param | `cometchatConversationsStyle` | `cometchatConversationsBadgeStyle` | +| Users list separators | `themes.xml` / style param | `cometchatUsersStyle` | `cometchatUsersSeparatorColor` | +| Group list titles | `themes.xml` / style param | `cometchatGroupsStyle` | `cometchatGroupsTitleTextColor` | +| Header call icons | `themes.xml` / style param | `cometchatMessageHeaderStyle` | `cometchatMessageHeaderCallButtonsStyle` | +| Message list background | `themes.xml` / style param | `cometchatMessageListStyle` | `cometchatMessageListBackgroundColor` | +| Search styling | `themes.xml` / style param | `cometchatSearchStyle` | `cometchatSearchBackgroundColor` | +| Message Information | `themes.xml` / style param | `cometchatMessageInformationStyle` | `cometchatMessageInformationBackgroundColor` | +| AI Chat History | `themes.xml` / style param | `cometchatAIAssistantChatHistoryStyle` | `cometchatAIAssistantChatHistoryBackgroundColor` | +| Date formatting | `themes.xml` / style param | `cometchatDateStyle` | `cometchatDateTextColor` | +| Receipts icons | `themes.xml` / style param | `cometchatReceiptsStyle` | `cometchatReceiptsReadColor` | +| Composer send button | `res/drawable/` + `themes.xml` | `cometchatMessageComposerActiveSendButtonDrawable` | `@drawable/active_send_button` | +| Call buttons styling | `themes.xml` / style param | `cometchatCallButtonsStyle` | `cometchatCallButtonsVideoCallBackgroundColor` | diff --git a/ui-kit/android/v6/components-overview.mdx b/ui-kit/android/v6/components-overview.mdx new file mode 100644 index 000000000..1461fb7f8 --- /dev/null +++ b/ui-kit/android/v6/components-overview.mdx @@ -0,0 +1,248 @@ +--- +title: "Overview" +description: "Browse all prebuilt UI components in the CometChat Android UI Kit." +--- + + + +| Field | Value | +| --- | --- | +| Packages | `com.cometchat:chatuikit-kotlin-android` (Kotlin XML Views), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) | +| Required setup | `CometChatUIKit.init()` + `CometChatUIKit.login()` before rendering any component | +| Shared core | `chatuikit-core` — ViewModels, repositories, use cases, events (shared by both modules) | +| Calling | Requires separate `com.cometchat:calls-sdk-android` package | + + + +## Architecture + +The UI Kit is a set of independent components that compose into chat layouts. A typical chat layout uses four core components: + +- `CometChatConversations` — list of recent conversations +- `CometChatMessageHeader` — toolbar with avatar, name, status, typing indicator +- `CometChatMessageList` — scrollable message feed with reactions, receipts, threads +- `CometChatMessageComposer` — rich input with attachments, mentions, voice notes + +Selecting a conversation yields a `User` or `Group` object. Pass it to the message components to load the chat. + +Components communicate via `CometChatEvents` — a SharedFlow-based event bus. See [Events](/ui-kit/android/v6/events). + +--- + +## Component Catalog + +### Conversations and Lists + +| Component | Purpose | Page | +| --- | --- | --- | +| `CometChatConversations` | Scrollable list of recent conversations | [Conversations](/ui-kit/android/v6/conversations) | +| `CometChatUsers` | Scrollable list of users | [Users](/ui-kit/android/v6/users) | +| `CometChatGroups` | Scrollable list of groups | [Groups](/ui-kit/android/v6/groups) | +| `CometChatGroupMembers` | Scrollable list of group members | [Group Members](/ui-kit/android/v6/group-members) | + +### Messages + +| Component | Purpose | Page | +| --- | --- | --- | +| `CometChatMessageHeader` | Toolbar with avatar, name, status, typing | [Message Header](/ui-kit/android/v6/message-header) | +| `CometChatMessageList` | Message feed with reactions, receipts, threads | [Message List](/ui-kit/android/v6/message-list) | +| `CometChatMessageComposer` | Rich input with attachments, mentions, voice | [Message Composer](/ui-kit/android/v6/message-composer) | +| `CometChatThreadHeader` | Parent message bubble and reply count | [Thread Header](/ui-kit/android/v6/threaded-messages-header) | + +### Calling + +| Component | Purpose | Page | +| --- | --- | --- | +| `CometChatCallButtons` | Voice and video call buttons | [Call Buttons](/ui-kit/android/v6/call-buttons) | +| `CometChatIncomingCall` | Incoming call notification | [Incoming Call](/ui-kit/android/v6/incoming-call) | +| `CometChatOutgoingCall` | Outgoing call screen | [Outgoing Call](/ui-kit/android/v6/outgoing-call) | +| `CometChatCallLogs` | Call history list | [Call Logs](/ui-kit/android/v6/call-logs) | + +--- + +## Component API Pattern + +All components share a consistent API surface across both modules. + +### Setting User or Group + + + + + +```kotlin lines +messageHeader.setUser(user) +messageList.setUser(user) +messageComposer.setUser(user) + +// Or for group chat +messageHeader.setGroup(group) +messageList.setGroup(group) +messageComposer.setGroup(group) +``` + + + + +```kotlin lines +CometChatMessageHeader(user = user) +CometChatMessageList(user = user) +CometChatMessageComposer(user = user) + +// Or for group chat +CometChatMessageHeader(group = group) +CometChatMessageList(group = group) +CometChatMessageComposer(group = group) +``` + + + + +### Callbacks + + + + +```kotlin lines +conversations.setOnItemClick { conversation -> /* navigate */ } +conversations.setOnError { exception -> /* handle error */ } +conversations.setOnLoad { list -> /* data loaded */ } +``` + + + + +```kotlin lines +CometChatConversations( + onItemClick = { conversation -> /* navigate */ }, + onError = { exception -> /* handle error */ }, + onLoad = { list -> /* data loaded */ } +) +``` + + + + +### Data Filtering + + + + +```kotlin lines +conversations.setConversationsRequestBuilder( + ConversationsRequest.ConversationsRequestBuilder().setLimit(20) +) +``` + + + + +```kotlin lines +CometChatConversations( + conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder().setLimit(20) +) +``` + + + + +### View Slots + +Replace specific regions of a component's UI. See [View Slots](/ui-kit/android/v6/customization-view-slots). + + + + +```kotlin lines +conversations.setSubtitleView(object : ConversationsViewHolderListener() { + override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View { + return CustomSubtitleView(context) + } + override fun bindView(context: Context, createdView: View, conversation: Conversation, ...) { + (createdView as CustomSubtitleView).bind(conversation) + } +}) +``` + + + + +```kotlin lines +CometChatConversations( + subtitleView = { conversation, typingIndicator -> + Text(conversation.lastMessage?.text ?: "") + } +) +``` + + + + +### Styles + +See [Component Styling](/ui-kit/android/v6/component-styling). + + + + +XML theme attributes in `themes.xml`: + +```xml lines + +``` + + + + +Style data classes via parameters: + +```kotlin lines +CometChatConversations( + style = CometChatConversationsStyle.default().copy( + backgroundColor = Color(0xFFF5F5F5) + ) +) +``` + + + + +### Events + +Global inter-component communication via `CometChatEvents`: + +```kotlin lines +// Subscribe to message events +viewModelScope.launch { + CometChatEvents.messageEvents.collect { event -> + when (event) { + is CometChatMessageEvent.MessageSent -> { /* handle */ } + is CometChatMessageEvent.MessageDeleted -> { /* handle */ } + else -> {} + } + } +} +``` + +See [Events](/ui-kit/android/v6/events) for the full reference. + +--- + +## Next Steps + + + + Chat features included out of the box + + + Customize colors, fonts, and styles + + + Deep customization via ViewModels, styles, and view slots + + + Task-oriented tutorials for common patterns + + diff --git a/ui-kit/android/v6/conversation-message-view.mdx b/ui-kit/android/v6/conversation-message-view.mdx new file mode 100644 index 000000000..61f3ed5f9 --- /dev/null +++ b/ui-kit/android/v6/conversation-message-view.mdx @@ -0,0 +1,446 @@ +--- +title: "Building A Conversation List + Message View" +sidebarTitle: "Conversation List + Message View" +description: "Build a conversation list with a full-screen message view using the Kotlin XML Views or Jetpack Compose UI Kit." +--- + + + +| Field | Value | +| --- | --- | +| Components | `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` | +| Layout | Sequential navigation — conversation list → full-screen message view | +| Prerequisite | Complete [Kotlin Integration](/ui-kit/android/v6/getting-started-kotlin) or [Jetpack Compose Integration](/ui-kit/android/v6/getting-started-jetpack) Steps 1–3 first | +| Pattern | WhatsApp, Slack, Telegram | + + + +This guide builds a sequential navigation chat layout — conversation list as the entry point, tap a conversation to open a full-screen message view. + +This assumes you've already completed the integration guide for your chosen UI toolkit (project created, dependencies installed, init + login working). + +--- + +## What You're Building + +Three sections working together: + +1. **Conversation list** — shows all active conversations (users and groups) +2. **Message header** — displays user/group name, avatar, and status +3. **Message list + composer** — chat history with real-time updates and text input + + + +This implementation uses Android's standard Activity navigation: `ConversationActivity` displays the list, user taps a conversation, `MessageActivity` launches with the selected user/group data via Intent extras. + + +This implementation uses Compose state to manage navigation between the conversation list and message screen — no Activities or Fragments needed beyond your `MainActivity`. + + + +--- + +## Step 1: Set Up the Conversation List + + + + +Create a new Activity called `ConversationActivity` to display the list of conversations. + +**Layout** — `activity_conversation.xml`: + +```xml activity_conversation.xml lines + + + + + +``` + +**Activity** — `ConversationActivity.kt`: + +```kotlin ConversationActivity.kt lines +import android.content.Intent +import android.os.Bundle +import android.util.Log +import androidx.activity.enableEdgeToEdge +import androidx.appcompat.app.AppCompatActivity +import com.cometchat.chat.models.Group +import com.cometchat.chat.models.User +import com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations + +class ConversationActivity : AppCompatActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + enableEdgeToEdge() + setContentView(R.layout.activity_conversation) + + val conversations = findViewById(R.id.conversations) + + conversations.setTitle("Chats") + conversations.setOnItemClick { conversation -> + val intent = Intent(this, MessageActivity::class.java) + when (val entity = conversation.conversationWith) { + is User -> intent.putExtra("user", entity) + is Group -> intent.putExtra("group", entity) + else -> Log.e("ConversationActivity", "Unknown conversation type") + } + startActivity(intent) + } + } +} +``` + + +You must use an activity that supports the **lifecycle** API (`AppCompatActivity`, `ComponentActivity`, or `FragmentActivity`) to properly manage the UI Kit's lifecycle events. + + + + + +Create a `ChatApp.kt` file with the root composable that manages navigation between the conversation list and message screen: + +```kotlin ChatApp.kt lines +import androidx.compose.runtime.Composable +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.remember +import androidx.compose.runtime.setValue +import com.cometchat.chat.models.Group +import com.cometchat.chat.models.User + +@Composable +fun ChatApp() { + var selectedUser by remember { mutableStateOf(null) } + var selectedGroup by remember { mutableStateOf(null) } + + val inChat = selectedUser != null || selectedGroup != null + + if (!inChat) { + ConversationsScreen( + onConversationClick = { user, group -> + selectedUser = user + selectedGroup = group + } + ) + } else { + MessageScreen( + user = selectedUser, + group = selectedGroup, + onBack = { + selectedUser = null + selectedGroup = null + } + ) + } +} +``` + +Add the `ConversationsScreen` composable: + +```kotlin ChatApp.kt lines +import androidx.compose.foundation.layout.fillMaxSize +import androidx.compose.ui.Modifier +import com.cometchat.uikit.compose.presentation.conversations.ui.CometChatConversations + +@Composable +fun ConversationsScreen( + onConversationClick: (User?, Group?) -> Unit +) { + CometChatConversations( + modifier = Modifier.fillMaxSize(), + title = "Chats", + onItemClick = { conversation -> + when (val entity = conversation.conversationWith) { + is User -> onConversationClick(entity, null) + is Group -> onConversationClick(null, entity) + } + } + ) +} +``` + + + + +--- + +## Step 2: Set Up the Message Screen + + + + +Create a new Activity — `MessageActivity` to display the chat interface. + +**Layout** — `activity_message.xml`: + +```xml activity_message.xml lines + + + + + + + + + +``` + +**Activity** — `MessageActivity.kt`: + +```kotlin MessageActivity.kt lines +import android.os.Bundle +import android.widget.Toast +import androidx.activity.enableEdgeToEdge +import androidx.appcompat.app.AppCompatActivity +import com.cometchat.chat.models.Group +import com.cometchat.chat.models.User +import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer +import com.cometchat.uikit.kotlin.presentation.messageheader.ui.CometChatMessageHeader +import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList + +class MessageActivity : AppCompatActivity() { + + private lateinit var messageHeader: CometChatMessageHeader + private lateinit var messageList: CometChatMessageList + private lateinit var messageComposer: CometChatMessageComposer + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + enableEdgeToEdge() + setContentView(R.layout.activity_message) + + messageHeader = findViewById(R.id.message_header) + messageList = findViewById(R.id.message_list) + messageComposer = findViewById(R.id.message_composer) + + val user = intent.getSerializableExtra("user") as? User + val group = intent.getSerializableExtra("group") as? Group + + when { + user != null -> { + messageHeader.setUser(user) + messageList.setUser(user) + messageComposer.setUser(user) + } + group != null -> { + messageHeader.setGroup(group) + messageList.setGroup(group) + messageComposer.setGroup(group) + } + else -> { + Toast.makeText(this, "Missing user or group data", Toast.LENGTH_SHORT).show() + finish() + } + } + + messageHeader.setOnBackPress { finish() } + } +} +``` + + + + +Add the `MessageScreen` composable with header, list, and composer stacked vertically: + +```kotlin ChatApp.kt lines +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.WindowInsets +import androidx.compose.foundation.layout.consumeWindowInsets +import androidx.compose.foundation.layout.fillMaxSize +import androidx.compose.foundation.layout.fillMaxWidth +import androidx.compose.foundation.layout.imePadding +import androidx.compose.foundation.layout.navigationBarsPadding +import androidx.compose.foundation.layout.padding +import androidx.compose.foundation.layout.statusBars +import androidx.compose.material3.Scaffold +import androidx.compose.runtime.Composable +import androidx.compose.ui.Modifier +import com.cometchat.chat.models.Group +import com.cometchat.chat.models.User +import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer +import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader +import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList + +@Composable +fun MessageScreen( + user: User? = null, + group: Group? = null, + onBack: () -> Unit +) { + Scaffold( + contentWindowInsets = WindowInsets.statusBars + ) { paddingValues -> + Column( + modifier = Modifier + .fillMaxSize() + .padding(paddingValues) + .consumeWindowInsets(paddingValues) + .navigationBarsPadding() + .imePadding() + ) { + CometChatMessageHeader( + modifier = Modifier.fillMaxWidth(), + user = user, + group = group, + hideBackButton = false, + onBackPress = onBack + ) + + CometChatMessageList( + modifier = Modifier + .fillMaxWidth() + .weight(1f), + user = user, + group = group + ) + + CometChatMessageComposer( + modifier = Modifier.fillMaxWidth(), + user = user, + group = group + ) + } + } +} +``` + + + + +--- + +## Step 3: Update MainActivity + + + + +Update your `MainActivity` to launch `ConversationActivity` after successful login: + +```kotlin MainActivity.kt lines +private fun loginUser() { + CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener() { + override fun onSuccess(user: User) { + Log.d(TAG, "Login successful: ${user.uid}") + + // Launch Conversation List + Message View + startActivity(Intent(this@MainActivity, ConversationActivity::class.java)) + } + + override fun onError(e: CometChatException) { + Log.e(TAG, "Login failed: ${e.message}") + } + }) +} +``` + + + + +Update your `MainActivity` to render `ChatApp()` after successful login: + +```kotlin MainActivity.kt lines +setContent { + when { + error != null -> { + Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { + Text(error ?: "Unknown error") + } + } + !isReady -> { + Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { + CircularProgressIndicator() + } + } + else -> { + ChatApp() + } + } +} +``` + + + + +--- + +## Step 4: Register Activities & Permissions + + + + +Add the new activities to your `AndroidManifest.xml`: + +```xml AndroidManifest.xml lines + + + + + + + + + + +``` + + + + +No additional activities needed — everything runs inside your existing `MainActivity`. + + + + +Ensure you've added the required permissions in your `AndroidManifest.xml`: + +```xml AndroidManifest.xml lines + + +``` + +--- + +## Next Steps + + + + Explore all available UI Kit components and their customization options + + + Customize colors, fonts, and styles to match your brand + + + Back to the main integration guide + + + Add capabilities like threaded messages, blocking, and group management + + diff --git a/ui-kit/android/v6/conversations.mdx b/ui-kit/android/v6/conversations.mdx new file mode 100644 index 000000000..ffbc2278f --- /dev/null +++ b/ui-kit/android/v6/conversations.mdx @@ -0,0 +1,952 @@ +--- +title: "Conversations" +description: "Scrollable list of recent one-on-one and group conversations for the logged-in user." +--- + +`CometChatConversations` renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence. + + + + + +--- + +## Where It Fits + +`CometChatConversations` is a list component. It renders recent conversations and emits the selected `Conversation` via `onItemClick`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard chat layout. + + + + +```xml activity_chat.xml lines + +``` + +```kotlin lines +val conversations = findViewById(R.id.conversations) + +conversations.setOnItemClick { conversation -> + when (val entity = conversation.conversationWith) { + is User -> navigateToUserChat(entity) + is Group -> navigateToGroupChat(entity) + } +} +``` + + + + +```kotlin lines +CometChatConversations( + modifier = Modifier.fillMaxSize(), + onItemClick = { conversation -> + when (val entity = conversation.conversationWith) { + is User -> navigateToUserChat(entity) + is Group -> navigateToGroupChat(entity) + } + } +) +``` + + + + +> See the [Conversation List + Message View](/ui-kit/android/v6/conversation-message-view) guide for a complete layout. + +--- + +## Quick Start + + + + +Add to your layout XML: + +```xml lines + +``` + +Or programmatically: + +```kotlin lines +override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(CometChatConversations(this)) +} +``` + + + + +```kotlin lines +@Composable +fun ConversationsScreen() { + CometChatConversations( + modifier = Modifier.fillMaxSize() + ) +} +``` + + + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + +Or in a Fragment: + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + return CometChatConversations(requireContext()) +} +``` + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + return ComposeView(requireContext()).apply { + setContent { CometChatConversations() } + } +} +``` + + + + +--- + +## Filtering Conversations + + + + +Pass a `ConversationsRequest.ConversationsRequestBuilder` to control what loads: + +```kotlin lines +conversations.setConversationsRequestBuilder( + ConversationsRequest.ConversationsRequestBuilder() + .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER) + .setLimit(20) +) +``` + + + + +```kotlin lines +CometChatConversations( + conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder() + .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER) + .setLimit(20) +) +``` + + + + +### Filter Recipes + +| Recipe | Builder method | +| --- | --- | +| Only user conversations | `.setConversationType(CONVERSATION_TYPE_USER)` | +| Only group conversations | `.setConversationType(CONVERSATION_TYPE_GROUP)` | +| Limit per page | `.setLimit(10)` | +| With tags | `.setTags(listOf("vip")).withTags(true)` | +| Filter by user tags | `.withUserAndGroupTags(true).setUserTags(listOf("premium"))` | +| Filter by group tags | `.withUserAndGroupTags(true).setGroupTags(listOf("support"))` | + + +Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll. + + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemClick` + +Fires when a conversation row is tapped. Primary navigation hook. + + + + +```kotlin lines +conversations.setOnItemClick { conversation -> + // Navigate to chat screen +} +``` + + + + +```kotlin lines +CometChatConversations( + onItemClick = { conversation -> + // Navigate to chat screen + } +) +``` + + + + +> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation. + +#### `onItemLongClick` + +Fires when a conversation row is long-pressed. Use for additional actions like delete or select. + + + + +```kotlin lines +conversations.setOnItemLongClick { conversation -> + // Show context menu +} +``` + + + + +```kotlin lines +CometChatConversations( + onItemLongClick = { conversation -> + // Show context menu + } +) +``` + + + + +#### `onBackPress` + +Fires when the user presses the back button in the toolbar. + + + + +```kotlin lines +conversations.setOnBackPress { + finish() +} +``` + + + + +```kotlin lines +CometChatConversations( + onBackPress = { /* navigate back */ } +) +``` + + + + +#### `onSearchClick` + +Fires when the user taps the search icon in the toolbar. + + + + +```kotlin lines +conversations.setOnSearchClick { + // Open search screen +} +``` + + + + +```kotlin lines +CometChatConversations( + onSearchClick = { /* open search */ } +) +``` + + + + +#### `onSelection` + +Fires when conversations are selected/deselected in multi-select mode. + + + + +```kotlin lines +conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE) +conversations.setOnSelection { selectedConversations -> + updateToolbar(selectedConversations.size) +} +``` + + + + +```kotlin lines +CometChatConversations( + selectionMode = UIKitConstants.SelectionMode.MULTIPLE, + onSelection = { selectedConversations -> + updateToolbar(selectedConversations.size) + } +) +``` + + + + +#### `onError` + +Fires on internal errors (network failure, auth issue, SDK exception). + + + + +```kotlin lines +conversations.setOnError { exception -> + Log.e("Conversations", "Error: ${exception.message}") +} +``` + + + + +```kotlin lines +CometChatConversations( + onError = { exception -> + Log.e("Conversations", "Error: ${exception.message}") + } +) +``` + + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + + +```kotlin lines +conversations.setOnLoad { conversations -> + Log.d("Conversations", "Loaded ${conversations.size}") +} +``` + + + + +```kotlin lines +CometChatConversations( + onLoad = { conversations -> + Log.d("Conversations", "Loaded ${conversations.size}") + } +) +``` + + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + + +```kotlin lines +conversations.setOnEmpty { + Log.d("Conversations", "No conversations") +} +``` + + + + +```kotlin lines +CometChatConversations( + onEmpty = { /* no conversations */ } +) +``` + + + + +### Global Events + +The component emits events via `CometChatEvents` that can be subscribed to from anywhere: + +```kotlin lines +viewModelScope.launch { + CometChatEvents.conversationEvents.collect { event -> + when (event) { + is CometChatConversationEvent.ConversationDeleted -> { /* handle */ } + is CometChatConversationEvent.ConversationUpdated -> { /* handle */ } + } + } +} +``` + +### SDK Events (Real-Time, Automatic) + +The component listens to these SDK events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +| --- | --- | +| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived` | Moves conversation to top, updates last message and unread count | +| `onTypingStarted` / `onTypingEnded` | Shows/hides typing indicator in subtitle | +| `onMessagesDelivered` / `onMessagesRead` | Updates receipt indicators | +| `onUserOnline` / `onUserOffline` | Updates presence status dot | +| `onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` | Updates group conversation metadata | + +--- + +## Functionality + +| Method (Kotlin XML) | Compose Parameter | Description | +| --- | --- | --- | +| `setBackIconVisibility(View.VISIBLE)` | `hideBackIcon = false` | Toggle back button | +| `setToolbarVisibility(View.GONE)` | `hideToolbar = true` | Toggle toolbar | +| `setSearchBoxVisibility(View.GONE)` | `hideSearchBox = true` | Toggle search box | +| `setDisableSoundForMessages(true)` | `disableSoundForMessages = true` | Disable message sounds | +| `setCustomSoundForMessages(R.raw.sound)` | `customSoundForMessages = R.raw.sound` | Custom message sound | +| `setSelectionMode(MULTIPLE)` | `selectionMode = MULTIPLE` | Enable selection mode | +| `setTitle("Chats")` | `title = "Chats"` | Custom toolbar title | +| `setSearchPlaceholderText("Search...")` | `searchPlaceholderText = "Search..."` | Search placeholder | + +--- + +## Custom View Slots + +### Leading View + +Replace the avatar / left section. + + + + +```kotlin lines +conversations.setLeadingView(object : ConversationsViewHolderListener() { + override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View { + return ImageView(context).apply { + layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp) + } + } + + override fun bindView( + context: Context, createdView: View, conversation: Conversation, + typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder, + conversations: List, position: Int + ) { + val imageView = createdView as ImageView + // Load avatar image + } +}) +``` + + + + +```kotlin lines +CometChatConversations( + leadingView = { conversation, typingIndicator -> + CometChatAvatar( + imageUrl = conversation.conversationWith?.avatar, + name = conversation.conversationWith?.name + ) + } +) +``` + + + + +### Title View + +Replace the name / title text. + + + + +```kotlin lines +conversations.setTitleView(object : ConversationsViewHolderListener() { + override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, conversation: Conversation, + typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder, + conversations: List, position: Int + ) { + (createdView as TextView).text = conversation.conversationWith?.name ?: "" + } +}) +``` + + + + +```kotlin lines +CometChatConversations( + titleView = { conversation, _ -> + Text( + text = conversation.conversationWith?.name ?: "", + style = CometChatTheme.typography.heading4Medium + ) + } +) +``` + + + + +### Subtitle View + +Replace the last message preview. + + + + +```kotlin lines +conversations.setSubtitleView(object : ConversationsViewHolderListener() { + override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View { + return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END } + } + + override fun bindView( + context: Context, createdView: View, conversation: Conversation, + typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder, + conversations: List, position: Int + ) { + val textView = createdView as TextView + if (typingIndicator != null) { + textView.text = "typing..." + } else { + textView.text = when (val msg = conversation.lastMessage) { + is TextMessage -> msg.text + is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}" + else -> "New conversation" + } + } + } +}) +``` + + + + +```kotlin lines +CometChatConversations( + subtitleView = { conversation, typingIndicator -> + val text = if (typingIndicator != null) "typing..." else { + when (val msg = conversation.lastMessage) { + is TextMessage -> msg.text ?: "" + is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}" + else -> "New conversation" + } + } + Text(text, maxLines = 1, overflow = TextOverflow.Ellipsis) + } +) +``` + + + + +### Trailing View + +Replace the timestamp / badge / right section. + + + + +```kotlin lines +conversations.setTrailingView(object : ConversationsViewHolderListener() { + override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, conversation: Conversation, + typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder, + conversations: List, position: Int + ) { + (createdView as TextView).text = "${conversation.unreadMessageCount} unread" + } +}) +``` + + + + +```kotlin lines +CometChatConversations( + trailingView = { conversation, _ -> + if (conversation.unreadMessageCount > 0) { + Badge { Text("${conversation.unreadMessageCount}") } + } + } +) +``` + + + + +### State Views + + + + +```kotlin lines +conversations.setEmptyView(customEmptyView) +conversations.setErrorView(customErrorView) +conversations.setLoadingView(customLoadingView) +``` + + + + +```kotlin lines +CometChatConversations( + emptyView = { Text("No conversations yet") }, + errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } }, + loadingView = { CircularProgressIndicator() } +) +``` + + + + +### Overflow Menu + + + + +```kotlin lines +conversations.setOverflowMenu(ImageButton(context).apply { + setImageResource(R.drawable.ic_filter) + setOnClickListener { /* show filter */ } +}) +``` + + + + +```kotlin lines +CometChatConversations( + overflowMenu = { + IconButton(onClick = { /* show filter */ }) { + Icon(painterResource(R.drawable.ic_filter), "Filter") + } + } +) +``` + + + + +--- + +## Menu Options + + + + +```kotlin lines +// Replace all options +conversations.setOptions { context, conversation -> + listOf( + CometChatPopupMenu.MenuItem(id = "archive", name = "Archive", onClick = { /* ... */ }), + CometChatPopupMenu.MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ }) + ) +} + +// Append to defaults +conversations.setAddOptions { context, conversation -> + listOf( + CometChatPopupMenu.MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ }) + ) +} +``` + + + + +```kotlin lines +CometChatConversations( + options = { context, conversation -> + listOf( + MenuItem(id = "archive", name = "Archive", onClick = { /* ... */ }), + MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ }) + ) + }, + addOptions = { context, conversation -> + listOf(MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ })) + } +) +``` + + + + +--- + +## Common Patterns + +### Minimal list — hide all chrome + + + + +```kotlin lines +conversations.setToolbarVisibility(View.GONE) +conversations.setSearchBoxVisibility(View.GONE) +``` + + + + +```kotlin lines +CometChatConversations( + hideToolbar = true, + hideSearchBox = true +) +``` + + + + +### Users-only conversations + + + + +```kotlin lines +conversations.setConversationsRequestBuilder( + ConversationsRequest.ConversationsRequestBuilder() + .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER) +) +``` + + + + +```kotlin lines +CometChatConversations( + conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder() + .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER) +) +``` + + + + +### Custom date formatting + + + + +```kotlin lines +conversations.setDateTimeFormatter(object : DateTimeFormatterCallback { + override fun today(timestamp: Long) = "Today" + override fun yesterday(timestamp: Long) = "Yesterday" + override fun otherDays(timestamp: Long) = SimpleDateFormat("MMM d", Locale.getDefault()).format(Date(timestamp)) + override fun time(timestamp: Long) = SimpleDateFormat("h:mm a", Locale.getDefault()).format(Date(timestamp)) + override fun minutes(diff: Long, timestamp: Long) = "${diff}m ago" + override fun hours(diff: Long, timestamp: Long) = "${diff}h ago" + override fun lastWeek(timestamp: Long) = "Last week" +}) +``` + + + + +```kotlin lines +CometChatConversations( + dateTimeFormatter = object : DateTimeFormatterCallback { + override fun today(timestamp: Long) = "Today" + override fun yesterday(timestamp: Long) = "Yesterday" + override fun otherDays(timestamp: Long) = SimpleDateFormat("MMM d", Locale.getDefault()).format(Date(timestamp)) + override fun time(timestamp: Long) = SimpleDateFormat("h:mm a", Locale.getDefault()).format(Date(timestamp)) + override fun minutes(diff: Long, timestamp: Long) = "${diff}m ago" + override fun hours(diff: Long, timestamp: Long) = "${diff}h ago" + override fun lastWeek(timestamp: Long) = "Last week" + } +) +``` + + + + +--- + +## Advanced Methods + +### Programmatic Selection + + + + +```kotlin lines +// Enable selection +conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE) + +// Select a conversation +conversations.selectConversation(conversation, UIKitConstants.SelectionMode.MULTIPLE) + +// Get selected +val selected = conversations.getSelectedConversations() + +// Clear +conversations.clearSelection() +``` + + + + +Selection is managed via the `selectionMode` and `onSelection` parameters. The component handles selection state internally. + + + + +### ViewModel Access + +```kotlin lines +val factory = CometChatConversationsViewModelFactory( + repository = MyCustomRepository() // optional +) +val viewModel = ViewModelProvider(this, factory) + .get(CometChatConversationsViewModel::class.java) +``` + + + + +```kotlin lines +conversations.setViewModel(viewModel) +``` + + + + +```kotlin lines +CometChatConversations( + conversationsViewModel = viewModel +) +``` + + + + +See [ViewModel & Data](/ui-kit/android/v6/customization-viewmodel-data) for ListOperations, state observation, and custom repositories. + +--- + +## Style + + + + +Define a custom style in `themes.xml`: + +```xml themes.xml lines + + + +``` + + + + +```kotlin lines +CometChatConversations( + style = CometChatConversationsStyle.default().copy( + backgroundColor = Color(0xFFF5F5F5), + titleTextColor = Color(0xFF141414), + searchBoxStyle = CometChatSearchBoxStyle.default().copy( + backgroundColor = Color(0xFFFFFFFF) + ), + itemStyle = CometChatConversationsItemStyle.default().copy( + backgroundColor = Color.White, + titleTextColor = Color(0xFF141414), + subtitleTextColor = Color(0xFF727272), + avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp), + badgeStyle = CometChatBadgeStyle.default().copy(backgroundColor = Color(0xFFF76808)), + dateStyle = CometChatDateStyle.default().copy(textColor = Color(0xFFA1A1A1)), + receiptStyle = CometChatReceiptStyle.default().copy(), + statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy(), + typingIndicatorStyle = CometChatTypingIndicatorStyle.default().copy() + ) + ) +) +``` + + + + +### Style Properties + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background color | +| `titleTextColor` | Toolbar title color | +| `searchBoxStyle` | Search box appearance | +| `itemStyle.backgroundColor` | Row background | +| `itemStyle.selectedBackgroundColor` | Selected row background | +| `itemStyle.titleTextColor` | Conversation name color | +| `itemStyle.subtitleTextColor` | Last message preview color | +| `itemStyle.separatorColor` | Row separator color | +| `itemStyle.avatarStyle` | Avatar appearance | +| `itemStyle.badgeStyle` | Unread badge appearance | +| `itemStyle.dateStyle` | Timestamp appearance | +| `itemStyle.receiptStyle` | Read receipt icons | +| `itemStyle.statusIndicatorStyle` | Online/offline indicator | +| `itemStyle.typingIndicatorStyle` | Typing indicator text | +| `itemStyle.mentionStyle` | Mention highlight style | + +See [Component Styling](/ui-kit/android/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + Build a full chat layout with this component + + + Detailed styling reference with screenshots + + + Custom ViewModels, repositories, and ListOperations + + + Replace specific UI regions across all components + + diff --git a/ui-kit/android/v6/core-features.mdx b/ui-kit/android/v6/core-features.mdx new file mode 100644 index 000000000..ad33a43b5 --- /dev/null +++ b/ui-kit/android/v6/core-features.mdx @@ -0,0 +1,244 @@ +--- +title: "Core" +description: "Overview of CometChat's core chat features including instant messaging, media sharing, read receipts, typing indicators, user presence, reactions, mentions, threaded conversations, and moderation." +--- + + + +| Field | Value | +| --- | --- | +| Packages | `com.cometchat:chatuikit-kotlin-android` (Kotlin XML Views), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) | +| Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` — must complete before rendering any component | +| Core features | Instant Messaging, Media Sharing, Read Receipts, Mark as Unread, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Search, Threaded Conversations, Moderation, Report Message, Group Chat | +| Key components | `CometChatConversations`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`, `CometChatUsers`, `CometChatGroups`, `CometChatGroupMembers`, `CometChatMessageInformation`, `CometChatThreadHeader` | +| Theming | See [Theming](/ui-kit/android/v6/theme-introduction) | + + + +The UI Kit components work together to deliver a complete chat experience. The sections below map each core feature to the components that power it. + +## Instant Messaging + +Real-time text messaging — users can send and receive instant messages. + + + + + +| Component | Role | +| --- | --- | +| [CometChatMessageComposer](/ui-kit/android/v6/message-composer) | Enables users to write and send text messages. | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Renders sent and received messages using text bubbles. | + +## Media Sharing + +Share images, videos, audio files, and documents within conversations. + + + + + +| Component | Role | +| --- | --- | +| [CometChatMessageComposer](/ui-kit/android/v6/message-composer) | Provides an action sheet with options for sharing media files. | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Renders media message bubbles — [Image](/ui-kit/android/v6/message-bubble-styling#image-bubble), [File](/ui-kit/android/v6/message-bubble-styling#file-bubble), [Audio](/ui-kit/android/v6/message-bubble-styling#audio-bubble), [Video](/ui-kit/android/v6/message-bubble-styling#video-bubble). | + +## Read Receipts + +Visibility into message status — delivered and read indicators. + + + + + +| Component | Role | +| --- | --- | +| [CometChatConversations](/ui-kit/android/v6/conversations) | Displays delivery status of the last message in each conversation item. | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Shows read receipt status on every message bubble. | +| [CometChatMessageInformation](/ui-kit/android/v6/component-styling#message-information) | Shows detailed delivery and read status for a specific sent message. | + +## Mark as Unread + +Users can manually mark messages as unread to revisit important conversations later. The message list can start from the first unread message automatically. + + + + + +| Component | Role | +| --- | --- | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Provides the "Mark as unread" option in message actions and supports starting from the first unread message. | +| [CometChatConversations](/ui-kit/android/v6/conversations) | Reflects updated unread count in real-time. | + +## Typing Indicators + +Shows when a user is typing a response in real-time. + + + + + +| Component | Role | +| --- | --- | +| [CometChatConversations](/ui-kit/android/v6/conversations) | Shows real-time typing status in conversation items. | +| [CometChatMessageHeader](/ui-kit/android/v6/message-header) | Displays a "typing..." indicator when the other user or a group member is typing. | + +## User Presence + +See whether contacts are online or offline. + + + + + +| Component | Role | +| --- | --- | +| [CometChatConversations](/ui-kit/android/v6/conversations) | Shows user presence in conversation items. | +| [CometChatMessageHeader](/ui-kit/android/v6/message-header) | Displays user presence in the chat header. | +| [CometChatUsers](/ui-kit/android/v6/users) | Shows presence indicators in the user list. | +| [CometChatGroupMembers](/ui-kit/android/v6/group-members) | Shows presence indicators for group members. | + +## Reactions + +React to messages with emojis without typing a full response. + + + + + +| Component | Role | +| --- | --- | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Displays reactions on message bubbles and provides the reaction picker. | + +## Mentions + +Address specific users in a conversation by typing `@` to trigger mention suggestions. + + + + + +| Component | Role | +| --- | --- | +| [CometChatConversations](/ui-kit/android/v6/conversations) | Shows where users have been mentioned from the conversation list. | +| [CometChatMessageComposer](/ui-kit/android/v6/message-composer) | Triggers mention suggestions on `@` and inserts formatted mentions. | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Renders mentions with distinct styling in the message flow. | + + +## Rich Text Formatting + +Rich Text Formatting allows users to style their messages with bold, italic, strikethrough, code, code blocks, blockquotes, ordered/unordered lists, and links. This brings richer expression to conversations and helps users emphasize key points. + + + + + +| Component | Role | +| --- | --- | +| [CometChatMessageComposer](/ui-kit/android/v6/message-composer) | Provides a built-in rich text editor with formatting toolbar and text selection menu items for bold, italic, strikethrough, code, links, lists, blockquotes, and code blocks. | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Renders formatted messages with the appropriate styling automatically applied, ensuring that rich text formatting is displayed exactly as intended by the sender. | +## Threaded Conversations + +Respond directly to a specific message, keeping conversations organized. + + + + + +| Component | Role | +| --- | --- | +| [CometChatThreadHeader](/ui-kit/android/v6/threaded-messages-header) | Displays all replies made to a particular message. | +| [CometChatMessageComposer](/ui-kit/android/v6/message-composer) | Allows composing messages within a thread. | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Displays threaded messages in context. | + +## Quoted Replies + +Reply to specific messages by selecting "Reply" from the message action menu, maintaining context in the conversation. + + + + + +| Component | Role | +| --- | --- | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Provides the "Reply" option in message actions. | +| [CometChatMessageComposer](/ui-kit/android/v6/message-composer) | Shows the quoted reply above the input field for context. | + +## Group Chats + +Conversations with multiple participants — team collaborations, group discussions, and communities. + + + + + +| Component | Role | +| --- | --- | +| [CometChatGroups](/ui-kit/android/v6/groups) | Lists and manages groups. | +| [CometChatGroupMembers](/ui-kit/android/v6/group-members) | Displays and manages group members with roles and actions. | + +## Moderation + +Automatically filter and manage inappropriate content based on predefined rules. + + + + + + +Learn more about setting up moderation rules in the [Moderation](/moderation/overview) documentation. + + +| Component | Role | +| --- | --- | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Handles moderated messages, displaying blocked content based on your moderation settings. | + +## Report Message + +Users can report inappropriate messages by choosing from predefined reasons with optional remarks. + + +Learn more about flagged messages in the [Flagged Messages](/moderation/flagged-messages) documentation. + + + + + + +| Component | Role | +| --- | --- | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Provides the "Report Message" option in message actions. | + +## Conversation and Advanced Search + +Conversation and Advanced Search enables users to quickly find conversations, messages, and media across chats in real time. It supports filters, scopes, and custom actions, allowing users to locate content efficiently while keeping the chat experience smooth and intuitive. + + + + + +| Component | Role | +| --- | --- | +| [CometChatSearch](/ui-kit/android/v6/search) | Allows users to search across conversations and messages in real time. Users can click on a result to open the conversation or jump directly to a specific message. | +| [CometChatMessageHeader](/ui-kit/android/v6/message-header) | Shows the search button in the chat header, allowing users to search within a conversation. | +| [CometChatMessageList](/ui-kit/android/v6/message-list) | Shows the selected message when clicked from search results and highlights it in the message list. | +| [CometChatConversations](/ui-kit/android/v6/conversations) | Displays the search input. | + +--- + +## Next Steps + + + + Browse all available UI Kit components + + + Customize the look and feel of your chat UI + + + Add audio and video calling + + + Explore AI-powered chat capabilities + + diff --git a/ui-kit/android/v6/custom-text-formatter-guide.mdx b/ui-kit/android/v6/custom-text-formatter-guide.mdx new file mode 100644 index 000000000..592fb0b1d --- /dev/null +++ b/ui-kit/android/v6/custom-text-formatter-guide.mdx @@ -0,0 +1,174 @@ +--- +title: "Custom Text Formatter" +sidebarTitle: "Custom Text Formatter" +description: "Extend CometChatTextFormatter to build custom inline text patterns with tracking characters and suggestion lists." +--- + + + +| Field | Value | +| --- | --- | +| Packages | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack` | +| Key class | `CometChatTextFormatter` (abstract base class for custom formatters) | +| Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login("UID")` | +| Purpose | Extend to create custom inline text patterns with tracking characters, suggestion lists, and span formatting | +| Features | Tracking character activation, suggestion list, span formatting per context (composer, bubbles, conversations), pre-send hooks | +| Sample app | [GitHub](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin) | +| Related | [Mentions Formatter](/ui-kit/android/v6/mentions-formatter-guide) \| [ShortCut Formatter](/ui-kit/android/v6/shortcut-formatter-guide) \| [All Guides](/ui-kit/android/v6/guide-overview) | + + + +`CometChatTextFormatter` is an abstract class for formatting text in the message composer and message bubbles. Extend it to build custom formatters — hashtags, shortcuts, or any pattern triggered by a tracking character. + +| Capability | Description | +| --- | --- | +| Tracking character | Activates the formatter when the user types a specific character (e.g., `#`, `!`) | +| Suggestion list | Populates a dropdown of `SuggestionItem` objects as the user types | +| Span formatting | Applies `SpannableStringBuilder` spans per context: composer, left/right bubbles, conversations | +| Pre-send hook | `handlePreMessageSend` lets you modify the message before it's sent | +| Component integration | Plugs into any component via `setTextFormatters()` | + +--- + +## Steps + +### 1. Create a class extending CometChatTextFormatter + +Pass your tracking character to the superclass constructor. + + + +```kotlin lines +class HashTagFormatter : CometChatTextFormatter('#') { + private val suggestions: MutableList = ArrayList() +} +``` + + +```kotlin lines +// Same class — formatters are shared between both modules +class HashTagFormatter : CometChatTextFormatter('#') { + private val suggestions: MutableList = ArrayList() +} +``` + + + +### 2. Override the search method + +Called when the user types after the tracking character. Match input against your data and update the suggestion list. + +```kotlin lines +override fun search(context: Context, queryString: String?) { + suggestions.clear() + val query = "#${queryString ?: ""}" + // Match against your hashtag data source + val matchingTags = getMatchingTags(query) + for (tag in matchingTags) { + val item = SuggestionItem("", tag, null, null, tag, null, null) + item.isHideLeadingIcon = true + suggestions.add(item) + } + setSuggestionItemList(suggestions) +} +``` + +### 3. Override onScrollToBottom + +Required by the base class. Implement pagination logic or leave empty. + +```kotlin +override fun onScrollToBottom() { + // Load more suggestions if needed +} +``` + +### 4. Override span formatting methods (optional) + +Customize how matched text renders in different contexts using `SpannableStringBuilder`. + +```kotlin lines +override fun prepareLeftMessageBubbleSpan( + context: Context, baseMessage: BaseMessage, spannable: SpannableStringBuilder +): SpannableStringBuilder? { + // Apply custom spans for incoming message bubbles + return applyHashTagSpans(spannable, Color.parseColor("#5dff05")) +} + +override fun prepareRightMessageBubbleSpan( + context: Context, baseMessage: BaseMessage, spannable: SpannableStringBuilder +): SpannableStringBuilder? { + // Apply custom spans for outgoing message bubbles + return applyHashTagSpans(spannable, Color.parseColor("#30b3ff")) +} +``` + +### 5. Integrate with a component + + + +```kotlin lines +import com.cometchat.uikit.core.CometChatUIKit + +val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(this, messageComposer.additionParameter) +textFormatters.add(HashTagFormatter()) +messageComposer.setTextFormatters(textFormatters) +``` + + +```kotlin lines +import com.cometchat.uikit.core.CometChatUIKit + +// In your composable or ViewModel setup +val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(context, additionParameter) +textFormatters.add(HashTagFormatter()) + +CometChatMessageComposer( + user = user, + textFormatters = textFormatters +) +``` + + + +Pass the same list to `CometChatMessageList` and `CometChatConversations` via their `setTextFormatters()` methods to apply formatting across all contexts. + +--- + +## Methods Reference + +| Method | Description | +| --- | --- | +| `search(Context, String)` | Abstract — called when user types after the tracking character. Update the suggestion list here. | +| `onScrollToBottom()` | Abstract — called when the suggestion list scrolls to the bottom. Implement pagination or leave empty. | +| `onItemClick(Context, SuggestionItem, User, Group)` | Called when a suggestion item is selected. Override to customize insertion behavior. | +| `handlePreMessageSend(Context, BaseMessage)` | Called before a message is sent. Override to modify the message (e.g., add metadata). | +| `prepareLeftMessageBubbleSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in incoming message bubbles. | +| `prepareRightMessageBubbleSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in outgoing message bubbles. | +| `prepareComposerSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in the message composer. | +| `prepareConversationSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in the conversations list preview. | +| `setSuggestionItemList(List)` | Updates the suggestion dropdown with new items. | +| `setDisableSuggestions(boolean)` | Disables the suggestion dropdown entirely. (`protected` — accessible from subclasses only.) | +| `setInfoText(String)` | Sets informational text displayed above the suggestion list. | +| `setInfoVisibility(boolean)` | Toggles visibility of the info text. | +| `setShowLoadingIndicator(boolean)` | Shows/hides a loading spinner in the suggestion dropdown. | +| `getTrackingCharacter()` | Returns the tracking character passed to the constructor. | + +--- + +## Next Steps + + + + Built-in @mention formatting with styled tokens + + + Shortcut text expansion via the message-shortcuts extension + + + Browse all feature and formatter guides + + + Full working sample application on GitHub + + \ No newline at end of file diff --git a/ui-kit/android/v6/customization-events.mdx b/ui-kit/android/v6/customization-events.mdx new file mode 100644 index 000000000..61991429a --- /dev/null +++ b/ui-kit/android/v6/customization-events.mdx @@ -0,0 +1,227 @@ +--- +title: "Events & Callbacks" +description: "Handle user interaction events, selection mode, and global UI Kit events." +--- + +The UI Kit provides two levels of event handling: component-level callbacks set directly on a component, and global events via the `CometChatEvents` singleton using Kotlin `SharedFlow`. + +--- + +## Component-Level Callbacks + +### Click Callbacks + + + + +```kotlin lines +conversations.setOnItemClick { conversation -> + // Navigate to chat screen +} + +conversations.setOnItemLongClick { conversation -> + // Show context menu +} + +conversations.setOnBackPress { + // Handle back navigation +} + +conversations.setOnSearchClick { + // Open search +} + +conversations.setOnError { exception -> + Log.e("Conversations", "Error: ${exception.message}") +} + +conversations.setOnLoad { list -> + Log.d("Conversations", "Loaded ${list.size} conversations") +} + +conversations.setOnEmpty { + Log.d("Conversations", "No conversations") +} +``` + + + + +```kotlin lines +CometChatConversations( + onItemClick = { conversation -> + // Navigate to chat screen + }, + onItemLongClick = { conversation -> + // Show context menu + }, + onBackPress = { + // Handle back navigation + }, + onSearchClick = { + // Open search + }, + onError = { exception -> + Log.e("Conversations", "Error: ${exception.message}") + }, + onLoad = { list -> + Log.d("Conversations", "Loaded ${list.size} conversations") + }, + onEmpty = { + Log.d("Conversations", "No conversations") + } +) +``` + + + + +--- + +## Selection Mode + +Enable single or multi-select on list components: + + + + +```kotlin lines +// Enable multi-select mode +conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE) + +// Listen for selection changes +conversations.setOnSelection { selectedList -> + updateToolbar(selectedList.size) +} + +// Get selected items +val selected = conversations.getSelectedConversations() + +// Clear selection +conversations.clearSelection() +``` + + + + +```kotlin lines +CometChatConversations( + selectionMode = UIKitConstants.SelectionMode.MULTIPLE, + onSelection = { selectedList -> + updateToolbar(selectedList.size) + } +) +``` + + + + +--- + +## Global Events (CometChatEvents) + +Global events are emitted by UI Kit components when actions happen anywhere in the app. They use Kotlin `SharedFlow` for reactive, type-safe event distribution. Subscribe from any coroutine scope. + +### Event Flows + +| Flow | Sealed Class | Fires When | +| --- | --- | --- | +| `CometChatEvents.messageEvents` | `CometChatMessageEvent` | Messages sent, edited, deleted, reactions, typing | +| `CometChatEvents.callEvents` | `CometChatCallEvent` | Calls initiated, accepted, rejected, ended | +| `CometChatEvents.conversationEvents` | `CometChatConversationEvent` | Conversations deleted or updated | +| `CometChatEvents.groupEvents` | `CometChatGroupEvent` | Groups created, updated, members changed | +| `CometChatEvents.userEvents` | `CometChatUserEvent` | Users blocked/unblocked | +| `CometChatEvents.uiEvents` | `CometChatUIEvent` | UI-level events (panels, dialogs) | + +### Subscribing to Events + +```kotlin lines +import com.cometchat.uikit.core.events.CometChatEvents +import com.cometchat.uikit.core.events.CometChatMessageEvent + +// Subscribe in a ViewModel or lifecycle-aware scope +viewModelScope.launch { + CometChatEvents.messageEvents.collect { event -> + when (event) { + is CometChatMessageEvent.MessageSent -> { + // Handle sent message: event.message, event.status + } + is CometChatMessageEvent.MessageDeleted -> { + // Handle deleted message: event.message + } + is CometChatMessageEvent.MessageEdited -> { + // Handle edited message: event.message + } + is CometChatMessageEvent.ReactionAdded -> { + // Handle reaction: event.event + } + else -> { /* other message events */ } + } + } +} +``` + +### Emitting Events + +```kotlin lines +// Emit from anywhere — thread-safe +CometChatEvents.emitMessageEvent( + CometChatMessageEvent.MessageSent(message, MessageStatus.SUCCESS) +) + +CometChatEvents.emitCallEvent( + CometChatCallEvent.OutgoingCall(call) +) + +CometChatEvents.emitConversationEvent( + CometChatConversationEvent.ConversationDeleted(conversation) +) +``` + +### Key Event Types + +**Message Events:** + +| Event | Data | +| --- | --- | +| `MessageSent` | `message`, `status` | +| `MessageEdited` | `message`, `status` | +| `MessageDeleted` | `message` | +| `MessageRead` | `message` | +| `ReactionAdded` / `ReactionRemoved` | `event` (ReactionEvent) | +| `TypingStarted` / `TypingEnded` | `indicator` (TypingIndicator) | +| `MessagesDelivered` / `MessagesRead` | `receipt` (MessageReceipt) | + +**Call Events:** + +| Event | Data | +| --- | --- | +| `OutgoingCall` | `call` | +| `CallAccepted` | `call` | +| `CallRejected` | `call` | +| `CallEnded` | `call` | + +**Conversation Events:** + +| Event | Data | +| --- | --- | +| `ConversationDeleted` | `conversation` | +| `ConversationUpdated` | `conversation` | + +--- + +## Component vs Global Events + +| Aspect | Component Callbacks | Global Events | +| --- | --- | --- | +| Scope | Single component instance | App-wide | +| Registration | `setOnItemClick {}` or composable parameter | `CometChatEvents.*.collect {}` | +| Use case | Handle user interaction on a specific screen | Cross-component coordination | +| Example | Tap a conversation → navigate | Message sent → update conversation list | + +--- + +## Related + +- [Events Reference](/ui-kit/android/v6/events) — Full list of all event types. +- [Customization Overview](/ui-kit/android/v6/customization-overview) — SDK Listeners vs UIKit Events distinction. diff --git a/ui-kit/android/v6/customization-menu-options.mdx b/ui-kit/android/v6/customization-menu-options.mdx new file mode 100644 index 000000000..ff8ea7b08 --- /dev/null +++ b/ui-kit/android/v6/customization-menu-options.mdx @@ -0,0 +1,182 @@ +--- +title: "Menu & Options" +description: "Add, replace, or extend context menu actions on components." +--- + +Components provide context menus (e.g., long-press on a conversation or message). You can replace all options or append custom ones. + +--- + +## setOptions vs addOptions + +| Method | Behavior | +| --- | --- | +| `setOptions` | Replaces all default options with your custom list | +| `addOptions` | Appends your custom options to the existing defaults | + +Use `addOptions` to keep defaults (like "Delete") and add your own. Use `setOptions` for full control. + +--- + +## Adding Custom Options + + + + +```kotlin lines +import com.cometchat.uikit.kotlin.presentation.shared.popupmenu.CometChatPopupMenu + +conversations.addOptions { context, conversation -> + listOf( + CometChatPopupMenu.MenuItem( + id = "pin", + name = "Pin Conversation", + startIcon = ContextCompat.getDrawable(context, R.drawable.ic_pin), + onClick = { pinConversation(conversation) } + ) + ) +} +``` + + + + +```kotlin lines +import com.cometchat.uikit.compose.shared.views.popupmenu.MenuItem + +CometChatConversations( + addOptions = { context, conversation -> + listOf( + MenuItem( + id = "pin", + name = "Pin Conversation", + startIcon = painterResource(R.drawable.ic_pin), + onClick = { pinConversation(conversation) } + ) + ) + } +) +``` + + + + +--- + +## Replacing All Options + + + + +```kotlin lines +conversations.setOptions { context, conversation -> + listOf( + CometChatPopupMenu.MenuItem( + id = "archive", + name = "Archive", + startIcon = ContextCompat.getDrawable(context, R.drawable.ic_archive), + onClick = { archiveConversation(conversation) } + ), + CometChatPopupMenu.MenuItem( + id = "mute", + name = "Mute", + startIcon = ContextCompat.getDrawable(context, R.drawable.ic_mute), + onClick = { muteConversation(conversation) } + ) + ) +} +``` + + + + +```kotlin lines +CometChatConversations( + options = { context, conversation -> + listOf( + MenuItem( + id = "archive", + name = "Archive", + startIcon = painterResource(R.drawable.ic_archive), + onClick = { archiveConversation(conversation) } + ), + MenuItem( + id = "mute", + name = "Mute", + startIcon = painterResource(R.drawable.ic_mute), + onClick = { muteConversation(conversation) } + ) + ) + } +) +``` + + + + +--- + +## MenuItem Properties + + + + +`CometChatPopupMenu.MenuItem`: + +| Property | Type | Description | +| --- | --- | --- | +| `id` | `String` | Unique identifier | +| `name` | `String` | Display text | +| `startIcon` | `Drawable?` | Icon at the start | +| `endIcon` | `Drawable?` | Icon at the end | +| `startIconTint` | `@ColorInt Int` | Start icon tint | +| `textColor` | `@ColorInt Int` | Text color | +| `textAppearance` | `@StyleRes Int` | Text appearance | +| `onClick` | `(() -> Unit)?` | Click callback | + + + + +`MenuItem`: + +| Property | Type | Description | +| --- | --- | --- | +| `id` | `String` | Unique identifier | +| `name` | `String` | Display text | +| `startIcon` | `Painter?` | Icon at the start | +| `endIcon` | `Painter?` | Icon at the end | +| `startIconTint` | `Color?` | Start icon tint | +| `textColor` | `Color?` | Text color | +| `textStyle` | `TextStyle?` | Text style | +| `onClick` | `(() -> Unit)?` | Click callback | + + + + +Both modules provide convenience factory methods: + +```kotlin lines +// Simple menu item (no icons) +MenuItem.simple(id = "pin", name = "Pin") { /* onClick */ } + +// Menu item with icons (Compose) +MenuItem.withIcons(id = "pin", name = "Pin", startIcon = painterResource(R.drawable.ic_pin)) { /* onClick */ } +``` + +--- + +## Components with Menu Options + +| Component | Data passed to callback | +| --- | --- | +| `CometChatConversations` | `(Context, Conversation)` | +| `CometChatUsers` | `(Context, User)` | +| `CometChatGroups` | `(Context, Group)` | +| `CometChatGroupMembers` | `(Context, GroupMember)` | +| `CometChatCallLogs` | `(Context, CallLog)` | + +--- + +## Related + +- [Customization Overview](/ui-kit/android/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/android/v6/customization-overview.mdx b/ui-kit/android/v6/customization-overview.mdx new file mode 100644 index 000000000..f680af4b9 --- /dev/null +++ b/ui-kit/android/v6/customization-overview.mdx @@ -0,0 +1,235 @@ +--- +title: "Overview" +description: "Understand the layered architecture and discover all customization entry points in the CometChat Android UI Kit." +--- + +Every component in the UI Kit follows a layered architecture. Understanding these layers is the key to deep customization without rebuilding components from scratch. + +--- + +## Architecture Layers + +Each component is built from four layers, from outermost (UI) to innermost (data): + +| Layer | Role | Example | +| --- | --- | --- | +| View | Renders UI, handles user interaction, exposes setter methods | `CometChatConversations`, `CometChatMessageList` | +| ViewModel | Manages state, business logic, list operations, and SDK listeners | `CometChatConversationsViewModel`, `CometChatMessageListViewModel` | +| Repository | Abstracts data fetching — can be swapped for custom implementations | `ConversationsRepository`, `MessageListRepository` | +| DataSource | Direct SDK calls — the lowest layer that talks to CometChat servers | `ConversationsDataSourceImpl`, `MessageListDataSourceImpl` | + +```mermaid +block-beta + columns 1 + A["View Layer\nCometChatConversations / Compose\nUI rendering, styles, callbacks"] + B["ViewModel Layer\nCometChatConversationsViewModel\nState, ListOperations, SDK listeners"] + C["Repository Layer\nConversationsRepository\nData abstraction — swappable"] + D["DataSource Layer\nConversationsDataSourceImpl\nDirect CometChat SDK calls"] + + A --> B + B --> C + C --> D +``` + +The ViewModel lives in `chatuikit-core` and is shared by both Kotlin XML Views and Jetpack Compose. The View layer is module-specific. + +--- + +## Overriding the ViewModel + +Every component accepts an external ViewModel. This lets you subclass the default ViewModel to override behavior, or provide a completely custom one. + + + + +```kotlin lines +// 1. Subclass the ViewModel to override behavior +class MyConversationsViewModel( + getConversationsUseCase: GetConversationsUseCase, + deleteConversationUseCase: DeleteConversationUseCase, + refreshConversationsUseCase: RefreshConversationsUseCase +) : CometChatConversationsViewModel( + getConversationsUseCase, + deleteConversationUseCase, + refreshConversationsUseCase +) { + // Override any behavior here +} + +// 2. Create a factory with optional custom repository +val factory = CometChatConversationsViewModelFactory( + repository = MyCustomRepository() // or use default +) + +// 3. Create the ViewModel via ViewModelProvider +val viewModel = ViewModelProvider(this, factory) + .get(MyConversationsViewModel::class.java) + +// 4. Inject into the component +val conversations = findViewById(R.id.conversations) +conversations.setViewModel(viewModel) +``` + + + + +```kotlin lines +// 1. Subclass the ViewModel to override behavior +class MyConversationsViewModel( + getConversationsUseCase: GetConversationsUseCase, + deleteConversationUseCase: DeleteConversationUseCase, + refreshConversationsUseCase: RefreshConversationsUseCase +) : CometChatConversationsViewModel( + getConversationsUseCase, + deleteConversationUseCase, + refreshConversationsUseCase +) { + // Override any behavior here +} + +// 2. Create a factory with optional custom repository +val factory = CometChatConversationsViewModelFactory( + repository = MyCustomRepository() // or use default +) + +// 3. Create and pass to the component +val viewModel: MyConversationsViewModel = viewModel(factory = factory) + +CometChatConversations( + conversationsViewModel = viewModel +) +``` + + + + +--- + +## Overriding the Repository + +Each ViewModel is created via a Factory that accepts a custom Repository. Implement the repository interface to change how data is fetched. + +```kotlin lines +// 1. Implement the repository interface +class MyConversationsRepository : ConversationsRepository { + override suspend fun fetchConversations(request: ConversationsRequest): List { + // Custom data fetching logic — local DB, filtered API call, etc. + } + // ... implement other methods +} + +// 2. Create a factory with your custom repository +val factory = CometChatConversationsViewModelFactory( + repository = MyConversationsRepository() +) + +// 3. Create the ViewModel using the factory +val viewModel = ViewModelProvider(this, factory) + .get(CometChatConversationsViewModel::class.java) + +// 4. Set it on the component +conversations.setViewModel(viewModel) +``` + +Available repository interfaces in `chatuikit-core`: + +| Repository | Used by | +| --- | --- | +| `ConversationsRepository` | `CometChatConversationsViewModel` | +| `MessageListRepository` | `CometChatMessageListViewModel` | +| `MessageComposerRepository` | `CometChatMessageComposerViewModel` | +| `MessageHeaderRepository` | `CometChatMessageHeaderViewModel` | +| `UsersRepository` | `CometChatUsersViewModel` | +| `GroupsRepository` | `CometChatGroupsViewModel` | +| `GroupMembersRepository` | `CometChatGroupMembersViewModel` | +| `CallLogsRepository` | `CometChatCallLogsViewModel` | +| `CallButtonsRepository` | `CometChatCallButtonsViewModel` | +| `ReactionListRepository` | `CometChatReactionListViewModel` | +| `MessageInformationRepository` | `CometChatMessageInformationViewModel` | +| `StickerRepository` | `CometChatStickerKeyboardViewModel` | +| `PollRepository` | `CometChatCreatePollViewModel` | + +--- + +## ListOperations API + +All list-based ViewModels implement the `ListOperations` interface, giving you a consistent API to manipulate list data programmatically. + +### Available Operations + +| Method | Description | +| --- | --- | +| `addItem(item)` | Appends an item to the list | +| `addItems(items)` | Appends multiple items | +| `removeItem(item)` | Removes the first matching item | +| `removeItemAt(index)` | Removes item at index | +| `updateItem(item, predicate)` | Replaces the first item matching the predicate | +| `clearItems()` | Removes all items | +| `getItems()` | Returns a copy of all items | +| `getItemAt(index)` | Returns item at index (or null) | +| `getItemCount()` | Returns the item count | +| `moveItemToTop(item)` | Moves an item to index 0 (or adds it there) | +| `batch { }` | Performs multiple operations in a single emission | + +### Example + +```kotlin lines +// Batch operations — emits only once for all changes +viewModel.batch { + add(newConversation1) + add(newConversation2) + remove(oldConversation) + moveToTop(pinnedConversation) +} +``` + +Batch operations are critical for performance when handling rapid updates (e.g., multiple messages arriving simultaneously). + +--- + +## SDK Listeners vs UIKit Events + +ViewModels use two event systems for real-time updates: + +| Aspect | SDK Listeners | UIKit Events | +| --- | --- | --- | +| Source | CometChat server | UIKit components | +| Direction | Server → Client | Component → Component | +| Registration | `CometChat.add*Listener()` | `CometChatEvents.*Events.collect {}` | +| Purpose | Incoming messages, calls, presence | UI-initiated actions (message sent, call accepted) | + +Both are needed for full functionality. SDK listeners handle server-pushed events, UIKit events handle inter-component communication. + +--- + +## Customization Categories + + + + Replace specific regions of a component's UI (leading view, title, subtitle, trailing view). + + + Customize visual appearance using XML theme attributes or Compose style data classes. + + + Configure data fetching, observe state flows, and call mutation methods on the ViewModel. + + + Handle click events, selection mode, and global UI Kit events. + + + Replace or restyle the default empty, error, and loading state views. + + + Create custom text processors for hashtags, mentions, links, or any pattern. + + + Add, replace, or extend context menu actions and composer attachment options. + + + +--- + +## What's Next + +Start with [Styles](/ui-kit/android/v6/customization-styles) for quick visual changes, or [ViewModel & Data](/ui-kit/android/v6/customization-viewmodel-data) for behavior customization. diff --git a/ui-kit/android/v6/customization-state-views.mdx b/ui-kit/android/v6/customization-state-views.mdx new file mode 100644 index 000000000..9296e3703 --- /dev/null +++ b/ui-kit/android/v6/customization-state-views.mdx @@ -0,0 +1,189 @@ +--- +title: "State Views" +description: "Replace the default empty, error, and loading state views with custom layouts." +--- + +Components display state views when the list is empty, an error occurs, or data is loading. You can replace these with your own custom views. + +--- + +## State Types + +| State | When it shows | +| --- | --- | +| Loading | Data is being fetched | +| Empty | No data to display | +| Error | An error occurred during data fetching | + +--- + +## Replacing State Views + + + + +Each component accepts a `View?` for each state: + +```kotlin lines +// Custom empty view +val emptyView = LayoutInflater.from(context) + .inflate(R.layout.custom_empty_state, null) +conversations.setEmptyView(emptyView) + +// Custom error view +val errorView = LayoutInflater.from(context) + .inflate(R.layout.custom_error_state, null) +conversations.setErrorView(errorView) + +// Custom loading view +val loadingView = LayoutInflater.from(context) + .inflate(R.layout.custom_loading_state, null) +conversations.setLoadingView(loadingView) +``` + +Example custom empty layout: + +```xml res/layout/custom_empty_state.xml lines + + + + + + +``` + + + + +Each component accepts `@Composable` lambdas for each state: + +```kotlin lines +CometChatConversations( + emptyView = { + Column( + modifier = Modifier.fillMaxSize(), + horizontalAlignment = Alignment.CenterHorizontally, + verticalArrangement = Arrangement.Center + ) { + Icon( + painter = painterResource(R.drawable.ic_empty_conversations), + contentDescription = "No conversations", + modifier = Modifier.size(120.dp), + tint = CometChatTheme.colorScheme.iconTintSecondary + ) + Spacer(modifier = Modifier.height(16.dp)) + Text( + text = "No conversations yet", + style = CometChatTheme.typography.heading2Medium, + color = CometChatTheme.colorScheme.textColorPrimary + ) + } + }, + errorView = { onRetry -> + Column( + modifier = Modifier.fillMaxSize(), + horizontalAlignment = Alignment.CenterHorizontally, + verticalArrangement = Arrangement.Center + ) { + Text("Something went wrong") + Spacer(modifier = Modifier.height(8.dp)) + Button(onClick = onRetry) { + Text("Retry") + } + } + }, + loadingView = { + Box( + modifier = Modifier.fillMaxSize(), + contentAlignment = Alignment.Center + ) { + CircularProgressIndicator() + } + } +) +``` + +Note: the `errorView` lambda receives an `onRetry` callback you can wire to a retry button. + + + + +--- + +## Hiding State Views + + + + +Components like `CometChatMessageList` provide explicit hide methods: + +```kotlin lines +messageList.setHideLoadingState(true) +messageList.setHideEmptyState(true) +messageList.setHideErrorState(true) +``` + +For components that don't have dedicated hide methods (e.g., `CometChatConversations`), pass `null` to remove a custom state view: + +```kotlin lines +conversations.setEmptyView(null) +conversations.setErrorView(null) +conversations.setLoadingView(null) +``` + + + + +```kotlin lines +CometChatConversations( + hideEmptyState = true, + hideErrorState = true, + hideLoadingState = true +) + +CometChatMessageList( + hideEmptyState = true, + hideErrorState = true, + hideLoadingState = true +) +``` + + + + +--- + +## Components with State Views + +State views are available on all list-based components: + +| Component | States supported | +| --- | --- | +| `CometChatConversations` | Loading, Empty, Error | +| `CometChatUsers` | Loading, Empty, Error | +| `CometChatGroups` | Loading, Empty, Error | +| `CometChatGroupMembers` | Loading, Empty, Error | +| `CometChatCallLogs` | Loading, Empty, Error | +| `CometChatMessageList` | Loading, Empty, Error | + +--- + +## Related + +- [Customization Overview](/ui-kit/android/v6/customization-overview) — See all customization categories. +- [View Slots](/ui-kit/android/v6/customization-view-slots) — Replace specific regions of list items. diff --git a/ui-kit/android/v6/customization-styles.mdx b/ui-kit/android/v6/customization-styles.mdx new file mode 100644 index 000000000..afa2a6c40 --- /dev/null +++ b/ui-kit/android/v6/customization-styles.mdx @@ -0,0 +1,231 @@ +--- +title: "Styles" +description: "Customize component appearance using XML theme attributes, programmatic setters, or Compose style data classes." +--- + +The UI Kit supports multiple approaches to styling depending on your module. + +--- + +## Styling Approaches + + + + +Two ways to style components: + +1. **XML theme attributes** — declarative, app-wide theming via `themes.xml` +2. **Programmatic `CometChatTheme` setters** — runtime color/font overrides + +Programmatic setters take precedence over XML theme attributes. + +### XML Theme Hierarchy + +```xml themes.xml lines + + + + + + + + +``` + +### Programmatic Overrides + +```kotlin lines +// Override theme colors at runtime +CometChatTheme.setPrimaryColor(Color.parseColor("#6851D6")) +CometChatTheme.setBackgroundColor1(Color.parseColor("#FFFFFF")) +CometChatTheme.setTextColorPrimary(Color.parseColor("#141414")) +CometChatTheme.setTextColorSecondary(Color.parseColor("#727272")) +``` + + + + +Components accept a `style` parameter — a data class with `.default()` factory and `.copy()` for overrides: + +```kotlin lines +CometChatConversations( + style = CometChatConversationsStyle.default().copy( + backgroundColor = Color(0xFFF5F5F5), + titleTextColor = Color(0xFF6851D6), + itemStyle = CometChatConversationsItemStyle.default().copy( + avatarStyle = CometChatAvatarStyle.default().copy( + cornerRadius = 12.dp, + backgroundColor = Color(0xFFE8E0FF) + ), + badgeStyle = CometChatBadgeStyle.default().copy( + backgroundColor = Color(0xFFF76808) + ) + ) + ) +) +``` + +Global theme colors are provided via `CometChatTheme`: + +```kotlin lines +CometChatTheme( + colorScheme = lightColorScheme().copy( + primary = Color(0xFF6851D6), + backgroundColor1 = Color(0xFFFFFFFF), + textColorPrimary = Color(0xFF141414) + ) +) { + // All components inside use these colors as defaults +} +``` + + + + +--- + +## Font Customization + + + + +Override fonts at the theme level: + +```xml themes.xml lines + +``` + +| Attribute | Usage | +| --- | --- | +| `cometchatFontBold` | Headings, titles, emphasized text | +| `cometchatFontMedium` | Subtitles, secondary headings | +| `cometchatFontRegular` | Body text, descriptions, input fields | + + + + +Provide custom typography via `CometChatTheme`: + +```kotlin lines +CometChatTheme( + typography = CometChatTypography( + titleBold = TextStyle(fontFamily = myFontFamily, fontWeight = FontWeight.Bold, fontSize = 20.sp), + bodyRegular = TextStyle(fontFamily = myFontFamily, fontWeight = FontWeight.Normal, fontSize = 14.sp), + caption1Regular = TextStyle(fontFamily = myFontFamily, fontWeight = FontWeight.Normal, fontSize = 12.sp) + ) +) { + // All components use custom typography +} +``` + + + + +--- + +## CometChatTheme Color Tokens + +These tokens are available for programmatic override (Kotlin XML) or via `CometChatColorScheme` (Compose): + +### Colors + +| Token | Description | +| --- | --- | +| `primaryColor` | Brand color for buttons, links, highlights | +| `backgroundColor1` – `backgroundColor4` | Background levels | +| `textColorPrimary` / `Secondary` / `Tertiary` | Text colors | +| `textColorDisabled` / `White` / `Highlight` | Special text colors | +| `errorColor` / `successColor` / `warningColor` / `infoColor` | Alert colors | +| `strokeColorDefault` / `Light` / `Dark` / `Highlight` | Border colors | + +### Icon Tints + +| Token | Description | +| --- | --- | +| `iconTintPrimary` / `Secondary` / `Tertiary` | Icon tints | +| `iconTintWhite` / `Highlight` | Special icon tints | + +### Button Colors + +| Token | Description | +| --- | --- | +| `primaryButtonBackgroundColor` / `TextColor` / `IconTint` | Primary button | +| `secondaryButtonBackgroundColor` / `TextColor` / `IconTint` | Secondary button | + +--- + +## Per-Component Style Properties + +Each component has its own style data class with nested sub-component styles. Here's the pattern for key components: + +### CometChatConversations + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background | +| `titleTextColor` | Toolbar title color | +| `searchBoxStyle` | Search box styling | +| `itemStyle.avatarStyle` | Avatar in each row | +| `itemStyle.badgeStyle` | Unread badge | +| `itemStyle.dateStyle` | Timestamp | +| `itemStyle.receiptStyle` | Read receipts | +| `itemStyle.statusIndicatorStyle` | Online/offline indicator | +| `itemStyle.typingIndicatorStyle` | Typing indicator | + +### CometChatMessageList + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background | +| `incomingMessageBubbleStyle` | Incoming bubble appearance | +| `outgoingMessageBubbleStyle` | Outgoing bubble appearance | +| `actionBubbleStyle` | Group action bubbles | +| `callActionBubbleStyle` | Call action bubbles | + +### CometChatMessageComposer + +| Property | Description | +| --- | --- | +| `backgroundColor` | Composer background | +| `attachmentIconTint` | Attachment button tint | +| `voiceRecordingIconTint` | Voice recording button tint | +| `aiIconTint` | AI button tint | +| `sendButtonStyle` | Send button appearance | + +### CometChatMessageHeader + +| Property | Description | +| --- | --- | +| `backgroundColor` | Header background | +| `titleTextColor` | User/group name color | +| `subtitleTextColor` | Status/typing text color | +| `avatarStyle` | Avatar appearance | +| `callButtonsStyle` | Call button appearance | + +--- + +## Related + +- [Theme Introduction](/ui-kit/android/v6/theme-introduction) — Global theming reference. +- [Component Styling](/ui-kit/android/v6/component-styling) — Detailed per-component style examples with screenshots. +- [Color Resources](/ui-kit/android/v6/color-resources) — Default color palette reference. +- [Customization Overview](/ui-kit/android/v6/customization-overview) — All customization categories. diff --git a/ui-kit/android/v6/customization-text-formatters.mdx b/ui-kit/android/v6/customization-text-formatters.mdx new file mode 100644 index 000000000..ef9f0e3e0 --- /dev/null +++ b/ui-kit/android/v6/customization-text-formatters.mdx @@ -0,0 +1,176 @@ +--- +title: "Text Formatters" +description: "Create custom text processors for hashtags, mentions, links, or any pattern using the CometChatTextFormatter API." +--- + +Text formatters let you process message text with tracking characters, suggestion lists, and spannable transformations. Use them to add hashtag detection, custom mentions, link previews, or any text pattern processing. + +Both modules have their own `CometChatTextFormatter` class with the same API pattern: +- Kotlin XML: `com.cometchat.uikit.kotlin.shared.formatters.CometChatTextFormatter` +- Jetpack Compose: `com.cometchat.uikit.compose.presentation.shared.formatters.CometChatTextFormatter` + +--- + +## CometChatTextFormatter API + +The abstract class takes a `trackingCharacter` that triggers the formatter when typed in the composer (e.g., `@` for mentions, `#` for hashtags). + +### Key Override Methods + +| Method | Purpose | +| --- | --- | +| `search(context, queryString)` | Called when the user types after the tracking character. Fetch and display suggestions. | +| `onScrollToBottom()` | Called when the user scrolls to the bottom of the suggestion list. Use for pagination. | +| `prepareLeftMessageBubbleSpan(context, message, spannable)` | Apply spans to text in incoming message bubbles. | +| `prepareRightMessageBubbleSpan(context, message, spannable)` | Apply spans to text in outgoing message bubbles. | +| `prepareComposerSpan(context, message, spannable)` | Apply spans to text in the message composer. | +| `prepareConversationSpan(context, message, spannable)` | Apply spans to the last message preview in the conversation list. | +| `handlePreMessageSend(context, message)` | Modify a message before it's sent (attach metadata, transform text). | +| `onItemClick(context, suggestionItem, user, group)` | Called when the user selects a suggestion item. | + +### Suggestion System + +| Method | Description | +| --- | --- | +| `setSuggestionItemList(items)` | Set the list of suggestions to display | +| `setShowLoadingIndicator(show)` | Show/hide a loading spinner in the suggestion dropdown | +| `setDisableSuggestions(disable)` | Disable the suggestion dropdown entirely | + +--- + +## Example: Custom Hashtag Formatter + + + + + +```kotlin lines +import com.cometchat.uikit.kotlin.shared.formatters.CometChatTextFormatter +import com.cometchat.uikit.kotlin.shared.formatters.SuggestionItem + +class HashtagFormatter : CometChatTextFormatter('#') { + + override fun search(context: Context, queryString: String?) { + val suggestions = fetchHashtags(queryString) + setSuggestionItemList(suggestions) + } + + override fun onScrollToBottom() { + // Load more suggestions + } + + override fun prepareLeftMessageBubbleSpan( + context: Context, + baseMessage: BaseMessage, + spannable: SpannableStringBuilder + ): SpannableStringBuilder? { + applyHashtagSpans(spannable, context) + return spannable + } + + override fun prepareRightMessageBubbleSpan( + context: Context, + baseMessage: BaseMessage, + spannable: SpannableStringBuilder + ): SpannableStringBuilder? { + applyHashtagSpans(spannable, context) + return spannable + } +} +``` + + + + +```kotlin lines +import com.cometchat.uikit.compose.presentation.shared.formatters.CometChatTextFormatter +import com.cometchat.uikit.compose.presentation.shared.formatters.SuggestionItem + +class HashtagFormatter : CometChatTextFormatter('#') { + + override fun search(context: Context, queryString: String?) { + val suggestions = fetchHashtags(queryString) + setSuggestionItemList(suggestions) + } + + override fun onScrollToBottom() { + // Load more suggestions + } + + override fun prepareLeftMessageBubbleSpan( + context: Context, + baseMessage: BaseMessage, + spannable: SpannableStringBuilder + ): SpannableStringBuilder? { + applyHashtagSpans(spannable, context) + return spannable + } + + override fun prepareRightMessageBubbleSpan( + context: Context, + baseMessage: BaseMessage, + spannable: SpannableStringBuilder + ): SpannableStringBuilder? { + applyHashtagSpans(spannable, context) + return spannable + } +} +``` + + + + +--- + +## Registering Formatters + + + + +```kotlin lines +val hashtagFormatter = HashtagFormatter() +conversations.setTextFormatters(listOf(hashtagFormatter)) + +// Or on message composer / message list +messageComposer.setTextFormatters(listOf(hashtagFormatter)) +messageList.setTextFormatters(listOf(hashtagFormatter)) +``` + + + + +```kotlin lines +CometChatConversations( + textFormatters = listOf(HashtagFormatter()) +) + +CometChatMessageComposer( + textFormatters = listOf(HashtagFormatter()) +) + +CometChatMessageList( + textFormatters = listOf(HashtagFormatter()) +) +``` + + + + +--- + +## Built-in Formatter: CometChatMentionsFormatter + +The UI Kit includes `CometChatMentionsFormatter` as a built-in formatter that handles `@mention` detection, user suggestion lists, and spannable highlighting. It's automatically added to components when mentions are enabled. + +Each module has its own implementation: +- Kotlin XML: `com.cometchat.uikit.kotlin.shared.formatters.CometChatMentionsFormatter` +- Jetpack Compose: `com.cometchat.uikit.compose.presentation.shared.formatters.CometChatMentionsFormatter` + +See the [Mentions Formatter Guide](/ui-kit/android/v6/mentions-formatter-guide) for details. + +--- + +## Related + +- [Mentions Formatter Guide](/ui-kit/android/v6/mentions-formatter-guide) — Built-in mentions formatter reference. +- [Customization Overview](/ui-kit/android/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/android/v6/customization-view-slots.mdx b/ui-kit/android/v6/customization-view-slots.mdx new file mode 100644 index 000000000..eb27f7c3d --- /dev/null +++ b/ui-kit/android/v6/customization-view-slots.mdx @@ -0,0 +1,263 @@ +--- +title: "View Slots" +description: "Replace specific regions of a component's UI without rebuilding the entire component." +--- + +View Slots let you swap out specific parts of a component's list item — the avatar area, title, subtitle, trailing section, or the entire row — while keeping the rest of the component's behavior intact. + +--- + +## Available View Slots + +| Slot | Region | Description | +| --- | --- | --- | +| `leadingView` | Left section | Replaces the avatar / leading area | +| `titleView` | Title text | Replaces the name / title text | +| `subtitleView` | Subtitle text | Replaces the last message preview | +| `trailingView` | Right section | Replaces the timestamp / badge area | +| `itemView` | Entire row | Replaces the entire list item layout | + + +When you use `itemView`, all other slot setters are ignored since the entire row is replaced. + + +--- + +## How It Works + + + + +Each list-based component defines a `ViewHolderListener` abstract class with two callbacks: + +| Callback | Purpose | +| --- | --- | +| `createView(context, binding)` | Return a `View` for the slot. Called once when the ViewHolder is created. | +| `bindView(context, createdView, data, ...)` | Bind data to your custom view. Called every time the item is bound. | + +Pass the listener to the component via `setLeadingView()`, `setTitleView()`, `setSubtitleView()`, `setTrailingView()`, or `setItemView()`. + + + + +Each component accepts `@Composable` lambda parameters for each slot: + +```kotlin lines +CometChatConversations( + leadingView = { conversation, typingIndicator -> /* your composable */ }, + titleView = { conversation, typingIndicator -> /* your composable */ }, + subtitleView = { conversation, typingIndicator -> /* your composable */ }, + trailingView = { conversation, typingIndicator -> /* your composable */ }, + itemView = { conversation, typingIndicator -> /* your composable */ } +) +``` + +The lambda receives the data model directly — no `createView`/`bindView` split needed. + + + + +--- + +## Example: Custom Leading View + +Replace the default avatar with a custom view showing the first letter of the conversation name. + + + + +```kotlin lines +conversations.setLeadingView(object : ConversationsViewHolderListener() { + override fun createView( + context: Context, + binding: CometchatConversationsListItemsBinding + ): View { + return TextView(context).apply { + layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp) + gravity = Gravity.CENTER + textSize = 18f + setTextColor(Color.WHITE) + } + } + + override fun bindView( + context: Context, + createdView: View, + conversation: Conversation, + typingIndicator: TypingIndicator?, + holder: RecyclerView.ViewHolder, + conversations: List, + position: Int + ) { + val textView = createdView as TextView + val name = conversation.conversationWith?.name ?: "" + textView.text = name.firstOrNull()?.uppercase() ?: "?" + textView.background = GradientDrawable().apply { + shape = GradientDrawable.OVAL + setColor(Color.parseColor("#6851D6")) + } + } +}) +``` + + + + +```kotlin lines +CometChatConversations( + leadingView = { conversation, _ -> + val name = conversation.conversationWith?.name ?: "" + val initial = name.firstOrNull()?.uppercase() ?: "?" + + Box( + modifier = Modifier + .size(48.dp) + .background(Color(0xFF6851D6), CircleShape), + contentAlignment = Alignment.Center + ) { + Text( + text = initial, + color = Color.White, + fontSize = 18.sp + ) + } + } +) +``` + + + + +--- + +## Example: Custom Subtitle View + +Show a custom last message format in the subtitle area. + + + + +```kotlin lines +conversations.setSubtitleView(object : ConversationsViewHolderListener() { + override fun createView( + context: Context, + binding: CometchatConversationsListItemsBinding + ): View { + return TextView(context).apply { + maxLines = 1 + ellipsize = TextUtils.TruncateAt.END + } + } + + override fun bindView( + context: Context, + createdView: View, + conversation: Conversation, + typingIndicator: TypingIndicator?, + holder: RecyclerView.ViewHolder, + conversations: List, + position: Int + ) { + val textView = createdView as TextView + // Show typing indicator if available + if (typingIndicator != null) { + textView.text = "typing..." + return + } + textView.text = when (val msg = conversation.lastMessage) { + is TextMessage -> msg.text + is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}" + else -> "New conversation" + } + } +}) +``` + + + + +```kotlin lines +CometChatConversations( + subtitleView = { conversation, typingIndicator -> + val text = if (typingIndicator != null) { + "typing..." + } else { + when (val msg = conversation.lastMessage) { + is TextMessage -> msg.text + is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}" + else -> "New conversation" + } + } + + Text( + text = text, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + style = CometChatTheme.typography.bodyRegular, + color = CometChatTheme.colorScheme.textColorSecondary + ) + } +) +``` + + + + +--- + +## Toolbar Overflow Menu + +Inject a custom view into the component's toolbar area. This is separate from list item view slots. + + + + +```kotlin lines +val menuButton = ImageButton(context).apply { + setImageResource(R.drawable.ic_filter) + setOnClickListener { /* show filter dialog */ } +} +conversations.setOverflowMenu(menuButton) +``` + + + + +```kotlin lines +CometChatConversations( + overflowMenu = { + IconButton(onClick = { /* show filter dialog */ }) { + Icon( + painter = painterResource(R.drawable.ic_filter), + contentDescription = "Filter" + ) + } + } +) +``` + + + + +--- + +## Components with View Slots + +View slots are available on all list-based components: + +| Component | ViewHolderListener (Kotlin XML) | Composable Lambdas (Compose) | +| --- | --- | --- | +| `CometChatConversations` | `ConversationsViewHolderListener` | `(Conversation, TypingIndicator?) -> Unit` | +| `CometChatUsers` | `UsersViewHolderListener` | `(User) -> Unit` | +| `CometChatGroups` | `GroupsViewHolderListener` | `(Group) -> Unit` | +| `CometChatGroupMembers` | `GroupMembersViewHolderListener` | `(GroupMember) -> Unit` | +| `CometChatCallLogs` | `CallLogsViewHolderListener` | `(CallLog) -> Unit` | +| `CometChatReactionList` | `ReactionListViewHolderListener` | `(Reaction) -> Unit` | +| `CometChatMessageHeader` | `MessageHeaderViewHolderListener` | `(User?, Group?) -> Unit` | + +--- + +## Related + +- [Styles](/ui-kit/android/v6/customization-styles) — Customize visual appearance without replacing views. +- [Customization Overview](/ui-kit/android/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/android/v6/customization-viewmodel-data.mdx b/ui-kit/android/v6/customization-viewmodel-data.mdx new file mode 100644 index 000000000..8c51cde9f --- /dev/null +++ b/ui-kit/android/v6/customization-viewmodel-data.mdx @@ -0,0 +1,339 @@ +--- +title: "ViewModel & Data" +description: "Access and configure the ViewModel layer to customize data fetching, state management, and list operations." +--- + +Each component's ViewModel lives in `chatuikit-core` and manages data fetching, state transitions, real-time listeners, and list operations via `StateFlow`. The same ViewModel is shared by both Kotlin XML Views and Jetpack Compose modules. + +--- + +## Creating and Providing a ViewModel + +By default, each component creates its own ViewModel internally. To customize behavior, create the ViewModel externally using the factory and pass it to the component. + + + + +```kotlin lines +// 1. Create the factory (optionally with a custom repository) +val factory = CometChatConversationsViewModelFactory() + +// 2. Create the ViewModel using ViewModelProvider +val viewModel = ViewModelProvider(this, factory) + .get(CometChatConversationsViewModel::class.java) + +// 3. Configure the ViewModel before passing it +viewModel.setConversationsRequestBuilder( + ConversationsRequest.ConversationsRequestBuilder() + .setLimit(20) + .withTags(true) +) + +// 4. Pass it to the component +val conversations = findViewById(R.id.conversations) +conversations.setViewModel(viewModel) +``` + + + + +```kotlin lines +// 1. Create the factory (optionally with a custom repository) +val factory = CometChatConversationsViewModelFactory() + +// 2. Create the ViewModel using Compose's viewModel() +val viewModel: CometChatConversationsViewModel = viewModel(factory = factory) + +// 3. Pass it to the component +CometChatConversations( + conversationsViewModel = viewModel +) +``` + + + + +This pattern applies to all components — `CometChatUsers`, `CometChatGroups`, `CometChatMessageList`, `CometChatCallLogs`, etc. Each has a corresponding factory class. + +--- + +## State Observation + +ViewModels expose state via Kotlin `StateFlow` (not LiveData). The key state flows are: + +| StateFlow | Type | Description | +| --- | --- | --- | +| `uiState` | `StateFlow` | Current screen state: `Loading`, `Empty`, `Error(exception)`, `Content(list)` | +| `conversations` | `StateFlow>` | The current list of conversations | +| `typingIndicators` | `StateFlow>` | Active typing indicators by conversation ID | +| `deleteState` | `StateFlow` | Delete operation state: `Idle`, `InProgress`, `Success`, `Failure(exception)` | +| `playSoundEvent` | `SharedFlow` | Emits when a message sound should play | +| `scrollToTopEvent` | `SharedFlow` | Emits when the list should scroll to top | + +### UIState + +```kotlin lines +sealed class UIState { + object Loading : UIState() + object Empty : UIState() + data class Error(val exception: CometChatException) : UIState() + data class Content(val conversations: List) : UIState() +} +``` + +### Observing State + + + + +```kotlin lines +// Collect in a lifecycle-aware scope +lifecycleScope.launch { + repeatOnLifecycle(Lifecycle.State.STARTED) { + viewModel.uiState.collect { state -> + when (state) { + is UIState.Loading -> { /* show loading */ } + is UIState.Empty -> { /* show empty */ } + is UIState.Error -> { /* show error: state.exception */ } + is UIState.Content -> { /* data ready: state.conversations */ } + } + } + } +} +``` + + + + +```kotlin lines +val uiState by viewModel.uiState.collectAsState() + +when (uiState) { + is UIState.Loading -> CircularProgressIndicator() + is UIState.Empty -> Text("No conversations") + is UIState.Error -> Text("Error: ${(uiState as UIState.Error).exception.message}") + is UIState.Content -> { /* render list */ } +} +``` + + + + +--- + +## Configuring Data Fetching + +Pass a custom `ConversationsRequestBuilder` to control what data the component fetches. You can set it during ViewModel creation or directly on the component: + + + + +```kotlin lines +// Option 1: Set on the component directly +conversations.setConversationsRequestBuilder( + ConversationsRequest.ConversationsRequestBuilder() + .setLimit(20) + .setTags(listOf("important", "pinned")) + .withTags(true) +) + +// Option 2: Set on the ViewModel after creation +viewModel.setConversationsRequestBuilder( + ConversationsRequest.ConversationsRequestBuilder() + .setLimit(20) +) +``` + + + + +```kotlin lines +CometChatConversations( + conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder() + .setLimit(20) + .setTags(listOf("important", "pinned")) + .withTags(true) +) +``` + + + + + +Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. + + +--- + +## ListOperations API + +All list-based ViewModels implement `ListOperations`, giving you a consistent API to manipulate list data: + +```kotlin lines +// Add items +viewModel.addItem(conversation) +viewModel.addItems(conversations) + +// Remove items +viewModel.removeItem(conversation) +viewModel.removeItemAt(0) + +// Update items +viewModel.updateItem(updatedConversation) { + it.conversationId == updatedConversation.conversationId +} + +// Move to top +viewModel.moveItemToTop(importantConversation) + +// Query +val items = viewModel.getItems() +val count = viewModel.getItemCount() +val first = viewModel.getItemAt(0) + +// Clear +viewModel.clearItems() +``` + +### Batch Operations + +Perform multiple operations in a single emission — critical for performance with rapid updates: + +```kotlin lines +viewModel.batch { + add(newConversation1) + add(newConversation2) + remove(oldConversation) + moveToTop(pinnedConversation) +} +// Only one StateFlow emission for all four operations +``` + +--- + +## ViewModel Methods + +| Method | Description | +| --- | --- | +| `fetchConversations()` | Fetch the next page (pagination) | +| `refreshList()` | Clear and re-fetch from the server (silent refresh) | +| `deleteConversation(conversation)` | Delete a conversation via the SDK | +| `resetDeleteState()` | Reset delete state to `Idle` | +| `setConversationsRequestBuilder(builder)` | Set a custom request builder for filtering | +| `setDisableReceipt(disable)` | Disable read receipts | +| `setDisableSoundForMessages(disable)` | Disable message sounds | +| `setCustomSoundForMessage(rawRes)` | Set a custom sound resource | + +--- + +## Providing a Custom ViewModel + +Subclass the ViewModel to override behavior, then inject it: + +```kotlin lines +class MyConversationsViewModel( + getConversationsUseCase: GetConversationsUseCase, + deleteConversationUseCase: DeleteConversationUseCase, + refreshConversationsUseCase: RefreshConversationsUseCase +) : CometChatConversationsViewModel( + getConversationsUseCase, + deleteConversationUseCase, + refreshConversationsUseCase +) { + // Override list operations to add custom behavior + override fun addItem(item: Conversation) { + // Example: filter out blocked users before adding + val blockedUser = item.conversationWith as? User + if (blockedUser?.isBlockedByMe == true) return + super.addItem(item) + } + + override fun moveItemToTop(item: Conversation) { + // Example: log when a conversation is moved to top + Log.d("MyVM", "Moving ${item.conversationId} to top") + super.moveItemToTop(item) + } +} +``` + +Create it via the factory with a custom repository if needed: + +```kotlin lines +val factory = CometChatConversationsViewModelFactory( + repository = MyCustomRepository() +) +``` + + + + +```kotlin lines +val viewModel = ViewModelProvider(this, factory) + .get(CometChatConversationsViewModel::class.java) + +conversations.setViewModel(viewModel) +``` + + + + +```kotlin lines +val viewModel = viewModel(factory = factory) + +CometChatConversations( + conversationsViewModel = viewModel +) +``` + + + + +--- + +## Lifecycle Callbacks + +Intercept data loading events on the View: + + + + +```kotlin lines +conversations.setOnLoad { list -> + Log.d("Conversations", "Loaded ${list.size} conversations") +} + +conversations.setOnEmpty { + Log.d("Conversations", "No conversations found") +} + +conversations.setOnError { exception -> + Log.e("Conversations", "Error: ${exception.message}") +} +``` + + + + +```kotlin lines +CometChatConversations( + onLoad = { list -> + Log.d("Conversations", "Loaded ${list.size} conversations") + }, + onEmpty = { + Log.d("Conversations", "No conversations found") + }, + onError = { exception -> + Log.e("Conversations", "Error: ${exception.message}") + } +) +``` + + + + +--- + +## Related + +- [Customization Overview](/ui-kit/android/v6/customization-overview) — Architecture overview with repository and ListOperations details. +- [Events & Callbacks](/ui-kit/android/v6/customization-events) — Handle click events and global UI Kit events. diff --git a/ui-kit/android/v6/events.mdx b/ui-kit/android/v6/events.mdx new file mode 100644 index 000000000..3baae1188 --- /dev/null +++ b/ui-kit/android/v6/events.mdx @@ -0,0 +1,535 @@ +--- +title: "Events" +description: "Listen to UI Kit events for user actions, group changes, messages, and call lifecycle updates using CometChatEvents SharedFlow." +--- + + + +| Field | Value | +| --- | --- | +| Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` | +| Jetpack Compose | `com.cometchat:chatuikit-compose-android` | +| Import | `com.cometchat.uikit.core.events.CometChatEvents` | +| Event flows | `CometChatEvents.messageEvents`, `CometChatEvents.callEvents`, `CometChatEvents.conversationEvents`, `CometChatEvents.groupEvents`, `CometChatEvents.userEvents`, `CometChatEvents.uiEvents` | +| Pattern | Kotlin `SharedFlow` with sealed class event types — collect in `viewModelScope` or `lifecycleScope` | +| Purpose | Decoupled communication between UI Kit components — subscribe to event flows to react to changes without direct component references | + + + +Events enable a decoupled, flexible architecture in the CometChat UI Kit. Components emit events via the `CometChatEvents` singleton, and other parts of your application collect these `SharedFlow` streams to react without direct references between components. + +## When to use this + +- You need to update your UI when a user is blocked or unblocked. +- You need to respond to group actions such as member joins, kicks, bans, or ownership transfers. +- You need to track conversation deletions or updates in real time. +- You need to react to messages being sent, edited, deleted, or read. +- You need to handle call lifecycle events (outgoing, accepted, rejected, ended). +- You need to respond to UI-level events such as panel visibility changes or active chat changes. + +## Prerequisites + +- The `com.cometchat:chatuikit-kotlin-android` or `com.cometchat:chatuikit-compose-android` dependency added to your project. +- `CometChatUIKit.init()` called and completed successfully. +- A logged-in CometChat user (call `CometChatUIKit.login()` before collecting events). + +## CometChatEvents Singleton + +All events are accessed through the `CometChatEvents` singleton in `chatuikit-core`. Each domain has a dedicated `SharedFlow` that emits sealed class event types: + +```kotlin +import com.cometchat.uikit.core.events.CometChatEvents +``` + +| Flow | Sealed Class | Description | +|------|-------------|-------------| +| `CometChatEvents.messageEvents` | `MessageEvent` | Message sent, edited, deleted, read, reactions | +| `CometChatEvents.callEvents` | `CallEvent` | Call initiated, accepted, rejected, ended | +| `CometChatEvents.conversationEvents` | `ConversationEvent` | Conversation deleted, updated | +| `CometChatEvents.groupEvents` | `GroupEvent` | Group created, deleted, member changes | +| `CometChatEvents.userEvents` | `UserEvent` | User blocked, unblocked | +| `CometChatEvents.uiEvents` | `UIEvent` | Panel visibility, active chat changes | + +## API reference + +### Message Events + +`CometChatEvents.messageEvents` emits `MessageEvent` sealed class instances when messages are sent, edited, deleted, or read. + +**Event types:** + +| Event | Description | +| ----- | ----------- | +| `MessageEvent.Sent(message, status)` | Triggered when a message is sent. Status can be `inProgress` or `sent`. | +| `MessageEvent.Edited(message, status)` | Triggered when a message is edited. Status can be `inProgress` or `sent`. | +| `MessageEvent.Deleted(message)` | Triggered when a message is deleted. | +| `MessageEvent.Read(message)` | Triggered when a message is read. | +| `MessageEvent.LiveReaction(icon)` | Triggered when a live reaction is sent. | +| `MessageEvent.FormReceived(message)` | Triggered when a form message is received. | +| `MessageEvent.CardReceived(message)` | Triggered when a card message is received. | +| `MessageEvent.CustomInteractiveReceived(message)` | Triggered when a custom interactive message is received. | +| `MessageEvent.InteractionGoalCompleted(message)` | Triggered when an interaction goal is completed. | +| `MessageEvent.SchedulerReceived(message)` | Triggered when a scheduler message is received. | + +**Collecting events:** + + + +```kotlin +// In an Activity or Fragment — use lifecycleScope +lifecycleScope.launch { + CometChatEvents.messageEvents.collect { event -> + when (event) { + is MessageEvent.Sent -> { + val message = event.message + val status = event.status + // Update UI when message is sent + } + is MessageEvent.Edited -> { + val message = event.message + // Update UI when message is edited + } + is MessageEvent.Deleted -> { + val message = event.message + // Remove message from UI + } + is MessageEvent.Read -> { + val message = event.message + // Update read receipts + } + is MessageEvent.LiveReaction -> { + val icon = event.icon + // Show live reaction animation + } + is MessageEvent.FormReceived -> { /* Handle form message */ } + is MessageEvent.CardReceived -> { /* Handle card message */ } + is MessageEvent.CustomInteractiveReceived -> { /* Handle custom interactive */ } + is MessageEvent.InteractionGoalCompleted -> { /* Handle goal completion */ } + is MessageEvent.SchedulerReceived -> { /* Handle scheduler message */ } + } + } +} +``` + + + +```kotlin +@Composable +fun MessageEventsHandler() { + LaunchedEffect(Unit) { + CometChatEvents.messageEvents.collect { event -> + when (event) { + is MessageEvent.Sent -> { + val message = event.message + val status = event.status + // Update UI when message is sent + } + is MessageEvent.Edited -> { + val message = event.message + // Update UI when message is edited + } + is MessageEvent.Deleted -> { + val message = event.message + // Remove message from UI + } + is MessageEvent.Read -> { + val message = event.message + // Update read receipts + } + is MessageEvent.LiveReaction -> { + val icon = event.icon + // Show live reaction animation + } + is MessageEvent.FormReceived -> { /* Handle form message */ } + is MessageEvent.CardReceived -> { /* Handle card message */ } + is MessageEvent.CustomInteractiveReceived -> { /* Handle custom interactive */ } + is MessageEvent.InteractionGoalCompleted -> { /* Handle goal completion */ } + is MessageEvent.SchedulerReceived -> { /* Handle scheduler message */ } + } + } + } +} +``` + + + +> **What this does:** Collects the `messageEvents` SharedFlow and pattern-matches on the sealed class to handle each message lifecycle event. + +--- + +### Call Events + +`CometChatEvents.callEvents` emits `CallEvent` sealed class instances for call lifecycle changes. + +**Event types:** + +| Event | Description | +| ----- | ----------- | +| `CallEvent.OutgoingCall(call)` | Triggered when the logged-in user initiates an outgoing call. | +| `CallEvent.Accepted(call)` | Triggered when a call is accepted. | +| `CallEvent.Rejected(call)` | Triggered when a call is rejected. | +| `CallEvent.Ended(call)` | Triggered when a call is ended. | + +**Collecting events:** + + + +```kotlin +lifecycleScope.launch { + CometChatEvents.callEvents.collect { event -> + when (event) { + is CallEvent.OutgoingCall -> { + val call = event.call + // Handle outgoing call initiated + } + is CallEvent.Accepted -> { + val call = event.call + // Handle call accepted + } + is CallEvent.Rejected -> { + val call = event.call + // Handle call rejected + } + is CallEvent.Ended -> { + val call = event.call + // Handle call ended + } + } + } +} +``` + + + +```kotlin +@Composable +fun CallEventsHandler() { + LaunchedEffect(Unit) { + CometChatEvents.callEvents.collect { event -> + when (event) { + is CallEvent.OutgoingCall -> { + // Handle outgoing call initiated + } + is CallEvent.Accepted -> { + // Handle call accepted + } + is CallEvent.Rejected -> { + // Handle call rejected + } + is CallEvent.Ended -> { + // Handle call ended + } + } + } + } +} +``` + + + +--- + +### Conversation Events + +`CometChatEvents.conversationEvents` emits `ConversationEvent` sealed class instances when conversations are deleted or updated. + +**Event types:** + +| Event | Description | +| ----- | ----------- | +| `ConversationEvent.Deleted(conversation)` | Triggered when the logged-in user deletes a conversation. | +| `ConversationEvent.Updated(conversation)` | Triggered when there is an update in the conversation. | + +**Collecting events:** + + + +```kotlin +lifecycleScope.launch { + CometChatEvents.conversationEvents.collect { event -> + when (event) { + is ConversationEvent.Deleted -> { + val conversation = event.conversation + // Remove conversation from UI + } + is ConversationEvent.Updated -> { + val conversation = event.conversation + // Update conversation in UI + } + } + } +} +``` + + + +```kotlin +@Composable +fun ConversationEventsHandler() { + LaunchedEffect(Unit) { + CometChatEvents.conversationEvents.collect { event -> + when (event) { + is ConversationEvent.Deleted -> { + // Remove conversation from UI + } + is ConversationEvent.Updated -> { + // Update conversation in UI + } + } + } + } +} +``` + + + +--- + +### Group Events + +`CometChatEvents.groupEvents` emits `GroupEvent` sealed class instances when the logged-in user performs group-related actions. + +**Event types:** + +| Event | Description | +| ----- | ----------- | +| `GroupEvent.Created(group)` | Triggered when the logged-in user creates a group. | +| `GroupEvent.Deleted(group)` | Triggered when the logged-in user deletes a group. | +| `GroupEvent.Left(actionMessage, leftUser, leftGroup)` | Triggered when the logged-in user leaves a group. | +| `GroupEvent.MemberScopeChanged(actionMessage, updatedUser, scopeChangedTo, scopeChangedFrom, group)` | Triggered when a member's scope is changed. | +| `GroupEvent.MemberBanned(actionMessage, bannedUser, bannedBy, bannedFrom)` | Triggered when a member is banned from a group. | +| `GroupEvent.MemberKicked(actionMessage, kickedUser, kickedBy, kickedFrom)` | Triggered when a member is kicked from a group. | +| `GroupEvent.MemberUnBanned(actionMessage, unbannedUser, unBannedBy, unBannedFrom)` | Triggered when a member is unbanned from a group. | +| `GroupEvent.MemberJoined(joinedUser, joinedGroup)` | Triggered when the logged-in user joins a group. | +| `GroupEvent.MemberAdded(actionMessages, usersAdded, userAddedIn, addedBy)` | Triggered when members are added to a group. | +| `GroupEvent.OwnershipChanged(group, newOwner)` | Triggered when group ownership is transferred. | + +**Collecting events:** + + + +```kotlin +lifecycleScope.launch { + CometChatEvents.groupEvents.collect { event -> + when (event) { + is GroupEvent.Created -> { + val group = event.group + // Add new group to UI + } + is GroupEvent.Deleted -> { + val group = event.group + // Remove group from UI + } + is GroupEvent.Left -> { + val leftUser = event.leftUser + val leftGroup = event.leftGroup + // Handle user leaving group + } + is GroupEvent.MemberScopeChanged -> { + val updatedUser = event.updatedUser + val newScope = event.scopeChangedTo + // Update member scope in UI + } + is GroupEvent.MemberBanned -> { + val bannedUser = event.bannedUser + // Remove banned user from member list + } + is GroupEvent.MemberKicked -> { + val kickedUser = event.kickedUser + // Remove kicked user from member list + } + is GroupEvent.MemberUnBanned -> { + val unbannedUser = event.unbannedUser + // Handle unbanned user + } + is GroupEvent.MemberJoined -> { + val joinedUser = event.joinedUser + // Add user to member list + } + is GroupEvent.MemberAdded -> { + val usersAdded = event.usersAdded + // Add users to member list + } + is GroupEvent.OwnershipChanged -> { + val newOwner = event.newOwner + // Update group owner in UI + } + } + } +} +``` + + + +```kotlin +@Composable +fun GroupEventsHandler() { + LaunchedEffect(Unit) { + CometChatEvents.groupEvents.collect { event -> + when (event) { + is GroupEvent.Created -> { /* Add new group to UI */ } + is GroupEvent.Deleted -> { /* Remove group from UI */ } + is GroupEvent.Left -> { /* Handle user leaving group */ } + is GroupEvent.MemberScopeChanged -> { /* Update member scope */ } + is GroupEvent.MemberBanned -> { /* Remove banned user */ } + is GroupEvent.MemberKicked -> { /* Remove kicked user */ } + is GroupEvent.MemberUnBanned -> { /* Handle unbanned user */ } + is GroupEvent.MemberJoined -> { /* Add user to member list */ } + is GroupEvent.MemberAdded -> { /* Add users to member list */ } + is GroupEvent.OwnershipChanged -> { /* Update group owner */ } + } + } + } +} +``` + + + +--- + +### User Events + +`CometChatEvents.userEvents` emits `UserEvent` sealed class instances when the logged-in user blocks or unblocks another user. + +**Event types:** + +| Event | Description | +| ----- | ----------- | +| `UserEvent.Blocked(user)` | Triggered when the logged-in user blocks another user. | +| `UserEvent.Unblocked(user)` | Triggered when the logged-in user unblocks another user. | + +**Collecting events:** + + + +```kotlin +lifecycleScope.launch { + CometChatEvents.userEvents.collect { event -> + when (event) { + is UserEvent.Blocked -> { + val user = event.user + // Update UI to reflect blocked user + } + is UserEvent.Unblocked -> { + val user = event.user + // Update UI to reflect unblocked user + } + } + } +} +``` + + + +```kotlin +@Composable +fun UserEventsHandler() { + LaunchedEffect(Unit) { + CometChatEvents.userEvents.collect { event -> + when (event) { + is UserEvent.Blocked -> { + // Update UI to reflect blocked user + } + is UserEvent.Unblocked -> { + // Update UI to reflect unblocked user + } + } + } + } +} +``` + + + +--- + +### UI Events + +`CometChatEvents.uiEvents` emits `UIEvent` sealed class instances for UI-level actions such as panel visibility and active chat changes. + +**Event types:** + +| Event | Description | +| ----- | ----------- | +| `UIEvent.ShowPanel(id, alignment, view)` | Triggered to show an additional UI panel with custom elements. | +| `UIEvent.HidePanel(id, alignment)` | Triggered to hide a previously shown UI panel. | +| `UIEvent.ActiveChatChanged(id, message, user, group)` | Triggered when the active chat changes. | +| `UIEvent.OpenChat(user, group)` | Triggered to open a chat with a specific user or group. | + +**Collecting events:** + + + +```kotlin +lifecycleScope.launch { + CometChatEvents.uiEvents.collect { event -> + when (event) { + is UIEvent.ShowPanel -> { + val alignment = event.alignment + // Show custom UI panel + } + is UIEvent.HidePanel -> { + val alignment = event.alignment + // Hide custom UI panel + } + is UIEvent.ActiveChatChanged -> { + val user = event.user + val group = event.group + // React to active chat change + } + is UIEvent.OpenChat -> { + val user = event.user + val group = event.group + // Navigate to chat with user or group + } + } + } +} +``` + + + +```kotlin +@Composable +fun UIEventsHandler() { + LaunchedEffect(Unit) { + CometChatEvents.uiEvents.collect { event -> + when (event) { + is UIEvent.ShowPanel -> { /* Show custom UI panel */ } + is UIEvent.HidePanel -> { /* Hide custom UI panel */ } + is UIEvent.ActiveChatChanged -> { /* React to active chat change */ } + is UIEvent.OpenChat -> { /* Navigate to chat */ } + } + } + } +} +``` + + + +--- + +## Lifecycle Management + +Since `SharedFlow` collection is coroutine-based, lifecycle management is handled automatically: + +- In XML Views, use `lifecycleScope.launch` — the coroutine is cancelled when the lifecycle owner is destroyed. +- In Jetpack Compose, use `LaunchedEffect` — the coroutine is cancelled when the composable leaves the composition. + +No manual `removeListener` calls are needed, unlike the old static listener pattern. + +--- + +## Next steps + + + + UI Kit wrapper methods for initialization, authentication, and sending messages + + + Display and manage the conversation list, which reacts to conversation events + + + Display messages in a chat, which reacts to message events + + diff --git a/ui-kit/android/v6/extensions.mdx b/ui-kit/android/v6/extensions.mdx new file mode 100644 index 000000000..3c254551f --- /dev/null +++ b/ui-kit/android/v6/extensions.mdx @@ -0,0 +1,105 @@ +--- +title: "Extensions" +description: "Enable built-in CometChat extensions like reactions, stickers, polls, and link previews from the dashboard." +--- + + + +| Field | Value | +| --- | --- | +| Packages | `com.cometchat:chatuikit-kotlin-android` (Java), `com.cometchat:chatuikit-kotlin-android` (Kotlin XML), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) | +| Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` + Extensions enabled in [CometChat Dashboard](/fundamentals/extensions-overview) | +| Built-in extensions | Stickers, Polls, Collaborative Whiteboard, Collaborative Document, Message Translation, Link Preview, Thumbnail Generation, Profanity Filter | +| Key components | [Message Composer](/ui-kit/android/v6/message-composer) (Stickers, Polls, Whiteboard, Document), [Message List](/ui-kit/android/v6/message-list) (Translation, Link Preview, Thumbnails) | +| Activation | Enable each extension from the CometChat Dashboard — UI Kit auto-integrates them, no additional code required | +| Related | [Core Features](/ui-kit/android/v6/core-features), [AI Features](/ui-kit/android/v6/ai-features), [Extensions Overview](/fundamentals/extensions-overview) | + + + +CometChat’s UI Kit comes with built-in support for a wide variety of extensions that provide additional functionality. These extensions enhance the chatting experience, making it more interactive, secure, and efficient. + +Activating any of the extensions in CometChat is a simple process done through your application's dashboard. Refer to our guide for detailed information on [Extensions](/fundamentals/extensions-overview). + +Once you have successfully enabled the desired extension in your dashboard, it will be reflected in your CometChat application upon initialization and successful login. Please note that extension features will only be available if they are supported by the CometChat UI Kit. + +CometChat’s UI Kit offers built-in support for 8 extensions. This seamless integration makes it easy for you to enhance your chat application with engaging features without any extra coding effort. Just enable the desired extensions from the CometChat Dashboard, and they will be automatically reflected in the relevant components of your application, providing a richer and more engaging experience for your users. + +## Built-in Extensions + +Here's a guide on how you can enable and integrate these extensions: + +### Stickers + +The Stickers extension allows users to express their emotions more creatively. It adds a much-needed fun element to the chat by allowing users to send various pre-designed stickers. For a comprehensive understanding and guide on implementing and using the Sticker Extension, refer to our specific guide on the [Sticker Extension](/fundamentals/stickers). + +Once you have successfully activated the [Sticker Extension](/fundamentals/stickers) from your CometChat Dashboard, the feature will automatically be incorporated into the [Message Composer](/ui-kit/android/v6/message-composer) component of UI Kits. + + + + + +### Polls + +The Polls extension enhances group discussions by allowing users to create polls. Users can ask questions with a predefined list of answers, enabling a quick, organized way to gather group opinions. For a comprehensive understanding and guide on implementing and using the Polls Extension, refer to our specific guide on the [Polls Extension](/fundamentals/polls). + +Once you have successfully activated the [Polls Extension](/fundamentals/polls) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/ui-kit/android/v6/message-composer) component of UI Kits. + + + + + +### Collaborative Whiteboard + +The Collaborative Whiteboard extension facilitates real-time collaboration. Users can draw, brainstorm, and share ideas on a shared digital whiteboard. For a comprehensive understanding and guide on implementing and using the Collaborative Whiteboard Extension, refer to our specific guide on the [Collaborative Whiteboard Extension](/ui-kit/android/v6/message-bubble-styling#collaborative-bubble). + +Once you have successfully activated the [Collaborative Whiteboard Extension](/fundamentals/collaborative-whiteboard) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/ui-kit/android/v6/message-composer) component of UI Kits. + + + + + +### Collaborative Document + +With the Collaborative Document extension, users can work together on a shared document. This feature is essential for remote teams where document collaboration is a recurring requirement. For a comprehensive understanding and guide on implementing and using the Collaborative Document Extension, refer to our specific guide on the [Collaborative Document Extension](/ui-kit/android/v6/message-bubble-styling#collaborative-bubble). + +Once you have successfully activated the [Collaborative Document Extension](/fundamentals/collaborative-document) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/ui-kit/android/v6/message-composer) component of UI Kits. + + + + + +### Message Translation + +The Message Translation extension in CometChat is designed to translate any message into your local locale. It eliminates language barriers, making the chat more inclusive. For a comprehensive understanding and guide on implementing and using the Message Translation Extension, refer to our specific guide on the [Message Translation Extension](/fundamentals/message-translation). + +Once you have successfully activated the [Message Translation Extension](/fundamentals/message-translation) from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of [MessageList Component](/ui-kit/android/v6/message-list) component of UI Kits. + + + + + +### Link Preview + +The Link Preview extension provides a summary of the URL shared in the chat. It includes the title, a description, and a thumbnail image from the web page. For a comprehensive understanding and guide on implementing and using the Link Preview Extension, refer to our specific guide on the [Link Preview Extension](/fundamentals/link-preview). + +Once you have successfully activated the [Link Preview Extension](/fundamentals/link-preview) from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Component](/ui-kit/android/v6/message-list) component of UI Kits. + + + + + +### Thumbnail Generation + +The Thumbnail Generation extension automatically creates a smaller preview image whenever a larger image is shared, helping to reduce the upload/download time and bandwidth usage. For a comprehensive understanding and guide on implementing and using the Thumbnail Generation Extension, refer to our specific guide on the [Thumbnail Generation Extension](/fundamentals/thumbnail-generation). + +Once you have successfully activated the [Thumbnail Generation Extension](/fundamentals/thumbnail-generation) from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Component](/ui-kit/android/v6/message-list) component of UI Kits. + + + + + +### Profanity Filter + +The Profanity Filter extension helps in maintaining the chat decorum by censoring obscene and inappropriate words in the messages. For a comprehensive understanding and guide on implementing and using the Profanity Filter Extension, refer to our specific guide on the [Legacy Extensions](/moderation/legacy-extensions). + +Once you have successfully activated the Profanity Filter Extension from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Component](/ui-kit/android/v6/message-list) component of UI Kits. diff --git a/ui-kit/android/v6/getting-started-jetpack.mdx b/ui-kit/android/v6/getting-started-jetpack.mdx new file mode 100644 index 000000000..d43964e57 --- /dev/null +++ b/ui-kit/android/v6/getting-started-jetpack.mdx @@ -0,0 +1,257 @@ +--- +title: "Getting Started With Jetpack Compose UI Kit" +sidebarTitle: "Jetpack Compose" +description: "Step-by-step guide to integrate the CometChat Jetpack Compose UI Kit into your Android app." +--- + + + +| Field | Value | +| --- | --- | +| Package | `com.cometchat:chatuikit-compose-android` | +| UI Layer | Jetpack Compose (Material 3) | +| Init | `CometChatUIKit.init(context, UIKitSettings, callback)` — must resolve before `login()` | +| Login | `CometChatUIKit.login("UID", callback)` — must resolve before rendering components | +| Order | `init()` → `login()` → render. Breaking this order = blank screen | +| Auth Key | Dev/testing only. Use Auth Token in production | +| Calling | Optional. Add `com.cometchat:calls-sdk-android` to enable voice/video | +| Min SDK | Android 9.0 (API 28) | + + + +This guide walks you through integrating the CometChat Jetpack Compose UI Kit into an Android app. All UI components are native Compose composables built with Material 3. By the end you'll have a working chat UI. + +--- + +## Prerequisites + +You need three things from the [CometChat Dashboard](https://app.cometchat.com/): + +| Credential | Where to find it | +| --- | --- | +| App ID | Dashboard → Your App → Credentials | +| Auth Key | Dashboard → Your App → Credentials | +| Region | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) | + +You also need: +- Android Studio (Hedgehog or later recommended) +- An Android emulator or physical device running Android 9.0 (API 28) or higher +- Kotlin configured with Compose compiler plugin +- Gradle plugin 8.0+ with Kotlin DSL + + +Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](https://api-explorer.cometchat.com/) and use `loginWithAuthToken()`. Never ship Auth Keys in client code. + + +--- + +## Step 1 — Create an Android Project + +1. Open Android Studio and start a new project. +2. Choose Empty Activity (Compose) as the project template. +3. Set minimum API level to 28 or higher. + +--- + +## Step 2 — Install Dependencies + +### Add the CometChat Repository + +Add the CometChat Maven repository to your `settings.gradle.kts`: + +```kotlin settings.gradle.kts lines +dependencyResolutionManagement { + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) + repositories { + google() + mavenCentral() + maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/") + } +} +``` + +### Add Dependencies + + +Open your app-level `build.gradle.kts` and enable Compose, then add the dependencies: + +```kotlin build.gradle.kts lines +plugins { + alias(libs.plugins.android.application) + alias(libs.plugins.kotlin.android) + alias(libs.plugins.kotlin.compose) +} + +android { + // ... + buildFeatures { + compose = true + } + compileOptions { + sourceCompatibility = JavaVersion.VERSION_11 + targetCompatibility = JavaVersion.VERSION_11 + } + kotlinOptions { + jvmTarget = "11" + } +} + +dependencies { + // CometChat Jetpack Compose UI Kit + implementation("com.cometchat:chatuikit-compose-android:6.0.0") + + // (Optional) Voice/video calling + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + +--- + +## Step 3 — Initialize and Login + +Create your `MainActivity.kt` with the CometChat initialization and login flow. Since Compose uses a declarative approach, we track the auth state and render UI conditionally: + +```kotlin MainActivity.kt lines +import android.os.Bundle +import android.util.Log +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.activity.enableEdgeToEdge +import androidx.compose.foundation.layout.Box +import androidx.compose.foundation.layout.fillMaxSize +import androidx.compose.material3.CircularProgressIndicator +import androidx.compose.material3.Text +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import com.cometchat.chat.core.CometChat +import com.cometchat.chat.exceptions.CometChatException +import com.cometchat.chat.models.User +import com.cometchat.uikit.core.CometChatUIKit +import com.cometchat.uikit.core.UIKitSettings + +class MainActivity : ComponentActivity() { + + private val TAG = "MainActivity" + + private val appID = "APP_ID" // Replace with your App ID + private val region = "REGION" // Replace with your App Region + private val authKey = "AUTH_KEY" // Replace with your Auth Key + + private var isReady by mutableStateOf(false) + private var error by mutableStateOf(null) + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + enableEdgeToEdge() + + val uiKitSettings = UIKitSettings.UIKitSettingsBuilder() + .setRegion(region) + .setAppId(appID) + .setAuthKey(authKey) + .subscribePresenceForAllUsers() + .build() + + CometChatUIKit.init(this, uiKitSettings, object : CometChat.CallbackListener() { + override fun onSuccess(s: String?) { + Log.d(TAG, "Initialization completed successfully") + loginUser() + } + + override fun onError(e: CometChatException?) { + error = "Init failed: ${e?.message}" + } + }) + + setContent { + when { + error != null -> { + Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { + Text(error ?: "Unknown error") + } + } + !isReady -> { + Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { + CircularProgressIndicator() + } + } + else -> { + ChatApp() + } + } + } + } + + private fun loginUser() { + CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener() { + override fun onSuccess(user: User) { + Log.d(TAG, "Login successful: ${user.uid}") + isReady = true + } + + override fun onError(e: CometChatException) { + error = "Login failed: ${e.message}" + } + }) + } +} +``` + + +`init()` must resolve before you call `login()`. Calling `login()` before init completes will fail silently. + + +--- + +## Step 4 — Choose a Chat Experience + +Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide. + +### Conversation List + Message View + +Sequential navigation — conversation list as the entry point, tap a conversation to open a full-screen message view. + + + Step-by-step guide to build this layout with Jetpack Compose + + +--- + +### One-to-One / Group Chat + +Single chat window — no sidebar. Loads a specific user or group chat directly. Ideal for support chat, direct messages, or notification-driven flows. + + + Step-by-step guide to build this layout + + +--- + +### Tab-Based Chat + +Bottom navigation with tabs for Chats, Calls, Users, and Settings. + + + Step-by-step guide to build this layout + + +--- + +## Next Steps + + + + Browse all available UI Kit components + + + Customize colors, fonts, and styles + + + Chat features included out of the box + + + Common issues and fixes + + diff --git a/ui-kit/android/v6/getting-started-kotlin.mdx b/ui-kit/android/v6/getting-started-kotlin.mdx new file mode 100644 index 000000000..7a4988449 --- /dev/null +++ b/ui-kit/android/v6/getting-started-kotlin.mdx @@ -0,0 +1,231 @@ +--- +title: "Getting Started With Kotlin UI Kit" +sidebarTitle: "Kotlin (XML Views)" +description: "Step-by-step guide to integrate the CometChat Kotlin UI Kit with XML Views into your Android app." +--- + + + +| Field | Value | +| --- | --- | +| Package | `com.cometchat:chatuikit-kotlin-android` | +| UI Layer | Kotlin + XML Views (View Binding) | +| Init | `CometChatUIKit.init(context, UIKitSettings, callback)` — must resolve before `login()` | +| Login | `CometChatUIKit.login("UID", callback)` — must resolve before rendering components | +| Order | `init()` → `login()` → render. Breaking this order = blank screen | +| Auth Key | Dev/testing only. Use Auth Token in production | +| Calling | Optional. Add `com.cometchat:calls-sdk-android` to enable voice/video | +| Min SDK | Android 9.0 (API 28) | + + + +This guide walks you through integrating the CometChat Kotlin UI Kit into an Android app using XML Views and View Binding. By the end you'll have a working chat UI. + +--- + +## Prerequisites + +You need three things from the [CometChat Dashboard](https://app.cometchat.com/): + +| Credential | Where to find it | +| --- | --- | +| App ID | Dashboard → Your App → Credentials | +| Auth Key | Dashboard → Your App → Credentials | +| Region | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) | + +You also need: +- Android Studio installed +- An Android emulator or physical device running Android 9.0 (API 28) or higher +- Kotlin configured in your project +- Gradle plugin 8.0+ with Kotlin DSL + + +Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](https://api-explorer.cometchat.com/) and use `loginWithAuthToken()`. Never ship Auth Keys in client code. + + +--- + +## Step 1 — Create an Android Project + +1. Open Android Studio and start a new project. +2. Choose Empty Activity as the project template. +3. Select Kotlin as the language. +4. Set minimum API level to 28 or higher. + +--- + +## Step 2 — Install Dependencies + +### Add the CometChat Repository + +Add the CometChat Maven repository to your `settings.gradle.kts`: + +```kotlin settings.gradle.kts lines +dependencyResolutionManagement { + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) + repositories { + google() + mavenCentral() + maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/") + } +} +``` + +### Add Dependencies + + +Open your app-level `build.gradle.kts` and enable View Binding, then add the dependencies: + +```kotlin build.gradle.kts lines +android { + // ... + buildFeatures { + viewBinding = true + } + compileOptions { + sourceCompatibility = JavaVersion.VERSION_11 + targetCompatibility = JavaVersion.VERSION_11 + } + kotlinOptions { + jvmTarget = "11" + } +} + +dependencies { + // CometChat Kotlin UI Kit + implementation("com.cometchat:chatuikit-kotlin-android:6.0.0") + + // (Optional) Voice/video calling + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + +### Add AndroidX Support + +Verify this line is present in `gradle.properties`: + +```properties gradle.properties lines +android.enableJetifier=true +``` + +--- + +## Step 3 — Initialize and Login + +Create your `MainActivity.kt` with the CometChat initialization and login flow: + +```kotlin MainActivity.kt lines +import android.os.Bundle +import android.util.Log +import androidx.activity.enableEdgeToEdge +import androidx.appcompat.app.AppCompatActivity +import com.cometchat.chat.core.CometChat +import com.cometchat.chat.exceptions.CometChatException +import com.cometchat.chat.models.User +import com.cometchat.uikit.core.CometChatUIKit +import com.cometchat.uikit.core.UIKitSettings + +class MainActivity : AppCompatActivity() { + + private val TAG = "MainActivity" + + private val appID = "APP_ID" // Replace with your App ID + private val region = "REGION" // Replace with your App Region + private val authKey = "AUTH_KEY" // Replace with your Auth Key + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + enableEdgeToEdge() + + val uiKitSettings = UIKitSettings.UIKitSettingsBuilder() + .setRegion(region) + .setAppId(appID) + .setAuthKey(authKey) + .subscribePresenceForAllUsers() + .build() + + CometChatUIKit.init(this, uiKitSettings, object : CometChat.CallbackListener() { + override fun onSuccess(s: String?) { + Log.d(TAG, "Initialization completed successfully") + loginUser() + } + + override fun onError(e: CometChatException?) { + Log.e(TAG, "Initialization failed: ${e?.message}") + } + }) + } + + private fun loginUser() { + CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener() { + override fun onSuccess(user: User) { + Log.d(TAG, "Login successful: ${user.uid}") + + // Navigate to your chat screen after login + // startActivity(Intent(this@MainActivity, ConversationActivity::class.java)) + } + + override fun onError(e: CometChatException) { + Log.e(TAG, "Login failed: ${e.message}") + } + }) + } +} +``` + + +`init()` must resolve before you call `login()`. Calling `login()` before init completes will fail silently. + + +--- + +## Step 4 — Choose a Chat Experience + +Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide. + +### Conversation List + Message View + +Sequential navigation — conversation list as the entry point, tap a conversation to open a full-screen message view. + + + Step-by-step guide to build this layout with Kotlin XML Views + + +--- + +### One-to-One / Group Chat + +Single chat window — no sidebar. Loads a specific user or group chat directly. Ideal for support chat, direct messages, or notification-driven flows. + + + Step-by-step guide to build this layout + + +--- + +### Tab-Based Chat + +Bottom navigation with tabs for Chats, Calls, Users, and Settings. + + + Step-by-step guide to build this layout + + +--- + +## Next Steps + + + + Browse all available UI Kit components + + + Customize colors, fonts, and styles + + + Chat features included out of the box + + + Common issues and fixes + + diff --git a/ui-kit/android/v6/getting-started.mdx b/ui-kit/android/v6/getting-started.mdx new file mode 100644 index 000000000..3ee397a3f --- /dev/null +++ b/ui-kit/android/v6/getting-started.mdx @@ -0,0 +1,219 @@ +--- +title: "Getting Started With CometChat Android UI Kit" +sidebarTitle: "Integration" +description: "Install, configure, and launch the CometChat Android UI Kit in your app — choose Kotlin (XML Views) or Jetpack Compose." +--- + + + +| Field | Value | +| --- | --- | +| Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` v6.x | +| Jetpack Compose | `com.cometchat:chatuikit-compose-android` v6.x | +| Init | `CometChatUIKit.init(context, UIKitSettings, callback)` — must resolve before `login()` | +| Login | `CometChatUIKit.login("UID", callback)` — must resolve before rendering components | +| Order | `init()` → `login()` → render. Breaking this order = blank screen | +| Auth Key | Dev/testing only. Use Auth Token in production | +| Theme | Set `CometChatTheme.DayNight` as parent theme in `themes.xml` | +| Calling | Optional. Add `com.cometchat:calls-sdk-android` to enable voice/video | +| Min SDK | Android 7.0 (API 24) | + + + +This guide walks you through adding CometChat to an Android app. By the end you'll have a working chat UI. + + + + + +--- + +## Prerequisites + +You need three things from the [CometChat Dashboard](https://app.cometchat.com/): + +| Credential | Where to find it | +| --- | --- | +| App ID | Dashboard → Your App → Credentials | +| Auth Key | Dashboard → Your App → Credentials | +| Region | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) | + +You also need: +- Android Studio installed +- An Android emulator or physical device running Android 7.0 (API 24) or higher +- Java 8 or higher +- Gradle plugin 4.0.1 or later + + +Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](https://api-explorer.cometchat.com/) and use [`loginWithAuthToken()`](/ui-kit/android/v6/methods#login-using-auth-token). Never ship Auth Keys in client code. + + +--- + +## Step 1 — Create an Android Project + +1. Open Android Studio and start a new project. +2. Choose Empty Activity as the project template. +3. Enter a project name and choose Kotlin as the language. +4. Set minimum API level to 24 or higher. + +--- + +## Step 2 — Install Dependencies + +Add the CometChat repository and dependencies to your Gradle configuration. + +### Add the CometChat Repository + +Add the CometChat Maven repository to your project-level `settings.gradle.kts` file: + +```kotlin settings.gradle.kts +dependencyResolutionManagement { + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) + repositories { + google() + mavenCentral() + maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/") + } +} +``` + +### Add the CometChat Dependency + +Choose the module that matches your UI toolkit: + + + +Inside `libs.versions.toml`, add the versions: + +```toml libs.versions.toml +[versions] +cometchat-ui-kit = "6.0.0" +cometchat-calls-sdk = "5.0.0-beta.2" +``` + +Define the libraries — pick the module for your UI toolkit: + + + +```toml libs.versions.toml +[libraries] +cometchat-ui-kit = { module = "com.cometchat:chatuikit-kotlin-android", version.ref = "cometchat-ui-kit" } +cometchat-calls-sdk = { module = "com.cometchat:calls-sdk-android", version.ref = "cometchat-calls-sdk" } +``` + + + +```toml libs.versions.toml +[libraries] +cometchat-ui-kit = { module = "com.cometchat:chatuikit-compose-android", version.ref = "cometchat-ui-kit" } +cometchat-calls-sdk = { module = "com.cometchat:calls-sdk-android", version.ref = "cometchat-calls-sdk" } +``` + + + +Now, in your app-level `build.gradle.kts` file: + +```kotlin build.gradle.kts +dependencies { + implementation(libs.cometchat.ui.kit) + + // (Optional) Include if using voice/video calling features + implementation(libs.cometchat.calls.sdk) +} +``` + + + + +Open the app-level `build.gradle.kts` file and add the dependency for your chosen UI toolkit: + + + +```kotlin build.gradle.kts +dependencies { + implementation("com.cometchat:chatuikit-kotlin-android:6.0.0") + + // (Optional) Include if using voice/video calling features + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + + + +```kotlin build.gradle.kts +dependencies { + implementation("com.cometchat:chatuikit-compose-android:6.0.0") + + // (Optional) Include if using voice/video calling features + implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2") +} +``` + + + + + + +### Add AndroidX Support + +The Jetifier tool helps migrate legacy support libraries to AndroidX. Open `gradle.properties` and verify this line is present: + +```properties gradle.properties +android.enableJetifier=true +``` + +--- + +## Choose Your UI Toolkit + +The remaining integration steps (initialization, login, theming, and rendering components) differ depending on your chosen UI toolkit. Follow the guide that matches your project: + + + + Step-by-step integration using `chatuikit-kotlin` with XML layouts and ViewBinding + + + Step-by-step integration using `chatuikit-jetpack` with Composables + + + +--- + +## Build Your Own Chat Experience + +Need full control over the UI? Use individual components, customize themes, and wire up your own layouts. + + + + Working reference app to compare against + + + All prebuilt UI elements with customization options + + + Messaging, real-time updates, and other capabilities + + + Colors, fonts, dark mode, and custom styling + + + +--- + +## Next Steps + + + + Browse all prebuilt UI components + + + Customize colors, fonts, and styles + + + Chat features included out of the box + + + Common issues and fixes + + diff --git a/ui-kit/android/v6/group-members.mdx b/ui-kit/android/v6/group-members.mdx new file mode 100644 index 000000000..518c7b105 --- /dev/null +++ b/ui-kit/android/v6/group-members.mdx @@ -0,0 +1,966 @@ +--- +title: "Group Members" +description: "Scrollable list of all members in a group with search, avatars, names, scope badges, and online/offline status." +--- + +`CometChatGroupMembers` renders a scrollable list of all members in a specific group with real-time updates for membership changes, search, avatars, scope badges, and online/offline status indicators. Requires a `Group` object to load data. + + + + + +--- + +## Where It Fits + +`CometChatGroupMembers` is a list component. It renders all members of a given group and emits the selected `GroupMember` via `onItemClick`. Use it inside a group detail screen or as a standalone member browser. + + + + +```xml activity_group_members.xml lines + +``` + +```kotlin lines +val groupMembers = findViewById(R.id.group_members) +groupMembers.setGroup(group) + +groupMembers.setOnItemClick { groupMember -> + // Navigate to member profile or start DM +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + modifier = Modifier.fillMaxSize(), + onItemClick = { groupMember -> + // Navigate to member profile or start DM + } +) +``` + + + + +--- + +## Quick Start + + + + +Add to your layout XML: + +```xml lines + +``` + +Then set the group in your Activity: + +```kotlin lines +override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(R.layout.activity_group_members) + + val groupMembers = findViewById(R.id.group_members) + groupMembers.setGroup(group) // Required — must be called before data loads +} +``` + + + + +```kotlin lines +@Composable +fun GroupMembersScreen(group: Group) { + CometChatGroupMembers( + group = group, + modifier = Modifier.fillMaxSize() + ) +} +``` + + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + +Or in a Fragment: + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + val view = CometChatGroupMembers(requireContext()) + view.setGroup(group) + return view +} +``` + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + return ComposeView(requireContext()).apply { + setContent { CometChatGroupMembers(group = group) } + } +} +``` + + + + +--- + +## Filtering Group Members + + + + +Pass a `GroupMembersRequest.GroupMembersRequestBuilder` to control what loads: + +```kotlin lines +groupMembers.setGroupMembersRequestBuilder( + GroupMembersRequest.GroupMembersRequestBuilder(group.guid) + .setLimit(20) + .setScopes(listOf("admin", "moderator")) +) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + groupMembersRequestBuilder = GroupMembersRequest.GroupMembersRequestBuilder(group.guid) + .setLimit(20) + .setScopes(listOf("admin", "moderator")) +) +``` + + + + +### Filter Recipes + +| Recipe | Builder method | +| --- | --- | +| Limit per page | `.setLimit(10)` | +| Search by keyword | `.setSearchKeyword("john")` | +| Filter by scopes | `.setScopes(listOf("admin", "moderator"))` | + + +Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll. + + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemClick` + +Fires when a member row is tapped. Primary navigation hook. + + + + +```kotlin lines +groupMembers.setOnItemClick { groupMember -> + // Navigate to member profile +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + onItemClick = { groupMember -> + // Navigate to member profile + } +) +``` + + + + +> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation. + +#### `onItemLongClick` + +Fires when a member row is long-pressed. Use for additional actions like kick or ban. + + + + +```kotlin lines +groupMembers.setOnItemLongClick { groupMember -> + // Show context menu +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + onItemLongClick = { groupMember -> + // Show context menu + } +) +``` + + + + +#### `onBackPress` + +Fires when the user presses the back button in the toolbar. + + + + +```kotlin lines +groupMembers.setOnBackPress { + finish() +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + onBackPress = { /* navigate back */ } +) +``` + + + + +#### `onSearchClick` + +Fires when the user taps the search icon in the toolbar. + + + + +```kotlin lines +groupMembers.setOnSearchClick { + // Open search screen +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + onSearchClick = { /* open search */ } +) +``` + + + + +#### `onSelection` + +Fires when members are selected/deselected in multi-select mode. + + + + +```kotlin lines +groupMembers.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE) +groupMembers.setOnSelection { selectedMembers -> + updateToolbar(selectedMembers.size) +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + selectionMode = UIKitConstants.SelectionMode.MULTIPLE, + onSelection = { selectedMembers -> + updateToolbar(selectedMembers.size) + } +) +``` + + + + +#### `onError` + +Fires on internal errors (network failure, auth issue, SDK exception). + + + + +```kotlin lines +groupMembers.setOnError { exception -> + Log.e("GroupMembers", "Error: ${exception.message}") +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + onError = { exception -> + Log.e("GroupMembers", "Error: ${exception.message}") + } +) +``` + + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + + +```kotlin lines +groupMembers.setOnLoad { memberList -> + Log.d("GroupMembers", "Loaded ${memberList.size}") +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + onLoad = { memberList -> + Log.d("GroupMembers", "Loaded ${memberList.size}") + } +) +``` + + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + + +```kotlin lines +groupMembers.setOnEmpty { + Log.d("GroupMembers", "No members found") +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + onEmpty = { /* no members */ } +) +``` + + + + +### SDK Events (Real-Time, Automatic) + +The component listens to these SDK events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +| --- | --- | +| `onGroupMemberJoined` | Adds the new member to the list | +| `onGroupMemberLeft` | Removes the member from the list | +| `onGroupMemberKicked` | Removes the kicked member | +| `onGroupMemberBanned` | Removes the banned member | +| `onGroupMemberUnbanned` | Updates the member list | +| `onGroupMemberScopeChanged` | Updates the member's scope badge | +| `onMemberAddedToGroup` | Adds new members to the list | + +--- + +## Functionality + +| Method (Kotlin XML) | Compose Parameter | Description | +| --- | --- | --- | +| `setGroup(group)` | `group = group` | Set the group to load members for (required) | +| `setBackIconVisibility(View.VISIBLE)` | `hideBackIcon = false` | Toggle back button | +| `setToolbarVisibility(View.GONE)` | `hideToolbar = true` | Toggle toolbar | +| `setSearchBoxVisibility(View.GONE)` | `hideSearchBox = true` | Toggle search box | +| `setSeparatorVisibility(View.GONE)` | `hideSeparator = true` | Toggle list separators | +| `setSelectionMode(MULTIPLE)` | `selectionMode = MULTIPLE` | Enable selection mode | +| `setTitle("Members")` | `title = "Members"` | Custom toolbar title | +| `setSearchPlaceholderText("Find...")` | `searchPlaceholderText = "Find..."` | Search placeholder | + +--- + +## Custom View Slots + +### Leading View + +Replace the avatar / left section. + + + + + + + + +```kotlin lines +groupMembers.setLeadingView(object : GroupMembersViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return ImageView(context).apply { + layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp) + } + } + + override fun bindView( + context: Context, createdView: View, groupMember: GroupMember, + holder: RecyclerView.ViewHolder, memberList: List, position: Int + ) { + val imageView = createdView as ImageView + // Load member avatar + } +}) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + leadingView = { groupMember -> + CometChatAvatar( + imageUrl = groupMember.avatar, + name = groupMember.name + ) + } +) +``` + + + + +### Title View + +Replace the name / title text. + + + + + + + + +```kotlin lines +groupMembers.setTitleView(object : GroupMembersViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, groupMember: GroupMember, + holder: RecyclerView.ViewHolder, memberList: List, position: Int + ) { + (createdView as TextView).text = groupMember.name ?: "" + } +}) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + titleView = { groupMember -> + Text( + text = groupMember.name ?: "", + style = CometChatTheme.typography.heading4Medium + ) + } +) +``` + + + + +### Subtitle View + +Replace the subtitle text below the member's name. + + + + + + + + +```kotlin lines +groupMembers.setSubtitleView(object : GroupMembersViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END } + } + + override fun bindView( + context: Context, createdView: View, groupMember: GroupMember, + holder: RecyclerView.ViewHolder, memberList: List, position: Int + ) { + (createdView as TextView).text = "Scope: ${groupMember.scope}" + } +}) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + subtitleView = { groupMember -> + Text( + text = "Scope: ${groupMember.scope}", + maxLines = 1, + overflow = TextOverflow.Ellipsis + ) + } +) +``` + + + + +### Trailing View + +Replace the right section of each member item. + + + + + + + + +```kotlin lines +groupMembers.setTrailingView(object : GroupMembersViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, groupMember: GroupMember, + holder: RecyclerView.ViewHolder, memberList: List, position: Int + ) { + (createdView as TextView).text = groupMember.scope ?: "" + } +}) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + trailingView = { groupMember -> + Text(text = groupMember.scope ?: "") + } +) +``` + + + + +### Item View + +Replace the entire list item row. + + + + + + + + +```kotlin lines +groupMembers.setItemView(object : GroupMembersViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return LayoutInflater.from(context).inflate(R.layout.custom_member_item, null) + } + + override fun bindView( + context: Context, createdView: View, groupMember: GroupMember, + holder: RecyclerView.ViewHolder, memberList: List, position: Int + ) { + val avatar = createdView.findViewById(R.id.custom_avatar) + val title = createdView.findViewById(R.id.tvName) + title.text = groupMember.name + avatar.setAvatar(groupMember.name, groupMember.avatar) + } +}) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + itemView = { groupMember -> + Row( + modifier = Modifier.fillMaxWidth().padding(12.dp), + verticalAlignment = Alignment.CenterVertically + ) { + CometChatAvatar(imageUrl = groupMember.avatar, name = groupMember.name) + Spacer(Modifier.width(12.dp)) + Column { + Text(groupMember.name ?: "", style = CometChatTheme.typography.heading4Medium) + Text(groupMember.scope ?: "", style = CometChatTheme.typography.body3Regular) + } + } + } +) +``` + + + + +### State Views + + + + +```kotlin lines +groupMembers.setEmptyView(R.layout.custom_empty_view) +groupMembers.setErrorView(R.layout.custom_error_view) +groupMembers.setLoadingView(R.layout.custom_loading_view) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + emptyView = { Text("No members found") }, + errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } }, + loadingView = { CircularProgressIndicator() } +) +``` + + + + +### Overflow Menu + + + + +```kotlin lines +groupMembers.setOverflowMenu(ImageButton(context).apply { + setImageResource(R.drawable.ic_add_member) + setOnClickListener { /* add member */ } +}) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + overflowMenu = { + IconButton(onClick = { /* add member */ }) { + Icon(painterResource(R.drawable.ic_add_member), "Add Member") + } + } +) +``` + + + + +--- + +## Menu Options + + + + +```kotlin lines +// Replace all options +groupMembers.setOptions { context, groupMember -> + listOf( + CometChatPopupMenu.MenuItem(id = "kick", name = "Kick", onClick = { /* ... */ }), + CometChatPopupMenu.MenuItem(id = "ban", name = "Ban", onClick = { /* ... */ }) + ) +} + +// Append to defaults +groupMembers.setAddOptions { context, groupMember -> + listOf( + CometChatPopupMenu.MenuItem(id = "promote", name = "Promote", onClick = { /* ... */ }) + ) +} +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + options = { context, groupMember -> + listOf( + MenuItem(id = "kick", name = "Kick", onClick = { /* ... */ }), + MenuItem(id = "ban", name = "Ban", onClick = { /* ... */ }) + ) + }, + addOptions = { context, groupMember -> + listOf(MenuItem(id = "promote", name = "Promote", onClick = { /* ... */ })) + } +) +``` + + + + +--- + +## Common Patterns + +### Minimal list — hide all chrome + + + + +```kotlin lines +groupMembers.setToolbarVisibility(View.GONE) +groupMembers.setSearchBoxVisibility(View.GONE) +groupMembers.setSeparatorVisibility(View.GONE) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + hideToolbar = true, + hideSearchBox = true, + hideSeparator = true +) +``` + + + + +### Admins and moderators only + + + + +```kotlin lines +groupMembers.setGroupMembersRequestBuilder( + GroupMembersRequest.GroupMembersRequestBuilder(group.guid) + .setScopes(listOf("admin", "moderator")) +) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + groupMembersRequestBuilder = GroupMembersRequest.GroupMembersRequestBuilder(group.guid) + .setScopes(listOf("admin", "moderator")) +) +``` + + + + +--- + +## Advanced Methods + +### Programmatic Selection + + + + +```kotlin lines +// Enable selection +groupMembers.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE) + +// Select a member +groupMembers.selectGroupMember(member, UIKitConstants.SelectionMode.MULTIPLE) + +// Get selected +val selected = groupMembers.getSelectedGroupMembers() + +// Clear +groupMembers.clearSelection() +``` + + + + +Selection is managed via the `selectionMode` and `onSelection` parameters. The component handles selection state internally. + + + + +### ViewModel Access + +```kotlin lines +val factory = CometChatGroupMembersViewModelFactory() +val viewModel = ViewModelProvider(this, factory) + .get(CometChatGroupMembersViewModel::class.java) +``` + + + + +```kotlin lines +groupMembers.setViewModel(viewModel) +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + groupMembersViewModel = viewModel +) +``` + + + + +See [ViewModel & Data](/ui-kit/android/v6/customization-viewmodel-data) for ListOperations, state observation, and custom repositories. + +--- + +## Style + + + + + + + + +Define a custom style in `themes.xml`: + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +CometChatGroupMembers( + group = group, + style = CometChatGroupMembersStyle.default().copy( + backgroundColor = Color(0xFFF5F5F5), + titleTextColor = Color(0xFF141414), + itemStyle = CometChatGroupMembersItemStyle.default().copy( + backgroundColor = Color.White, + titleTextColor = Color(0xFF141414), + subtitleTextColor = Color(0xFF727272), + avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp), + statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy() + ) + ) +) +``` + + + + +### Style Properties + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background color | +| `titleTextColor` | Toolbar title color | +| `searchBoxStyle` | Search box appearance | +| `itemStyle.backgroundColor` | Row background | +| `itemStyle.selectedBackgroundColor` | Selected row background | +| `itemStyle.titleTextColor` | Member name color | +| `itemStyle.subtitleTextColor` | Subtitle text color | +| `itemStyle.separatorColor` | Row separator color | +| `itemStyle.avatarStyle` | Avatar appearance | +| `itemStyle.statusIndicatorStyle` | Online/offline indicator | + +See [Component Styling](/ui-kit/android/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + Browse and search available groups + + + Browse recent conversations + + + Detailed styling reference with screenshots + + + Custom ViewModels, repositories, and ListOperations + + diff --git a/ui-kit/android/v6/groups.mdx b/ui-kit/android/v6/groups.mdx new file mode 100644 index 000000000..80b72af5a --- /dev/null +++ b/ui-kit/android/v6/groups.mdx @@ -0,0 +1,974 @@ +--- +title: "Groups" +description: "Scrollable list of all available groups with search, avatars, names, and group type indicators." +--- + +`CometChatGroups` renders a scrollable list of all available groups with real-time updates for membership changes, search, avatars, and group type indicators (public, private, password-protected). + + + + + +--- + +## Where It Fits + +`CometChatGroups` is a list component. It renders all available groups and emits the selected `Group` via `onItemClick`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a group messaging layout. + + + + +```xml activity_chat.xml lines + +``` + +```kotlin lines +val groups = findViewById(R.id.groups) + +groups.setOnItemClick { group -> + messageHeader.setGroup(group) + messageList.setGroup(group) + messageComposer.setGroup(group) +} +``` + + + + +```kotlin lines +CometChatGroups( + modifier = Modifier.fillMaxSize(), + onItemClick = { group -> + messageHeader.setGroup(group) + messageList.setGroup(group) + messageComposer.setGroup(group) + } +) +``` + + + + +--- + +## Quick Start + + + + +Add to your layout XML: + +```xml lines + +``` + +Or programmatically: + +```kotlin lines +override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(CometChatGroups(this)) +} +``` + + + + +```kotlin lines +@Composable +fun GroupsScreen() { + CometChatGroups( + modifier = Modifier.fillMaxSize() + ) +} +``` + + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + +Or in a Fragment: + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + return CometChatGroups(requireContext()) +} +``` + + + + +```kotlin lines +override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View { + return ComposeView(requireContext()).apply { + setContent { CometChatGroups() } + } +} +``` + + + + +--- + +## Filtering Groups + + + + +Pass a `GroupsRequest.GroupsRequestBuilder` to control what loads: + +```kotlin lines +groups.setGroupsRequestBuilder( + GroupsRequest.GroupsRequestBuilder() + .joinedOnly(true) + .setLimit(20) +) +``` + + + + +```kotlin lines +CometChatGroups( + groupsRequestBuilder = GroupsRequest.GroupsRequestBuilder() + .joinedOnly(true) + .setLimit(20) +) +``` + + + + +### Filter Recipes + +| Recipe | Builder method | +| --- | --- | +| Joined only | `.joinedOnly(true)` | +| Limit per page | `.setLimit(10)` | +| Search by keyword | `.setSearchKeyWord("design")` | +| Filter by tags | `.setTags(listOf("vip"))` | +| With tags | `.withTags(true)` | + + +Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll. + + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemClick` + +Fires when a group row is tapped. Primary navigation hook. + + + + +```kotlin lines +groups.setOnItemClick { group -> + // Navigate to group chat screen +} +``` + + + + +```kotlin lines +CometChatGroups( + onItemClick = { group -> + // Navigate to group chat screen + } +) +``` + + + + +> Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation. + +#### `onItemLongClick` + +Fires when a group row is long-pressed. Use for additional actions like delete or leave. + + + + +```kotlin lines +groups.setOnItemLongClick { group -> + // Show context menu +} +``` + + + + +```kotlin lines +CometChatGroups( + onItemLongClick = { group -> + // Show context menu + } +) +``` + + + + +#### `onBackPress` + +Fires when the user presses the back button in the toolbar. + + + + +```kotlin lines +groups.setOnBackPress { + finish() +} +``` + + + + +```kotlin lines +CometChatGroups( + onBackPress = { /* navigate back */ } +) +``` + + + + +#### `onSearchClick` + +Fires when the user taps the search icon in the toolbar. + + + + +```kotlin lines +groups.setOnSearchClick { + // Open search screen +} +``` + + + + +```kotlin lines +CometChatGroups( + onSearchClick = { /* open search */ } +) +``` + + + + +#### `onSelection` + +Fires when groups are selected/deselected in multi-select mode. + + + + +```kotlin lines +groups.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE) +groups.setOnSelection { selectedGroups -> + updateToolbar(selectedGroups.size) +} +``` + + + + +```kotlin lines +CometChatGroups( + selectionMode = UIKitConstants.SelectionMode.MULTIPLE, + onSelection = { selectedGroups -> + updateToolbar(selectedGroups.size) + } +) +``` + + + + +#### `onError` + +Fires on internal errors (network failure, auth issue, SDK exception). + + + + +```kotlin lines +groups.setOnError { exception -> + Log.e("Groups", "Error: ${exception.message}") +} +``` + + + + +```kotlin lines +CometChatGroups( + onError = { exception -> + Log.e("Groups", "Error: ${exception.message}") + } +) +``` + + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + + +```kotlin lines +groups.setOnLoad { groupList -> + Log.d("Groups", "Loaded ${groupList.size}") +} +``` + + + + +```kotlin lines +CometChatGroups( + onLoad = { groupList -> + Log.d("Groups", "Loaded ${groupList.size}") + } +) +``` + + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + + +```kotlin lines +groups.setOnEmpty { + Log.d("Groups", "No groups found") +} +``` + + + + +```kotlin lines +CometChatGroups( + onEmpty = { /* no groups */ } +) +``` + + + + +### SDK Events (Real-Time, Automatic) + +The component listens to these SDK events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +| --- | --- | +| `onGroupMemberJoined` | Updates the group list when a member joins | +| `onGroupMemberLeft` | Updates the group list when a member leaves | +| `onGroupMemberKicked` | Updates the group list when a member is kicked | +| `onGroupMemberBanned` | Updates the group list when a member is banned | +| `onGroupMemberUnbanned` | Updates the group list when a member is unbanned | +| `onGroupMemberScopeChanged` | Updates the group list when a member's scope changes | +| `onMemberAddedToGroup` | Updates the group list when members are added | + +--- + +## Functionality + +| Method (Kotlin XML) | Compose Parameter | Description | +| --- | --- | --- | +| `setBackIconVisibility(View.VISIBLE)` | `hideBackIcon = false` | Toggle back button | +| `setToolbarVisibility(View.GONE)` | `hideToolbar = true` | Toggle toolbar | +| `setSearchBoxVisibility(View.GONE)` | `hideSearchBox = true` | Toggle search box | +| `setGroupTypeVisibility(View.GONE)` | `hideGroupType = true` | Toggle group type indicator | +| `setSeparatorVisibility(View.GONE)` | `hideSeparator = true` | Toggle list separators | +| `setSelectionMode(MULTIPLE)` | `selectionMode = MULTIPLE` | Enable selection mode | +| `setTitle("My Groups")` | `title = "My Groups"` | Custom toolbar title | +| `setSearchPlaceholderText("Find...")` | `searchPlaceholderText = "Find..."` | Search placeholder | + +--- + +## Custom View Slots + +### Leading View + +Replace the avatar / left section. + + + + + + + + +```kotlin lines +groups.setLeadingView(object : GroupsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return ImageView(context).apply { + layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp) + } + } + + override fun bindView( + context: Context, createdView: View, group: Group, + holder: RecyclerView.ViewHolder, groupList: List, position: Int + ) { + val imageView = createdView as ImageView + // Load group avatar + } +}) +``` + + + + +```kotlin lines +CometChatGroups( + leadingView = { group -> + CometChatAvatar( + imageUrl = group.icon, + name = group.name + ) + } +) +``` + + + + +### Title View + +Replace the name / title text. + + + + + + + + +```kotlin lines +groups.setTitleView(object : GroupsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, group: Group, + holder: RecyclerView.ViewHolder, groupList: List, position: Int + ) { + (createdView as TextView).text = group.name ?: "" + } +}) +``` + + + + +```kotlin lines +CometChatGroups( + titleView = { group -> + Text( + text = group.name ?: "", + style = CometChatTheme.typography.heading4Medium + ) + } +) +``` + + + + +### Subtitle View + +Replace the subtitle text below the group name. + + + + + + + + +```kotlin lines +groups.setSubtitleView(object : GroupsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END } + } + + override fun bindView( + context: Context, createdView: View, group: Group, + holder: RecyclerView.ViewHolder, groupList: List, position: Int + ) { + (createdView as TextView).text = "${group.membersCount} members" + } +}) +``` + + + + +```kotlin lines +CometChatGroups( + subtitleView = { group -> + Text( + text = "${group.membersCount} members", + maxLines = 1, + overflow = TextOverflow.Ellipsis + ) + } +) +``` + + + + +### Trailing View + +Replace the right section of each group item. + + + + + + + + +```kotlin lines +groups.setTrailingView(object : GroupsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return TextView(context) + } + + override fun bindView( + context: Context, createdView: View, group: Group, + holder: RecyclerView.ViewHolder, groupList: List, position: Int + ) { + (createdView as TextView).text = if (group.isJoined) "Joined" else "Join" + } +}) +``` + + + + +```kotlin lines +CometChatGroups( + trailingView = { group -> + Text(text = if (group.isJoined) "Joined" else "Join") + } +) +``` + + + + +### Item View + +Replace the entire list item row. + + + + + + + + +```kotlin lines +groups.setItemView(object : GroupsViewHolderListener() { + override fun createView(context: Context, binding: CometchatListBaseItemsBinding): View { + return LayoutInflater.from(context).inflate(R.layout.custom_group_item, null) + } + + override fun bindView( + context: Context, createdView: View, group: Group, + holder: RecyclerView.ViewHolder, groupList: List, position: Int + ) { + val avatar = createdView.findViewById(R.id.custom_avatar) + val title = createdView.findViewById(R.id.tvName) + title.text = group.name + avatar.setAvatar(group.name, group.icon) + } +}) +``` + + + + +```kotlin lines +CometChatGroups( + itemView = { group -> + Row( + modifier = Modifier.fillMaxWidth().padding(12.dp), + verticalAlignment = Alignment.CenterVertically + ) { + CometChatAvatar(imageUrl = group.icon, name = group.name) + Spacer(Modifier.width(12.dp)) + Column { + Text(group.name ?: "", style = CometChatTheme.typography.heading4Medium) + Text("${group.membersCount} members", style = CometChatTheme.typography.body3Regular) + } + } + } +) +``` + + + + +### State Views + + + + +```kotlin lines +groups.setEmptyView(R.layout.custom_empty_view) +groups.setErrorView(R.layout.custom_error_view) +groups.setLoadingView(R.layout.custom_loading_view) +``` + + + + +```kotlin lines +CometChatGroups( + emptyView = { Text("No groups found") }, + errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } }, + loadingView = { CircularProgressIndicator() } +) +``` + + + + +### Overflow Menu + + + + + + + + +```kotlin lines +groups.setOverflowMenu(ImageButton(context).apply { + setImageResource(R.drawable.ic_create_group) + setOnClickListener { /* create group */ } +}) +``` + + + + +```kotlin lines +CometChatGroups( + overflowMenu = { + IconButton(onClick = { /* create group */ }) { + Icon(painterResource(R.drawable.ic_create_group), "Create Group") + } + } +) +``` + + + + +--- + +## Menu Options + + + + +```kotlin lines +// Replace all options +groups.setOptions { context, group -> + listOf( + CometChatPopupMenu.MenuItem(id = "leave", name = "Leave", onClick = { /* ... */ }), + CometChatPopupMenu.MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ }) + ) +} + +// Append to defaults +groups.setAddOptions { context, group -> + listOf( + CometChatPopupMenu.MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ }) + ) +} +``` + + + + +```kotlin lines +CometChatGroups( + options = { context, group -> + listOf( + MenuItem(id = "leave", name = "Leave", onClick = { /* ... */ }), + MenuItem(id = "delete", name = "Delete", onClick = { /* ... */ }) + ) + }, + addOptions = { context, group -> + listOf(MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ })) + } +) +``` + + + + +--- + +## Common Patterns + +### Minimal list — hide all chrome + + + + +```kotlin lines +groups.setToolbarVisibility(View.GONE) +groups.setSearchBoxVisibility(View.GONE) +groups.setGroupTypeVisibility(View.GONE) +``` + + + + +```kotlin lines +CometChatGroups( + hideToolbar = true, + hideSearchBox = true, + hideGroupType = true +) +``` + + + + +### Joined groups only + + + + +```kotlin lines +groups.setGroupsRequestBuilder( + GroupsRequest.GroupsRequestBuilder() + .joinedOnly(true) +) +``` + + + + +```kotlin lines +CometChatGroups( + groupsRequestBuilder = GroupsRequest.GroupsRequestBuilder() + .joinedOnly(true) +) +``` + + + + +### Tagged groups + + + + +```kotlin lines +groups.setGroupsRequestBuilder( + GroupsRequest.GroupsRequestBuilder() + .setTags(listOf("support")) + .withTags(true) +) +``` + + + + +```kotlin lines +CometChatGroups( + groupsRequestBuilder = GroupsRequest.GroupsRequestBuilder() + .setTags(listOf("support")) + .withTags(true) +) +``` + + + + +--- + +## Advanced Methods + +### Programmatic Selection + + + + +```kotlin lines +// Enable selection +groups.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE) + +// Select a group +groups.selectGroup(group, UIKitConstants.SelectionMode.MULTIPLE) + +// Get selected +val selected = groups.getSelectedGroups() + +// Clear +groups.clearSelection() +``` + + + + +Selection is managed via the `selectionMode` and `onSelection` parameters. The component handles selection state internally. + + + + +### ViewModel Access + +```kotlin lines +val factory = CometChatGroupsViewModelFactory() +val viewModel = ViewModelProvider(this, factory) + .get(CometChatGroupsViewModel::class.java) +``` + + + + +```kotlin lines +groups.setViewModel(viewModel) +``` + + + + +```kotlin lines +CometChatGroups( + groupsViewModel = viewModel +) +``` + + + + +See [ViewModel & Data](/ui-kit/android/v6/customization-viewmodel-data) for ListOperations, state observation, and custom repositories. + +--- + +## Style + + + + + + + + +Define a custom style in `themes.xml`: + +```xml themes.xml lines + + + + + +``` + + + + +```kotlin lines +CometChatGroups( + style = CometChatGroupsStyle.default().copy( + backgroundColor = Color(0xFFF5F5F5), + titleTextColor = Color(0xFF141414), + itemStyle = CometChatGroupsItemStyle.default().copy( + backgroundColor = Color.White, + titleTextColor = Color(0xFF141414), + subtitleTextColor = Color(0xFF727272), + avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp), + statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy() + ) + ) +) +``` + + + + +### Style Properties + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background color | +| `titleTextColor` | Toolbar title color | +| `searchBoxStyle` | Search box appearance | +| `itemStyle.backgroundColor` | Row background | +| `itemStyle.selectedBackgroundColor` | Selected row background | +| `itemStyle.titleTextColor` | Group name color | +| `itemStyle.subtitleTextColor` | Subtitle text color | +| `itemStyle.separatorColor` | Row separator color | +| `itemStyle.avatarStyle` | Avatar appearance | +| `itemStyle.statusIndicatorStyle` | Group type indicator | + +See [Component Styling](/ui-kit/android/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + View and manage group members + + + Browse recent conversations + + + Detailed styling reference with screenshots + + + Custom ViewModels, repositories, and ListOperations + + diff --git a/ui-kit/android/v6/guide-ai-agent.mdx b/ui-kit/android/v6/guide-ai-agent.mdx new file mode 100644 index 000000000..2da496105 --- /dev/null +++ b/ui-kit/android/v6/guide-ai-agent.mdx @@ -0,0 +1,419 @@ +--- +title: "AI Agent Integration" +sidebarTitle: "AI Agent Integration" +description: "Enable AI-powered conversational assistance with chat history, contextual responses, and seamless handoffs." +--- + + + +| Field | Value | +| --- | --- | +| Packages | `com.cometchat:chatuikit-kotlin-android` · `com.cometchat:chatuikit-compose-android` | +| Key components | `CometChatAIAssistantChatHistory`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader` | +| Purpose | Enable AI-powered conversational assistance with chat history, contextual responses, and seamless handoffs. | +| Related | [AI Assistant Chat History](/ui-kit/android/v6/ai-assistant-chat-history), [AI Features](/ui-kit/android/v6/ai-features), [All Guides](/ui-kit/android/v6/guide-overview) | + + + +Enable intelligent conversational AI capabilities in your Android app using CometChat UIKit v6 with AI Agent integration: + +- **AI Assistant Chat History** +- **Chat History Management** +- **Contextual Responses** +- **Agent Detection** +- **Seamless Handoffs** + +Transform your chat experience with AI-powered assistance that provides intelligent responses and seamless integration with your existing chat infrastructure. + +## Overview + +Users can interact with AI agents through a dedicated chat interface that: + +- Provides intelligent responses based on conversation context. +- Maintains chat history for continuity. +- Seamlessly integrates with your existing user chat system. + +The AI Agent chat interface provides a familiar messaging experience enhanced with AI capabilities, accessible through your main chat flow or as a standalone feature. + + + + + +## Prerequisites + +- Android Studio project with `com.cometchat:chatuikit-kotlin-android` or `com.cometchat:chatuikit-compose-android` in `build.gradle`. +- Internet permission in `AndroidManifest.xml`. +- Valid CometChat **App ID**, **Region**, and **Auth Key** configured via `UIKitSettings`. +- User logged in with `CometChatUIKit.login()`. +- AI Agent configured in your CometChat dashboard. + +## Components + +| Component / Class | Role | +|:----------------------------------|:-----| +| `AIAssistantChatActivity` | Main activity for AI agent chat. | +| `CometChatAIAssistantChatHistory` | Displays previous AI conversation history. | +| `CometChatMessageList` | Shows AI messages with threading support. | +| `CometChatMessageComposer` | Input interface for AI conversations. | +| `CometChatMessageHeader` | Header with AI agent info and controls. | + +## Integration Steps + +### Step 1 — Activity / Screen Setup + +Create the AI Assistant chat screen with proper layout configuration. + + + +```kotlin AIAssistantChatActivity.kt lines +class AIAssistantChatActivity : AppCompatActivity() { + private lateinit var binding: ActivityAiAssistantChatBinding + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + binding = ActivityAiAssistantChatBinding.inflate(layoutInflater) + setContentView(binding.root) + + val messageJson = intent.getStringExtra(getString(R.string.app_base_message)) + val userJson = intent.getStringExtra(getString(R.string.app_user)) + + var user: User? = null + var parentMessage: BaseMessage? = null + + if (!userJson.isNullOrEmpty()) + user = User.fromJson(userJson) + if (!messageJson.isNullOrEmpty()) + parentMessage = BaseMessage.processMessage(JSONObject(messageJson)) + + initializeComponents(user, parentMessage) + initClickListeners() + } + + private fun initializeComponents(user: User?, parentMessage: BaseMessage?) { + user?.let { + binding.messageHeader.user = it + binding.messageList.user = it + binding.messageComposer.user = it + } + + if (parentMessage != null) { + binding.messageList.setParentMessage(parentMessage.getId()) + binding.messageComposer.setParentMessageId(parentMessage.getId()) + } + + binding.messageList.setStyle(R.style.CustomCometChatMessageListStyle) + binding.messageComposer.style = R.style.CustomMessageComposerStyle + } +} +``` + + + +```kotlin AIAssistantChatScreen.kt lines +import com.cometchat.uikit.compose.presentation.messageheader.ui.CometChatMessageHeader +import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList +import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer + +@Composable +fun AIAssistantChatScreen( + user: User, + parentMessageId: Int? = null, + onNewChatClick: () -> Unit = {}, + onChatHistoryClick: () -> Unit = {} +) { + Column(modifier = Modifier.fillMaxSize()) { + CometChatMessageHeader( + user = user + ) + + CometChatMessageList( + user = user, + parentMessageId = parentMessageId ?: 0, + modifier = Modifier.weight(1f) + ) + + CometChatMessageComposer( + user = user, + parentMessageId = parentMessageId ?: 0 + ) + } +} +``` + + + +**File reference:** +[`AIAssistantChatActivity.kt`](https://github.com/cometchat/cometchat-uikit-android/blob/v6/ai-sample-app/src/main/java/com/cometchat/ai/sampleapp/ui/activity/AIAssistantChatActivity.kt) + +### Step 2 — Layout (XML Views only) + +Add `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to your layout. + +```xml activity_ai_assistant_chat.xml lines + + + + + + + + + +``` + +> **Note:** In Jetpack Compose, layout is handled declaratively in the composable function — no XML needed. + +### Step 3 — Style of Message List & Composer (XML Views only) + +Define custom styles for the message list and composer to differentiate AI agent chats. + +```xml themes.xml lines + + + + + +``` + +> **Jetpack Compose:** Pass a custom style object via the `style` parameter on each composable instead of XML styles. + +### Step 4 — Initialize click listeners + +Initialize click listeners to handle new chat creation and chat history access. + + + +```kotlin AIAssistantChatActivity.kt lines +private fun initClickListeners() { + // New chat creation + binding.messageHeader.setNewChatButtonClick { + Utils.hideKeyBoard(this@AIAssistantChatActivity, binding.root) + val intent = Intent(this@AIAssistantChatActivity, AIAssistantChatActivity::class.java) + intent.putExtra(getString(R.string.app_user), user.toJson().toString()) + startActivity(intent) + finish() + } + + // Chat history access + binding.messageHeader.setChatHistoryButtonClick { + val intent = Intent(this@AIAssistantChatActivity, AIAssistantChatHistoryActivity::class.java) + intent.putExtra(getString(R.string.app_user), user.toJson().toString()) + startActivity(intent) + } +} +``` + + + +```kotlin AIAssistantChatScreen.kt lines +// In Jetpack Compose, pass callbacks as lambda parameters: +AIAssistantChatScreen( + user = aiUser, + onNewChatClick = { + // Navigate to a fresh AI chat screen + navController.navigate("ai_chat/${Gson().toJson(aiUser)}") + }, + onChatHistoryClick = { + // Navigate to chat history screen + navController.navigate("ai_chat_history/${Gson().toJson(aiUser)}") + } +) +``` + + + +### Step 5 — AI Assistant Chat History screen + +Create a screen to host the `CometChatAIAssistantChatHistory` component. + + + +```kotlin AIAssistantChatHistoryActivity.kt lines +class AIAssistantChatHistoryActivity : AppCompatActivity() { + private lateinit var binding: ActivityAiAssistantChatHistoryBinding + private var user: User? = null + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + binding = ActivityAiAssistantChatHistoryBinding.inflate(layoutInflater) + setContentView(binding.root) + + val userJson = intent.getStringExtra(getString(R.string.app_user)) + + if (userJson != null && userJson.isNotEmpty()) { + user = User.fromJson(userJson) + binding.cometchatAiAssistantChatHistory.setUser(user) + } + + initClickListeners() + } + + private fun initClickListeners() { + binding.cometchatAiAssistantChatHistory.setOnItemClickListener { view, position, message -> + val appEntity = message.getReceiver() + if (appEntity is User) { + user = appEntity + val intent = Intent(this, AIAssistantChatActivity::class.java) + intent.putExtra(getString(R.string.app_user), appEntity.toJson().toString()) + intent.putExtra(getString(R.string.app_base_message), message.getRawMessage().toString()) + startActivity(intent) + finish() + } + } + + binding.cometchatAiAssistantChatHistory.setOnNewChatClickListener { + val intent = Intent(this, AIAssistantChatActivity::class.java) + intent.putExtra(getString(R.string.app_user), user!!.toJson().toString()) + startActivity(intent) + finish() + } + + binding.cometchatAiAssistantChatHistory.setOnCloseClickListener { + finish() + } + } +} +``` + + + +```kotlin AIAssistantChatHistoryScreen.kt lines +import com.cometchat.uikit.compose.presentation.aiassistantchathistory.ui.CometChatAIAssistantChatHistory + +@Composable +fun AIAssistantChatHistoryScreen( + user: User, + navController: NavController +) { + CometChatAIAssistantChatHistory( + modifier = Modifier.fillMaxSize(), + onCloseClick = { + navController.popBackStack() + }, + onNewChatClick = { + navController.navigate("ai_chat/${Gson().toJson(user)}") + }, + onItemClick = { message -> + val receiver = message.receiver + if (receiver is User) { + navController.navigate( + "ai_chat/${Gson().toJson(receiver)}/${message.rawMessage}" + ) + } + } + ) +} +``` + + + +### Step 6 — Chat History layout (XML Views only) + +```xml activity_ai_assistant_chat_history.xml lines + + + + + +``` + +> **Note:** In Jetpack Compose, the `CometChatAIAssistantChatHistory` composable is used directly — no XML layout needed. + +### Step 7 — Launching AI Chat + + + +```kotlin lines +fun launchAIAssistantChat(aiUser: User) { + val intent = Intent(this, AIAssistantChatActivity::class.java) + intent.putExtra(getString(R.string.app_user), aiUser.toJson().toString()) + startActivity(intent) +} +``` + + + +```kotlin lines +// In your NavHost setup: +composable("ai_chat/{userJson}") { backStackEntry -> + val userJson = backStackEntry.arguments?.getString("userJson") + val user = Gson().fromJson(userJson, User::class.java) + AIAssistantChatScreen(user = user) +} + +composable("ai_chat_history/{userJson}") { backStackEntry -> + val userJson = backStackEntry.arguments?.getString("userJson") + val user = Gson().fromJson(userJson, User::class.java) + AIAssistantChatHistoryScreen(user = user, navController = navController) +} +``` + + + +## Implementation Flow Summary + +| Step | Action | +|:-----|:-------| +| 1 | User selects AI agent from chat list | +| 2 | AI chat screen launches | +| 3 | Parse intent data and detect agent chat (Role of user must be "@agentic") | +| 4 | Initialize UI with AI-specific styling | +| 5 | Configure chat history and navigation | +| 6 | Launch chat with AI agent | + +## Customization Options + +- **Custom AI Assistant Empty Chat View:** Customize the empty state view using `setAIAssistantEmptyChatGreetingView()` (XML Views) or the `emptyView` composable slot (Compose). +- **Streaming Speed:** Adjust AI response streaming speed via `setStreamingSpeed()`. +- **AI Assistant Suggested Messages:** Create custom list of suggested messages using `setAIAssistantSuggestedMessages()`. +- **AI Assistant Tools:** Set tools for the AI agent using `setAIAssistantTools()`. + +## Feature Matrix + +| Feature | Kotlin (XML Views) | Jetpack Compose | +|:--------|:-------------------|:----------------| +| AI Chat Interface | `AIAssistantChatActivity` | `AIAssistantChatScreen` composable | +| Chat History | `CometChatAIAssistantChatHistory` XML | `CometChatAIAssistantChatHistory()` composable | +| Message List | `CometChatMessageList` XML | `CometChatMessageList()` composable | +| Message Composer | `CometChatMessageComposer` XML | `CometChatMessageComposer()` composable | + + + + Explore this feature in the CometChat AI Builder: + [GitHub → AI Builder](https://github.com/cometchat/cometchat-uikit-android/tree/v6/ai-sample-app) + + + Explore this feature in the CometChat SampleApp: + [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v6/sample-app-kotlin) + + diff --git a/ui-kit/android/v6/guide-block-unblock-user.mdx b/ui-kit/android/v6/guide-block-unblock-user.mdx new file mode 100644 index 000000000..c70dd069c --- /dev/null +++ b/ui-kit/android/v6/guide-block-unblock-user.mdx @@ -0,0 +1,277 @@ +--- +title: "Block/Unblock User" +sidebarTitle: "Block/Unblock User" +description: "Let users block and unblock others directly within chat to control unwanted communication." +--- + + + +| Field | Value | +| --- | --- | +| Packages | `com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack` | +| Key components | `CometChatMessageComposer`, `CometChat.blockUsers()`, `CometChat.unblockUsers()`, `User.isBlockedByMe()` | +| Purpose | Let users block and unblock others directly within chat to control unwanted communication. | +| Related | [Message Composer](/ui-kit/android/v6/message-composer), [Message List](/ui-kit/android/v6/message-list), [All Guides](/ui-kit/android/v6/guide-overview) | + + + +Enable users to block and unblock others directly within chat using CometChat's Android UI Kit v5+, preventing unwanted communication and giving users more control. + +## Overview + +Blocking a user stops them from sending messages to the blocker. The CometChat UIKit handles most behaviors internally: + +- **Composer Hidden:** The message composer is hidden when chatting with a blocked user. +- **Unblock Prompt:** An "Unblock" button is displayed to reverse the block. +- **Message Restrictions:** Blocked users cannot send messages to the blocker. + +## Prerequisites + +- Android Studio project with CometChat Android UI Kit v5 added to `build.gradle`. +- CometChat **App ID**, **Auth Key**, and **Region** configured and initialized. +- `` in `AndroidManifest.xml`. +- Logged-in user via `CometChatUIKit.login()`. +- Existing one-on-one chat screen using `CometChatMessageList` and `CometChatMessageComposer`. + +## Components + +| Component / Class | Role | +|:-------------------------------------|:------------------------------------------------------------| +| `UserDetailActivity` | Displays user profile and provides block/unblock options. | +| `MessagesActivity` | Hosts the chat screen and toggles UI based on block state. | +| `CometChat.blockUsers()` | SDK API to block one or more users by UID. | +| `CometChat.unblockUsers()` | SDK API to unblock one or more users by UID. | +| `User.isBlockedByMe()` | Checks if the current user has blocked this user. | +| `unblockLayout` (View) | Layout shown when a user is blocked, containing unblock. | +| `CometChatMessageComposer` | Hidden when chatting with a blocked user. | + +## Integration Steps + +### 1. Detect Block Status + +Update UI when block state changes. + + + +```kotlin lines +// In MessagesActivity.kt +import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer + +private fun updateUserBlockStatus(user: User) { + val blocked = user.isBlockedByMe + binding.messageComposer.visibility = if (blocked) View.GONE else View.VISIBLE + binding.unblockLayout.visibility = if (blocked) View.VISIBLE else View.GONE +} +``` + + + +```kotlin lines +// In MessagesScreen.kt +import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer + +@Composable +fun MessagesScreen(user: User) { + val blocked = user.isBlockedByMe + + Column(modifier = Modifier.fillMaxSize()) { + // Message list... + + if (blocked) { + UnblockPrompt(onUnblock = { /* unblock logic */ }) + } else { + CometChatMessageComposer(user = user) + } + } +} +``` + + + +**File reference:** +[`MessagesActivity.kt`](https://github.com/cometchat/cometchat-uikit-android/blob/v6/sample-app-kotlin) + +Ensures the composer and unblock UI reflect the current block state. + +### 2. Hide Composer & Show Unblock UI + +Define layout elements and their visibility toggles. + +```xml activity_messages.xml lines + + + + + +