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

# Key Concepts

> Understand the core concepts of CometChat including users, groups, messaging categories, authentication, and member roles.

<Accordion title="AI Integration Quick Reference">
  Key identifiers:

  * **UID** — Unique User Identifier (alphanumeric, underscore, hyphen)
  * **GUID** — Group Unique Identifier (alphanumeric, underscore, hyphen)
  * **Auth Key** — Development-only credential for quick testing
  * **Auth Token** — Secure per-user token for production use
  * **REST API Key** — Server-side credential, never expose in client code

  ```dart theme={null}
  // Receiver types
  CometChatReceiverType.user         // For 1-on-1 messages
  CometChatReceiverType.group        // For group messages

  // Group types
  CometChatGroupType.public          // Anyone can join
  CometChatGroupType.password        // Requires password to join
  CometChatGroupType.private         // Invite-only

  // Member scopes
  CometChatMemberScope.admin         // Full privileges
  CometChatMemberScope.moderator     // Moderate members
  CometChatMemberScope.participant   // Send/receive messages

  // Message categories
  CometChatMessageCategory.message   // text, image, video, audio, file
  CometChatMessageCategory.custom    // Custom data messages
  CometChatMessageCategory.action    // System-generated messages
  CometChatMessageCategory.call      // Call-related messages
  ```
</Accordion>

This page covers the core concepts you'll encounter when building with CometChat. Read this before diving into the SDK guides — it'll make everything else click faster.

### CometChat Dashboard

The CometChat Dashboard enables you to create new apps (projects) and manage your existing apps.

