--- name: cometchat-android-v5-customization description: "Customize CometChat components beyond theming — custom message templates, DataSource decorators, event listeners, and custom view slots." license: "MIT" compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x" metadata: author: "CometChat" version: "3.0.0" tags: "cometchat android customization custom-view message-template datasource events" --- > **Ground truth:** `com.cometchat:chat-uikit-android:5.x` (legacy/maintenance-only; +`calls-sdk-android:5.x`) — resolved AAR (javap) + `ui-kit/android`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them. > **Companion skills:** `cometchat-android-v5-components` provides the component > catalog; `cometchat-android-v5-theming` covers visual styling; > `cometchat-android-v5-extensions` covers the extension architecture. ## Purpose This skill teaches how to customize CometChat components beyond what theming provides. It covers custom message templates, the DataSource/DataSourceDecorator pattern, ChatConfigurator, event listeners, and custom view slots. --- ## Use this skill when - "Customize the message list" - "Add a custom message bubble" - "Listen to message events" - "Add a custom action to message options" - "Filter conversations" ## Do not use this skill when - Changing colors/fonts → use `cometchat-android-v5-theming` - Enabling a packaged feature → use `cometchat-android-v5-features` - Setting up init/login → use `cometchat-android-v5-core` --- ## 1. CometChatMessageTemplate Templates define how message bubbles are rendered. Each template maps a message `type` + `category` to custom views. > **Prefer the decorator (§3) for anything app-wide.** The per-list `setTemplates(...)` shown here only affects the one `CometChatMessageList` you call it on. To register a custom type, override a built-in bubble, add an attachment, or add a long-press option **everywhere**, use the four `DataSourceDecorator` recipes in §3 — that is the pattern the kit's own extensions use. **Java:** ```java CometChatMessageTemplate template = new CometChatMessageTemplate() .setType(CometChatConstants.MESSAGE_TYPE_TEXT) .setCategory(CometChatConstants.CATEGORY_MESSAGE) .setContentView(new MessagesViewHolderListener() { @Override public View createView(Context context, CometChatMessageBubble messageBubble, UIKitConstants.MessageBubbleAlignment alignment) { // Return your custom view return LayoutInflater.from(context).inflate(R.layout.custom_text_bubble, null); } @Override public void bindView(Context context, View createdView, BaseMessage message, UIKitConstants.MessageBubbleAlignment alignment, RecyclerView.ViewHolder holder, List messageList, int position) { // Bind data to your custom view TextView textView = createdView.findViewById(R.id.customText); textView.setText(((TextMessage) message).getText()); } }) .setOptions((context, baseMessage, group) -> { // Return custom message options (long-press menu) List options = new ArrayList<>(); options.add(new CometChatMessageOption("custom_action", "Custom Action", R.drawable.ic_custom, () -> { /* handle click */ })); return options; }); // Apply to message list — APPEND to defaults, never replace. // ❌ messageList.setTemplates(Collections.singletonList(template)); // wipes ALL default bubbles List templates = CometChatUIKit.getDataSource().getMessageTemplates(new AdditionParameter()); templates.add(template); // keep text/image/video/file/… + add yours messageList.setTemplates(templates); ``` > **The #1 custom-bubble mistake:** `setTemplates(singletonList(myTemplate))` replaces the entire template set, so every default bubble (text, image, video, audio, file, …) stops rendering. Always seed the list from `CometChatUIKit.getDataSource().getMessageTemplates(new AdditionParameter())` and `add()` your template — or register a `DataSourceDecorator` (§3) so the append applies app-wide. **Kotlin:** ```kotlin val template = CometChatMessageTemplate() .setType(CometChatConstants.MESSAGE_TYPE_TEXT) .setCategory(CometChatConstants.CATEGORY_MESSAGE) .setContentView(object : MessagesViewHolderListener() { override fun createView(context: Context, messageBubble: CometChatMessageBubble, alignment: UIKitConstants.MessageBubbleAlignment): View { return LayoutInflater.from(context).inflate(R.layout.custom_text_bubble, null) } override fun bindView(context: Context, createdView: View, message: BaseMessage, alignment: UIKitConstants.MessageBubbleAlignment, holder: RecyclerView.ViewHolder, messageList: List, position: Int) { val textView = createdView.findViewById(R.id.customText) textView.text = (message as TextMessage).text } }) .setOptions { context, baseMessage, group -> listOf(CometChatMessageOption("custom_action", "Custom Action", R.drawable.ic_custom) { /* handle click */ }) } // APPEND to defaults — don't replace. // ❌ messageList.setTemplates(listOf(template)) // wipes ALL default bubbles val templates = CometChatUIKit.getDataSource().getMessageTemplates(AdditionParameter()) templates.add(template) messageList.setTemplates(templates) ``` ### Template view slots | Slot | Method | Description | |---|---|---| | `bubbleView` | `setBubbleView(MessagesViewHolderListener)` | Entire message bubble | | `headerView` | `setHeaderView(MessagesViewHolderListener)` | Above the bubble | | `contentView` | `setContentView(MessagesViewHolderListener)` | Inside the bubble | | `bottomView` | `setBottomView(MessagesViewHolderListener)` | Below the content, inside bubble | | `footerView` | `setFooterView(MessagesViewHolderListener)` | Below the bubble | | `statusInfoView` | `setStatusInfoView(MessagesViewHolderListener)` | Status info area | | `replyView` | `setReplyView(MessagesViewHolderListener)` | Reply preview above bubble | --- ## 2. CometChatMessageOption Custom actions in the message long-press menu. `CometChatMessageOption extends CometChatOption`. Verified constructor (`CometChatMessageOption.java:43`): ```java public CometChatMessageOption(@NotNull String id, @NotNull String title, @ColorInt int icon, OnClick onClick) ``` **Java:** ```java CometChatMessageOption option = new CometChatMessageOption( "bookmark", // unique ID "Bookmark", // title R.drawable.ic_bookmark, // icon — see note below () -> { // onClick (com.cometchat.chatuikit.shared.interfaces.OnClick) // Handle bookmark action } ); ``` > **Icon-param quirk:** the 4-arg constructor's third param is annotated `@ColorInt int icon`, but the kit's own decorators pass a **drawable** resource here (e.g. `MessageTranslationDecorator.java:53` passes `R.drawable.cometchat_ic_translate`). Pass your `R.drawable.*` id — the annotation is misleading, the runtime treats it as a drawable. The 7-arg constructor (`CometChatMessageOption.java:58`) adds `titleColor`, `iconTintColor`, `titleAppearance` if you need styling. --- ## 3. DataSource and DataSourceDecorator The `DataSource` interface defines how messages are rendered and what options are available. `DataSourceDecorator` wraps an existing DataSource to add or modify behavior without replacing it. **Java:** ```java public class CustomDataSource extends DataSourceDecorator { public CustomDataSource(DataSource dataSource) { super(dataSource); } @Override public List getTextMessageOptions(Context context, BaseMessage baseMessage, Group group, AdditionParameter additionParameter) { List options = super.getTextMessageOptions(context, baseMessage, group, additionParameter); // Add custom option options.add(new CometChatMessageOption("translate", "Translate", R.drawable.ic_translate, () -> { /* translate */ })); return options; } } ``` **Kotlin:** ```kotlin class CustomDataSource(dataSource: DataSource) : DataSourceDecorator(dataSource) { override fun getTextMessageOptions(context: Context, baseMessage: BaseMessage, group: Group?, additionParameter: AdditionParameter): List { val options = super.getTextMessageOptions(context, baseMessage, group, additionParameter).toMutableList() options.add(CometChatMessageOption("translate", "Translate", R.drawable.ic_translate) { /* translate */ }) return options } } ``` ### Register via ChatConfigurator **Java:** ```java ChatConfigurator.enable(dataSource -> new CustomDataSource(dataSource)); ``` **Kotlin:** ```kotlin ChatConfigurator.enable { dataSource -> CustomDataSource(dataSource) } ``` ### The four customization scenarios (all via the decorator) The canonical Android V5 extension surface is the `DataSource` chain. The four most common requests each map to **one overridden method** on your `DataSourceDecorator`. Every override **must call `super.*` first** and append — returning a fresh list/template wipes the kit's defaults. These are the exact methods + signatures the kit's own extensions use; cited file:line for each. #### Scenario 1 — Register a custom message type (new bubble) Override `getMessageTemplates(...)` and append a `CometChatMessageTemplate` whose `setCategory(...)` is `UIKitConstants.MessageCategory.CUSTOM` and whose `setType(...)` is your custom type string. Render its bubble with `setContentView(MessagesViewHolderListener)`. This mirrors `PollsExtensionDecorator.getMessageTemplates` (`PollsExtensionDecorator.java:82-86`) + `getPollTemplate` (`PollsExtensionDecorator.java:220-309`). **Java:** ```java @Override public List getMessageTemplates(@NonNull AdditionParameter additionParameter) { List templates = super.getMessageTemplates(additionParameter); // keep defaults templates.add(getLocationTemplate(additionParameter)); return templates; } private CometChatMessageTemplate getLocationTemplate(@NonNull AdditionParameter additionParameter) { return new CometChatMessageTemplate() .setCategory(UIKitConstants.MessageCategory.CUSTOM) // CUSTOM, not MESSAGE .setType("location") // your custom type // setOptions: Function3> .setOptions((context, baseMessage, group) -> ChatConfigurator.getDataSource().getCommonOptions(context, baseMessage, group, additionParameter)) .setContentView(new MessagesViewHolderListener() { @Override public View createView(Context context, CometChatMessageBubble messageBubble, UIKitConstants.MessageBubbleAlignment alignment) { return LayoutInflater.from(context).inflate(R.layout.custom_location_bubble, null); } @Override public void bindView(Context context, View createdView, BaseMessage message, UIKitConstants.MessageBubbleAlignment alignment, RecyclerView.ViewHolder holder, List messageList, int position) { // bind from (CustomMessage) message customData } }); } ``` > You usually also want the type to count as a known type: override `getDefaultMessageTypes(...)` / `getDefaultMessageCategories(...)` and append your type / `MessageCategory.CUSTOM` (Polls does exactly this — `PollsExtensionDecorator.java:171-186`). #### Scenario 2 — Override an existing built-in type's bubble Do **not** rebuild the template list. Override the per-type template getter and mutate the template returned by `super`. The verified getters on `DataSource` are `getTextTemplate(AdditionParameter)`, `getImageTemplate`, `getVideoTemplate`, `getAudioTemplate`, `getFileTemplate` (`DataSource.java:230-244`), plus the lookup `getMessageTemplate(String category, String type, AdditionParameter)` (`DataSource.java:260`). The decorator forwards each to the wrapped source (`DataSourceDecorator.java:598`, `:652`), so call `super` then re-skin only the slot you want. **Java:** ```java @Override public CometChatMessageTemplate getTextTemplate(@NonNull AdditionParameter additionParameter) { CometChatMessageTemplate template = super.getTextTemplate(additionParameter); // keeps type/category/options template.setContentView(new MessagesViewHolderListener() { // swap only the content slot @Override public View createView(Context context, CometChatMessageBubble messageBubble, UIKitConstants.MessageBubbleAlignment alignment) { return LayoutInflater.from(context).inflate(R.layout.my_text_bubble, null); } @Override public void bindView(Context context, View createdView, BaseMessage message, UIKitConstants.MessageBubbleAlignment alignment, RecyclerView.ViewHolder holder, List messageList, int position) { ((TextView) createdView.findViewById(R.id.body)).setText(((TextMessage) message).getText()); } }); return template; } ``` > `setContentView`/`setBubbleView`/`setHeaderView`/`setBottomView`/`setStatusInfoView`/`setFooterView`/`setReplyView` all take a `MessagesViewHolderListener` and return the template (`CometChatMessageTemplate.java:79-202`) — pick the slot you need. Overriding `getTextTemplate` reskins **every** text bubble app-wide while preserving its default options/category/type. #### Scenario 3 — Add a composer attachment option Override `getAttachmentOptions(...)`, call `super`, and append a `CometChatMessageComposerAction` (a builder — `setId/setTitle/setIcon/setOnClick`, `CometChatMessageComposerAction.java:46-127`). This is exactly `PollsExtensionDecorator.getAttachmentOptions` (`PollsExtensionDecorator.java:88-168`). **Java:** ```java @Override public List getAttachmentOptions(Context context, User user, Group group, HashMap idMap, @NonNull AdditionParameter additionParameter) { List options = super.getAttachmentOptions(context, user, group, idMap, additionParameter); // keep camera/gallery/file/poll/… options.add(new CometChatMessageComposerAction() .setId("location") .setTitle("Send Location") .setIcon(R.drawable.ic_location) .setOnClick(() -> { /* pick + send (see below) */ })); return options; } ``` #### Scenario 4 — Add a message long-press option (Forward-style) Override the **per-type** option getter — `getTextMessageOptions`, `getImageMessageOptions`, `getVideoMessageOptions`, `getAudioMessageOptions`, or `getFileMessageOptions` (`DataSource.java:49-108`) — call `super`, then append a `CometChatMessageOption`. This is exactly `MessageTranslationDecorator.getTextMessageOptions` (`MessageTranslationDecorator.java:44-59`). **Java:** ```java @Override public List getTextMessageOptions(Context context, BaseMessage baseMessage, Group group, @NonNull AdditionParameter additionParameter) { List options = super.getTextMessageOptions(context, baseMessage, group, additionParameter); // keep reply/copy/edit/delete/… if (baseMessage != null && baseMessage.getDeletedAt() == 0) { options.add(new CometChatMessageOption( "forward", "Forward", R.drawable.ic_forward, () -> { /* forward baseMessage */ })); } return options; } ``` > `getMessageOptions(...)` (`DataSource.java:271`) is the **aggregate** dispatcher the kit calls per message; it routes to the per-type getters above. To add an option to *one* message type, override that type's getter (as above). Override `getMessageOptions` only when you want the option on **every** message type at once. > **Append rule (all four):** an override that returns a fresh `new ArrayList<>()` instead of starting from `super.*` wipes every default (bubbles, attachments, or options). Always seed from `super`. Register the decorator app-wide via `ChatConfigurator.enable(...)` (§"Register via ChatConfigurator" above) — it accepts `Function1` (`ChatConfigurator.java:39`). For a packaged two-class extension (registrar + decorator), see `cometchat-android-v5-extensions`. ### Sending a custom message — use the UIKit path, not the raw SDK ```java CustomMessage message = new CustomMessage( receiverId, CometChatConstants.RECEIVER_TYPE_USER, // or RECEIVER_TYPE_GROUP "location", // matches the template type customData); // JSONObject // ✅ kit path — sets muid + sender, fires ccMessageSent → list APPENDS CometChatUIKit.sendCustomMessage(message, new CometChat.CallbackListener() { @Override public void onSuccess(CustomMessage m) { } @Override public void onError(CometChatException e) { } }); // ❌ CometChat.sendCustomMessage(...) — no muid/sender/event → recipient error + realtime replace ``` Verified against kit source (chat-uikit-android 5.x): - `CometChatUIKit.getDataSource()`, `ChatConfigurator.getDataSource()` / `ChatConfigurator.enable(Function1)` (`ChatConfigurator.java:39,55`) - `DataSource.getMessageTemplates(AdditionParameter)` (`DataSource.java:248`); per-type template getters `getTextTemplate/getImageTemplate/getVideoTemplate/getAudioTemplate/getFileTemplate(AdditionParameter)` (`DataSource.java:230-244`); lookup `getMessageTemplate(String category, String type, AdditionParameter)` (`DataSource.java:260`) - Per-type option getters `getTextMessageOptions/getImageMessageOptions/getVideoMessageOptions/getAudioMessageOptions/getFileMessageOptions(Context, BaseMessage, Group, AdditionParameter)` (`DataSource.java:49-108`); aggregate `getMessageOptions(...)` (`DataSource.java:271`) - `DataSource.getAttachmentOptions(Context, User, Group, HashMap, AdditionParameter)` (`DataSource.java:286`) - `CometChatMessageTemplate` setters `setType/setCategory(String)`, `setOptions(Function3>)`, `setContentView/setBubbleView/setHeaderView/setBottomView/setStatusInfoView/setFooterView/setReplyView(MessagesViewHolderListener)` (`CometChatMessageTemplate.java:79-237`) - `CometChatMessageComposerAction` builder `setId/setTitle/setIcon/setOnClick(...)` (`CometChatMessageComposerAction.java:46-127`); `CometChatMessageOption(String,String,int,OnClick)` (`CometChatMessageOption.java:43`) - `MessagesViewHolderListener.createView(...)` + `bindView(...)` (`MessagesViewHolderListener.java:18-26`) - `CometChatUIKit.sendCustomMessage(CustomMessage, CallbackListener)` - Canonical reference decorators: `PollsExtensionDecorator.java` (template + attachment), `MessageTranslationDecorator.java` (message option) --- ## 4. Event system CometChat provides event classes for reacting to chat events. Register listeners with a unique tag. ### CometChatMessageEvents **Java:** ```java CometChatMessageEvents.addListener("unique-tag", new CometChatMessageEvents() { @Override public void ccMessageSent(BaseMessage baseMessage, int status) { // Message sent } @Override public void onTextMessageReceived(TextMessage textMessage) { // Text message received } @Override public void onMessageReactionAdded(ReactionEvent reactionEvent) { // Reaction added } }); // Remove when done CometChatMessageEvents.removeListener("unique-tag"); ``` **Kotlin:** ```kotlin CometChatMessageEvents.addListener("unique-tag", object : CometChatMessageEvents() { override fun ccMessageSent(baseMessage: BaseMessage, status: Int) { // Message sent } override fun onTextMessageReceived(textMessage: TextMessage) { // Text message received } override fun onMessageReactionAdded(reactionEvent: ReactionEvent) { // Reaction added } }) // Remove when done CometChatMessageEvents.removeListener("unique-tag") ``` ### CometChatUserEvents ```java CometChatUserEvents.addUserListener("unique-tag", new CometChatUserEvents() { @Override public void ccUserBlocked(User user) { } @Override public void ccUserUnblocked(User user) { } }); ``` ### CometChatGroupEvents ```java CometChatGroupEvents.addGroupListener("unique-tag", new CometChatGroupEvents() { @Override public void ccGroupCreated(Group group) { } @Override public void ccGroupDeleted(Group group) { } @Override public void ccGroupMemberJoined(User joinedUser, Group joinedGroup) { } @Override public void ccGroupMemberKicked(Action action, User kicked, User kickedBy, Group from) { } @Override public void ccGroupMemberBanned(Action action, User banned, User bannedBy, Group from) { } }); ``` ### CometChatCallEvents ```java CometChatCallEvents.addListener("unique-tag", new CometChatCallEvents() { @Override public void ccOutgoingCall(Call call) { } @Override public void ccCallAccepted(Call call) { } @Override public void ccCallRejected(Call call) { } @Override public void ccCallEnded(Call call) { } }); ``` --- ## 5. Custom view slots on components Most components support custom view injection via `Function3`: ```java CometChatMessageHeader header = findViewById(R.id.header); header.setSubtitleView((context, user, group) -> { TextView subtitle = new TextView(context); if (user != null) { subtitle.setText(user.getStatus().equals("online") ? "Active now" : "Offline"); } return subtitle; }); ``` --- ## Hard rules - **Always extend `DataSourceDecorator`, never implement `DataSource` directly.** The decorator preserves existing behavior. - **Register `ChatConfigurator.enable()` AFTER `CometChatUIKit.init()` succeeds.** The configurator resets on init. - **Always remove event listeners when the Activity/Fragment is destroyed.** Use `onDestroy()` or `onDestroyView()`. - **Template view slots use `MessagesViewHolderListener`.** Implement both `createView()` and `bindView()`. ## Sound (in-app message + call sounds) The V5 UI Kit surfaces `CometChatSoundManager` for incoming/outgoing message + call sounds (mute / custom audio). **V5 is legacy/maintenance-only** — V6 is the current cohort. For call sounds see this family's `-calls` skill; verify the `CometChatSoundManager` API against the installed kit before relying on it.