UI Kit Builder Settings - CometChat Docs

The Builder configuration controls everything the Flutter UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This configuration is loaded from the cometchat-builder-settings.json file via BuilderSettingsHelper.

For developers customizing their chat UI: The configuration JSON file contains all your feature toggles, layout settings, and styling configuration. Edit this file to enable/disable features like messaging, calls, AI copilot, and theming. See the Integration Guide for setup.

Top-level Structure

The configuration JSON follows this structure:

{
  "builderId": "unique-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": { /* Boolean settings */ },
      "deeperUserEngagement": { /* Boolean settings */ },
      "aiUserCopilot": { /* Boolean settings */ },
      "userManagement": { /* Boolean settings */ },
      "groupManagement": { /* Boolean settings */ },
      "moderatorControls": { /* Boolean settings */ },
      "privateMessagingWithinGroups": { /* Boolean settings */ },
      "inAppSounds": { /* Boolean settings */ }
    },
    "callFeatures": {
      "voiceAndVideoCalling": { /* Boolean settings */ }
    },
    "layout": { /* Layout settings */ },
    "style": {
      "theme": "system",
      "color": { /* Color settings */ },
      "typography": { /* Typography settings */ }
    }
  }
}

All boolean settings follow the same pattern: true enables the feature and shows its UI elements, false hides them completely.

1. Chat Features (`chatFeatures`)

1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

Setting	Type	What It Does
`typingIndicator`	boolean	Shows “typing…” indicator when someone is composing a message
`threadConversationAndReplies`	boolean	Enables threaded replies to specific messages, creating nested conversation threads
`photosSharing`	boolean	Allows users to share images from device or camera
`videoSharing`	boolean	Allows users to share video files
`audioSharing`	boolean	Allows users to share audio files (mp3, wav, etc.)
`fileSharing`	boolean	Allows users to share documents (PDF, DOC, etc.)
`editMessage`	boolean	Lets users modify their sent messages; edited messages show “(edited)” label
`deleteMessage`	boolean	Lets users remove their sent messages
`messageDeliveryAndReadReceipts`	boolean	Shows delivery (✓) and read (✓✓) status indicators on messages
`userAndFriendsPresence`	boolean	Shows online/offline status dot next to user avatars
`conversationAndAdvancedSearch`	boolean	Enables search across messages, users, and conversations
`moderation`	boolean	Enables blocked message feedback for messages blocked by moderation rules
`quotedReplies`	boolean	Lets users quote a message when replying, showing the original above their response
`markAsUnread`	boolean	Lets users mark a conversation as unread to revisit later

Empower users with a seamless chat experience—reply to specific messages with quoted replies, mark conversations as unread for later, and search across all chats instantly. Learn more about Core Features.

1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

Setting	Type	What It Does
`mentions`	boolean	Lets users @mention specific people in a message to notify them
`mentionAll`	boolean	Lets users type @all to notify every member in a group chat
`reactions`	boolean	Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages
`messageTranslation`	boolean	Translates messages to user’s preferred language. Requires Dashboard setup
`polls`	boolean	Lets users create polls with multiple options for group voting. Requires Dashboard setup
`collaborativeWhiteboard`	boolean	Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup
`collaborativeDocument`	boolean	Creates shared documents for real-time collaborative editing. Requires Dashboard setup
`voiceNotes`	boolean	Lets users record and send voice messages
`emojis`	boolean	Shows emoji picker in composer for browsing and inserting emojis
`stickers`	boolean	Lets users send sticker images from available packs. Requires Dashboard setup
`userInfo`	boolean	Lets users tap on another user’s avatar to view their profile
`groupInfo`	boolean	Lets users tap on group header to view group details and member list

Configure these features based on your app’s requirements. Learn more about Extensions.

1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

Setting	Type	What It Does
`conversationStarter`	boolean	Shows AI-suggested opening messages
`conversationSummary`	boolean	Generates AI-powered conversation summary
`smartReply`	boolean	Shows AI-suggested quick reply options

AI User Copilot features require an OpenAI API key. Configure it in the CometChat Dashboard under AI > Settings.

1.4 User Management (`userManagement`)