<Note>
  Create your apps in the [CometChat Dashboard](https://app.cometchat.com) — each app gets a unique App ID required for SDK initialization. Ideally, create two apps — one for development and one for production. Use a single app regardless of the number of platforms; if you create separate apps per platform, your users won't be able to communicate across them.
</Note>

* For every app, a unique App ID is generated. This App ID will be required when integrating CometChat within your app.
* Along with the App ID, you will need to create an Auth Key (from the Dashboard) which can be used for user authentication.

## Users

A user is anyone who uses CometChat. Each user is uniquely identified by a UID (Unique User Identifier).

* The UID is typically the primary ID of the user from your database
* UID can be alphanumeric with underscore and hyphen only — spaces, punctuation, and other special characters are not allowed

### User Roles

A role is a category for grouping similar users. For example, group premium users with the role "Premium" to filter users or enable/disable features conditionally.

### User List

* The User List can be used to build the **Contacts** or **Who's Online** view in your app.
* The list of users can be different based on the logged-in user.

## Authentication

CometChat does not handle user registration or friends management — you handle that in your app, then log users into CometChat programmatically. So the user does not ever directly login to CometChat.

### API Keys

You can generate two types of keys from the [CometChat Dashboard](https://app.cometchat.com):

| Type | Privileges | Recommended Use |
| - | - | - |
| Auth Key | Create & login users | Client-side code (development only) |
| REST API Key | Perform any CometChat operation | Server-side code only |

<Warning>
  Never expose your REST API Key in client-side code. Use Auth Tokens for production authentication.
</Warning>

### Auth Tokens

Auth Tokens are secure, per-user credentials for production use:

* A single user can have multiple auth tokens (one per device)
* Generate tokens server-side via the [REST API](https://api-explorer.cometchat.com/reference/create-authtoken)
* Tokens can only be deleted via the Dashboard or REST API

### Authentication Flow

| Your App | Your Server | CometChat |
| - | - | - |
| User registers | Store user info in your database | Create user via REST API (UID & name) |
| User logs in | Verify credentials, login the user and retrieve the user ID | Log in user programmatically with UID |
| User sends friend request | Display request to potential friend | No action required |
| User accepts friend request | Display users as friends | Add both users as friends via REST API |

## Groups

A group enables multiple users to communicate on a particular topic or interest. Each group is uniquely identified using a GUID (Group Unique Identifier).

* The GUID is typically the primary ID of the group from your database
* GUID can be alphanumeric with underscore and hyphen only

<Warning>
  GUID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed.
</Warning>

## Group Types

| Type | Visibility | Participation |
| - | - | - |
| Public | All users | Any user can join |
| Password | All users | Users with valid password can join |
| Private | Members only | Users must be invited (auto-joined) |

## Member Scopes

Once a user joins a group, they become a member with one of three scopes:

| Scope | Default | Privileges |
| - | - | - |
| Admin | Group creator | Full control: manage members, change scopes, kick/ban anyone, update/delete group |
| Moderator | — | Moderate: change participant scopes, kick/ban participants, update group |
| Participant | All other members | Basic: send & receive messages and calls |

## Message Categories

Every message belongs to one of these categories:

| Category | Types | Description |
| - | - | - |
| `message` | `text`, `image`, `video`, `audio`, `file` | Standard messages |
| `custom` | Developer-defined | Custom data (e.g., location, polls) |
| `action` | `groupMember`, `message` | System-generated (joins, edits, deletes) |
| `call` | `audio`, `video` | Call-related messages |

For more details, see the [Message Structure and Hierarchy](/sdk/flutter/v4/message-structure-and-hierarchy) guide.

## Auto Mode Connection

<Note>
  Know more about auto mode connection [click here](/sdk/flutter/connection-behaviour)
</Note>

| App State | Behaviour |
| - | - |
| App in foreground | Connected with WebSocket |
| App in background | Immediately disconnected with WebSocket |

## Manual Mode Connection

<Note>
  Know more about manual mode connection [click here](/sdk/flutter/connection-behaviour)
</Note>

| App State | Behaviour |
| - | - |
| App in foreground | Call `CometChat.connect()` to create the WebSocket connection |
| App in background | Disconnect the WebSocket connection if no ping is received within 30 seconds after the app goes in the background. |

## Glossary

| Term | Definition | Learn More |
| - | - | - |
| UID | Unique User Identifier — alphanumeric string you assign to each user | [Users Overview](/sdk/flutter/users-overview) |
| GUID | Group Unique Identifier — alphanumeric string you assign to each group | [Groups Overview](/sdk/flutter/groups-overview) |
| Auth Key | Development-only credential for quick testing. Never use in production | [Authentication](/sdk/flutter/authentication-overview) |
| Auth Token | Secure, per-user token generated via REST API. Use in production | [Authentication](/sdk/flutter/authentication-overview) |
| REST API Key | Server-side credential for REST API calls. Never expose in client code | [CometChat Dashboard](https://app.cometchat.com) |
| Receiver Type | Specifies if a message target is a `user` or `group` | [Send Message](/sdk/flutter/send-message) |
| Scope | Group member scope: `admin`, `moderator`, or `participant` | [Change Member Scope](/sdk/flutter/group-change-member-scope) |
| Listener | Callback handler for real-time events (messages, presence, calls, groups) | [Real-Time Listeners](/sdk/flutter/real-time-listeners) |
| Conversation | A chat thread between two users or within a group | [Retrieve Conversations](/sdk/flutter/retrieve-conversations) |
| Metadata | Custom JSON data attached to users, groups, or messages | [Send Message](/sdk/flutter/send-message) |
| Tags | String labels for categorizing users, groups, conversations, or messages | [Additional Message Filtering](/sdk/flutter/additional-message-filtering) |
| RequestBuilder | Builder pattern class for constructing filtered/paginated queries | [Additional Message Filtering](/sdk/flutter/additional-message-filtering) |
| AppSettings | Configuration object for initializing the SDK (App ID, Region, presence) | [Setup SDK](/sdk/flutter/setup) |
| Transient Message | Ephemeral message not stored on server (typing indicators, live reactions) | [Transient Messages](/sdk/flutter/transient-messages) |
| Interactive Message | Message with actionable UI elements (forms, cards, buttons) | [Interactive Messages](/sdk/flutter/v4/interactive-messages) |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup SDK" icon="gear" href="/sdk/flutter/setup">
    Install and initialize the CometChat Flutter SDK
  </Card>

  <Card title="Authentication" icon="lock" href="/sdk/flutter/authentication-overview">
    Log users in and manage auth tokens
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/flutter/send-message">
    Send your first text or media message
  </Card>

  <Card title="Groups Overview" icon="users" href="/sdk/flutter/groups-overview">
    Create and manage group conversations
  </Card>
</CardGroup>


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