Key Concepts

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

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

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

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.

Create your apps in the CometChat Dashboard — 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.

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

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

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

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

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

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

Auto Mode Connection

Know more about auto mode connection click here

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

Manual Mode Connection

Know more about manual mode connection click here

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

---

Next Steps

Setup SDK

Install and initialize the CometChat Flutter SDK

Authentication

Log users in and manage auth tokens

Send Messages

Send your first text or media message

Groups Overview

Create and manage group conversations