Setting	Type	What It Does
`friendsOnly`	boolean	Restricts chat to friends list only

1.5 Group Management (`groupManagement`)

Setting	Type	What It Does
`createGroup`	boolean	Lets users create new groups
`addMembersToGroups`	boolean	Lets admins invite users to groups
`joinLeaveGroup`	boolean	Lets users join/leave groups
`deleteGroup`	boolean	Lets owners delete groups
`viewGroupMembers`	boolean	Shows member list in group info

1.6 Moderator Controls (`moderatorControls`)

Setting	Type	What It Does
`reportMessage`	boolean	Lets users flag messages for review
`kickUsers`	boolean	Lets admins remove users from groups
`banUsers`	boolean	Lets admins permanently ban users
`promoteDemoteMembers`	boolean	Lets owners change member roles

1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Setting	Type	What It Does
`sendPrivateMessageToGroupMembers`	boolean	Lets users start 1:1 chats with group members

1.8 In-App Sounds (`inAppSounds`)

Setting	Type	What It Does
`incomingMessageSound`	boolean	Plays sound for new messages
`outgoingMessageSound`	boolean	Plays sound when sending messages

2. Call Features (`callFeatures`)

2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Setting	Type	What It Does
`oneOnOneVoiceCalling`	boolean	Shows phone icon in 1:1 chat header for starting voice calls
`oneOnOneVideoCalling`	boolean	Shows video camera icon in 1:1 chat header for starting video calls
`groupVideoConference`	boolean	Shows video camera icon in group chat header for starting group video calls
`groupVoiceConference`	boolean	Shows phone icon in group chat header for starting group voice calls

Learn more about Call Features.

3. Layout (`layout`)

Setting	Type	What It Does
`withSideBar`	boolean	Shows navigation sidebar with tabs (Chats, Calls, Users, Groups)
`tabs`	string[]	Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`
`chatType`	string	Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats, `'both'` for all

Set withSideBar: false for embedded chat widgets or single-conversation views where navigation isn’t needed.

4. Style (`style`)

4.1 Theme

Setting	Type	What It Does
`theme`	string	Controls light/dark mode: `'light'`, `'dark'`, or `'system'`

4.2 Colors

Setting	Type	What It Does
`brandColor`	string	Primary accent color (hex). Example: `"#6852D6"`
`primaryTextLight`	string	Main text color in light mode
`primaryTextDark`	string	Main text color in dark mode
`secondaryTextLight`	string	Secondary text color in light mode
`secondaryTextDark`	string	Secondary text color in dark mode

4.3 Typography

Setting	Type	What It Does
`font`	string	Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'`
`size`	string	Text size: `'default'`, `'compact'`, or `'comfortable'`

Complete Settings Example

{
  "builderId": "your-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "threadConversationAndReplies": true,
        "photosSharing": true,
        "videoSharing": true,
        "audioSharing": true,
        "fileSharing": true,
        "editMessage": true,
        "deleteMessage": true,
        "messageDeliveryAndReadReceipts": true,
        "userAndFriendsPresence": true,
        "conversationAndAdvancedSearch": true,
        "moderation": true,
        "quotedReplies": false,
        "markAsUnread": false
      },
      "deeperUserEngagement": {
        "mentions": true,
        "mentionAll": true,
        "reactions": true,
        "messageTranslation": true,
        "polls": true,
        "collaborativeWhiteboard": true,
        "collaborativeDocument": true,
        "voiceNotes": true,
        "emojis": true,
        "stickers": true,
        "userInfo": true,
        "groupInfo": true
      },
      "aiUserCopilot": {
        "conversationStarter": false,
        "conversationSummary": false,
        "smartReply": false
      },
      "userManagement": {
        "friendsOnly": false
      },
      "groupManagement": {
        "createGroup": true,
        "addMembersToGroups": true,
        "joinLeaveGroup": true,
        "deleteGroup": true,
        "viewGroupMembers": true
      },
      "moderatorControls": {
        "kickUsers": true,
        "banUsers": true,
        "promoteDemoteMembers": true,
        "reportMessage": true
      },
      "privateMessagingWithinGroups": {
        "sendPrivateMessageToGroupMembers": true
      },
      "inAppSounds": {
        "incomingMessageSound": true,
        "outgoingMessageSound": true
      }
    },
    "callFeatures": {
      "voiceAndVideoCalling": {
        "oneOnOneVoiceCalling": true,
        "oneOnOneVideoCalling": true,
        "groupVideoConference": true,
        "groupVoiceConference": true
      }
    },
    "layout": {
      "withSideBar": true,
      "tabs": ["chats", "calls", "users", "groups"],
      "chatType": "both"
    },
    "style": {
      "theme": "system",
      "color": {
        "brandColor": "#6852D6",
        "primaryTextLight": "#141414",
        "primaryTextDark": "#FFFFFF",
        "secondaryTextLight": "#727272",
        "secondaryTextDark": "#989898"
      },
      "typography": {
        "font": "roboto",
        "size": "default"
      }
    }
  }
}

