> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Kit Builder Settings

> Configure iOS UI Kit Builder settings for messaging, AI helpers, calling, layout, theming, and Swift configuration.

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.

<Info>
  **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](/chat-builder/ios/integration) for setup.
</Info>

## Top-level Structure

The `CometChatBuilderSettings` object in Swift follows this structure:

```swift theme={null}
CometChatBuilderSettings.shared.chatFeatures
CometChatBuilderSettings.shared.callFeatures
CometChatBuilderSettings.shared.layout
CometChatBuilderSettings.shared.style
```

***

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

## 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 |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **AI > Settings**.
</Tip>

### 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.

```json theme={null}
{
  "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](https://app.cometchat.com) before they can be used:

<Note>
  **AI Copilot Features** (Conversation Starter, Conversation Summary, Smart Reply)

  * Requires an OpenAI API key configured in the Dashboard under **AI > Settings**
</Note>

<Note>
  **Stickers**

  * Requires sticker packs to be configured in the Dashboard under **Chat & Messaging > Stickers**
</Note>

<Note>
  **Polls**

  * Requires the Polls extension to be enabled in the Dashboard under **Extensions > Polls**
</Note>

<Note>
  **Collaborative Whiteboard & Document**

  * Requires the respective extensions to be enabled in the Dashboard under **Extensions**
</Note>

<Note>
  **Message Translation**

  * Requires the Message Translation extension to be enabled in the Dashboard under **Extensions > Message Translation**
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Directory Structure" href="/chat-builder/ios/builder-dir-structure">
    Understand the organization of the builder components and generated code.
  </Card>

  <Card title="Customizations" href="/chat-builder/ios/builder-customisations">
    Modify component props, styling, and behavior for deeper customization.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.