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

# Key Concepts

> Understand the fundamental building blocks of CometChat — users, groups, messaging categories, authentication, and 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

  Group types: `Public` | `Password` | `Private`
  Member scopes: `Admin` | `Moderator` | `Participant`
  Message categories: `message` | `custom` | `action` | `call` | `interactive`
</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.

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

## Authentication

CometChat does not handle user registration or friends management — you handle that in your app, then log users into CometChat programmatically.

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

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

| 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, retrieve 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

## 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 |
| `interactive` | `form`, `card`, `customInteractive` | Interactive messages (forms, cards) |

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

## Glossary

| Term | Definition | Learn More |
| - | - | - |
| UID | Unique User Identifier — alphanumeric string you assign to each user | [Users Overview](/sdk/react-native/users-overview) |
| GUID | Group Unique Identifier — alphanumeric string you assign to each group | [Groups Overview](/sdk/react-native/groups-overview) |
| Auth Key | Development-only credential for quick testing. Never use in production | [Authentication](/sdk/react-native/authentication-overview) |
| Auth Token | Secure, per-user token generated via REST API. Use in production | [Authentication](/sdk/react-native/authentication-overview#login-using-auth-token) |
| 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/react-native/send-message) |
| Scope | Group member scope: `admin`, `moderator`, or `participant` | [Change Member Scope](/sdk/react-native/group-change-member-scope) |
| Listener | Callback handler for real-time events (messages, presence, calls, groups) | [All Real-Time Listeners](/sdk/react-native/real-time-listeners) |
| Conversation | A chat thread between two users or within a group | [Retrieve Conversations](/sdk/react-native/retrieve-conversations) |
| Metadata | Custom JSON data attached to users, groups, or messages | [Send Message](/sdk/react-native/send-message) |
| Tags | String labels for categorizing users, groups, conversations, or messages | [Message Filtering](/sdk/react-native/additional-message-filtering) |
| RequestBuilder | Builder pattern class for constructing filtered/paginated queries | [Message Filtering](/sdk/react-native/additional-message-filtering) |
| AppSettings | Configuration object for initializing the SDK (App ID, Region, presence) | [Setup SDK](/sdk/react-native/setup-sdk) |
| Transient Message | Ephemeral message not stored on server (typing indicators, live reactions) | [Transient Messages](/sdk/react-native/transient-messages) |

***

## Next Steps

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

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

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

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


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