Accessing Settings in Code

Use the BuilderSettingsHelper to access settings in your Flutter code:

import 'package:chat_builder/utils/builder_settings_helper.dart';

// Access settings after loading
final settings = BuilderSettingsHelper.settings;

// Check if a feature is enabled
if (settings.chatFeatures.coreMessagingExperience.photosSharing) {
  // Enable photo sharing functionality
}

// Access style settings
final brandColor = settings.style.color.brandColor;
final theme = settings.style.theme;

// Access layout settings
final tabs = settings.layout.tabs;
final withSideBar = settings.layout.withSideBar;

Dashboard Feature Requirements

Some features require additional configuration in the CometChat Dashboard:

AI Copilot Features (Conversation Starter, Conversation Summary, Smart Reply)

Requires an OpenAI API key configured in the Dashboard under AI > Settings

Stickers, Polls, Collaborative Tools, Message Translation

Requires the respective extensions to be enabled in the Dashboard under Extensions

Moderation

Requires moderation rules to be configured in the Dashboard under Moderation > Rules

Customize Beyond Settings

The settings JSON controls feature toggles, layout, and theme tokens. When you need finer control over what individual components render, the exported module is built on the standard CometChat Flutter UI Kit, so you can use its customization layers directly:

Message Templates

Customize message bubble content, headers, footers, and status views.

Component View Slots

Replace specific regions of a component’s UI using builder callbacks.

Theme Token Overrides

Override color palettes, typography, and spacing tokens.

Integration Guide

Wire the exported module into your Flutter app.

​Top-level Structure

​1. Chat Features (chatFeatures)

​1.1 Core Messaging Experience (coreMessagingExperience)

​1.2 Deeper User Engagement (deeperUserEngagement)

​1.3 AI User Copilot (aiUserCopilot)

​1.4 User Management (userManagement)

​1.5 Group Management (groupManagement)

​1.6 Moderator Controls (moderatorControls)

​1.7 Private Messaging Within Groups (privateMessagingWithinGroups)

​1.8 In-App Sounds (inAppSounds)

​2. Call Features (callFeatures)

​2.1 Voice and Video Calling (voiceAndVideoCalling)

​3. Layout (layout)

​4. Style (style)

​4.1 Theme

​4.2 Colors

​4.3 Typography

​Complete Settings Example

​Accessing Settings in Code

​Dashboard Feature Requirements

​Customize Beyond Settings

Message Templates

Component View Slots

Theme Token Overrides

Integration Guide

Top-level Structure

1. Chat Features (`chatFeatures`)

1.1 Core Messaging Experience (`coreMessagingExperience`)

1.2 Deeper User Engagement (`deeperUserEngagement`)

1.3 AI User Copilot (`aiUserCopilot`)

1.4 User Management (`userManagement`)

1.5 Group Management (`groupManagement`)

1.6 Moderator Controls (`moderatorControls`)

1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

1.8 In-App Sounds (`inAppSounds`)

2. Call Features (`callFeatures`)

2.1 Voice and Video Calling (`voiceAndVideoCalling`)

3. Layout (`layout`)

4. Style (`style`)

4.1 Theme

4.2 Colors

4.3 Typography

Complete Settings Example

Accessing Settings in Code

Dashboard Feature Requirements

Customize Beyond Settings