> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-angular-v5-docs-update.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/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/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>