UI Kit Builder Settings

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

For developers customizing their chat UI: Edit cometchat-builder-settings.json to enable/disable features like messaging, calls, AI copilot, and theming. See the Integration Guide for setup.

Top-level Structure

The CometChatBuilderSettings object in Swift follows this structure:

CometChatBuilderSettings.shared.chatFeatures
CometChatBuilderSettings.shared.callFeatures
CometChatBuilderSettings.shared.layout
CometChatBuilderSettings.shared.style

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
Typing indicator (`typingIndicator`)	boolean	Shows “typing…” indicator when someone is composing a message
Thread conversation & replies (`threadConversationAndReplies`)	boolean	Enables threaded replies to specific messages, creating nested conversation threads
Photos sharing (`photosSharing`)	boolean	Allows users to share images from device or camera
Video sharing (`videoSharing`)	boolean	Allows users to share video files
Audio sharing (`audioSharing`)	boolean	Allows users to share audio files (mp3, wav, etc.)
File sharing (`fileSharing`)	boolean	Allows users to share documents (PDF, DOC, etc.)
Edit messages (`editMessage`)	boolean	Lets users modify their sent messages; edited messages show “(edited)” label
Delete messages (`deleteMessage`)	boolean	Lets users remove their sent messages
Message delivery and read receipts (`messageDeliveryAndReadReceipts`)	boolean	Shows delivery (✓) and read (✓✓) status indicators on messages
User & friends presence (`userAndFriendsPresence`)	boolean	Shows online/offline status dot next to user avatars
Conversation and Advanced Search (`conversationAndAdvancedSearch`)	boolean	Enables search across messages, users, and conversations
Moderation (`moderation`)	boolean	Enables blocked message feedback for messages blocked by moderation rules
Quoted Replies (`quotedReplies`)	boolean	Lets users quote a message when replying, showing the original above their response
Mark as Unread (`markAsUnread`)	boolean	Lets users mark a conversation as unread to revisit later

1.2 Deeper User Engagement (`deeperUserEngagement`)

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

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

1.3 AI User Copilot (`aiUserCopilot`)

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

Setting	Type	What It Does
Conversation Starter (`conversationStarter`)	boolean	Shows AI-suggested opening messages when starting a new chat. Requires OpenAI API key
Conversation Summary (`conversationSummary`)	boolean	Generates an AI-powered summary of the conversation. Requires OpenAI API key
Smart Reply (`smartReply`)	boolean	Shows AI-suggested quick reply options based on conversation context. Requires OpenAI API key

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
Friends Only (`friendsOnly`)	boolean	Restricts chat to friends list only; Users tab shows only friends

1.5 Group Management (`groupManagement`)

Control what users can do with groups.

Setting	Type	What It Does
Create Group (`createGroup`)	boolean	Lets users create new public or private groups
Add Members to Groups (`addMembersToGroups`)	boolean	Lets group admins/owners invite users to join the group
Join/Leave Group (`joinLeaveGroup`)	boolean	Lets users join public groups and leave groups they’re in
Delete Group (`deleteGroup`)	boolean	Lets group owners permanently delete a group and all its messages
View Group Members (`viewGroupMembers`)	boolean	Shows member list in group info

1.6 Moderator Controls (`moderatorControls`)

Admin tools for managing group members and content.

Setting	Type	What It Does
Report Message (`reportMessage`)	boolean	Lets users flag messages for moderator review in Dashboard
Kick Users (`kickUsers`)	boolean	Lets admins/moderators remove a user from a group (they can rejoin)
Ban Users (`banUsers`)	boolean	Lets admins/moderators permanently remove a user and prevent rejoining
Promote/Demote Members (`promoteDemoteMembers`)	boolean	Lets group owners change member roles (member, moderator, admin)

1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Allow direct messages between group members.

Setting	Type	What It Does
Send Private Message to Group Members (`sendPrivateMessageToGroupMembers`)	boolean	Lets users start a 1:1 chat with a group member from their profile

1.8 In-App Sounds (`inAppSounds`)

Control sound notifications for incoming and outgoing messages.

Setting	Type	What It Does
Incoming Message Sound (`incomingMessageSound`)	boolean	Plays a sound when a new message is received
Outgoing Message Sound (`outgoingMessageSound`)	boolean	Plays a sound when a message is sent

2. Call Features (`callFeatures`)

2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Enable voice and video calling capabilities.

Setting	Type	What It Does
1:1 Voice Calling (`oneOnOneVoiceCalling`)	boolean	Shows phone icon in 1:1 chat header for starting voice calls
1:1 Video Calling (`oneOnOneVideoCalling`)	boolean	Shows video camera icon in 1:1 chat header for starting video calls
Group Video Conference (`groupVideoConference`)	boolean	Shows video camera icon in group chat header for starting group video calls
Group Voice Conference (`groupVoiceConference`)	boolean	Shows phone icon in group chat header for starting group voice calls

3. Layout (`layout`)

Control the overall UI structure and navigation.

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

4. Style (`style`)

Customize colors, fonts, and theme appearance.

4.1 Theme

Setting	Type	What It Does
Theme (`theme`)	string	Controls light/dark mode: `'light'`, `'dark'`, or `'system'` (matches device preference)

4.2 Colors

Setting	Type	What It Does
Brand Color (`brandColor`)	string	Primary accent color (hex) for buttons, links, active states. Example: `"#6852D6"`
Primary Text Light (`primaryTextLight`)	string	Main text color in light mode (hex). Example: `"#141414"`
Primary Text Dark (`primaryTextDark`)	string	Main text color in dark mode (hex). Example: `"#FFFFFF"`
Secondary Text Light (`secondaryTextLight`)	string	Secondary text color in light mode (hex) for timestamps, subtitles. Example: `"#727272"`
Secondary Text Dark (`secondaryTextDark`)	string	Secondary text color in dark mode (hex) for timestamps, subtitles. Example: `"#989898"`

4.3 Typography

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

Settings Overview

Below is the complete settings structure with default values. Update these in your cometchat-builder-settings.json file to customize your chat experience.

{
  "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": "user"
    },
    "style": {
      "theme": "system",
      "color": {
        "brandColor": "#6852D6",
        "primaryTextLight": "#141414",
        "primaryTextDark": "#FFFFFF",
        "secondaryTextLight": "#727272",
        "secondaryTextDark": "#989898"
      },
      "typography": {
        "font": "roboto",
        "size": "default"
      }
    }
  }
}

Dashboard Feature Requirements

Some features require additional configuration in the CometChat Dashboard before they can be used:

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

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

Stickers

Requires sticker packs to be configured in the Dashboard under Chat & Messaging > Stickers

Polls

Requires the Polls extension to be enabled in the Dashboard under Extensions > Polls

Collaborative Whiteboard & Document

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

Message Translation

Requires the Message Translation extension to be enabled in the Dashboard under Extensions > Message Translation

Reference

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

Settings Overview

Dashboard Feature Requirements

Next Steps

Directory Structure

Customizations

Reference

​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

​Settings Overview

​Dashboard Feature Requirements

​Next Steps

Directory Structure

Customizations

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

Settings Overview

Dashboard Feature Requirements

Next Steps