Getting Started

Add CometChat to a Flutter app in 5 steps: create project, install, init, login, render.

AI Agent Component Spec

Field	Value
Package	cometchat_chat_uikit
Init	CometChatUIKit.init(uiKitSettings) — must resolve before login()
Login	CometChatUIKit.login("UID") — must resolve before rendering widgets
Order	init() → login() → render. Breaking this order = blank screen
Auth Key	Dev/testing only. Use Auth Token in production
Calling	Optional. Install cometchat_calls_uikit to enable
Platforms	iOS 13.0+, Android API 24+ (with calling)

This guide walks you through adding CometChat to a Flutter app. By the end you’ll have a working chat UI.

---

Prerequisites

You need three things from the CometChat Dashboard:

Credential	Where to find it
App ID	Dashboard → Your App → Credentials
Auth Key	Dashboard → Your App → Credentials
Region	Dashboard → Your App → Credentials (e.g. us, eu, in)

You also need Flutter 3.0+ installed with Android Studio or VS Code.

Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API and use loginWithAuthToken(). Never ship Auth Keys in client code.

---

Step 1 — Create a Flutter Project

flutter create my_chat_app
cd my_chat_app

---

Step 2 — Install the UI Kit

Add to your pubspec.yaml:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  cometchat_chat_uikit: ^5.2.10
  cometchat_calls_uikit: ^5.0.12  # Optional: for voice/video calling

Then run:

flutter pub get

Android Setup — Update android/app/build.gradle:

build.gradle

android {
    defaultConfig {
        minSdk = 24  // Required for calling
    }
}

iOS Setup — Update ios/Podfile:

Podfile

platform :ios, '13.0'

Then run:

cd ios && pod install && cd ..

---

Step 3 — Initialize CometChat

Create a constants file and initialize the UI Kit before anything else.

lib/cometchat_config.dart

class CometChatConfig {
  static const String appId = "APP_ID";      // Replace with your App ID
  static const String region = "REGION";     // Replace with your Region
  static const String authKey = "AUTH_KEY";  // Replace with your Auth Key (dev only)
}

lib/main.dart

import 'package:flutter/material.dart';
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';  // Optional
import 'cometchat_config.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'CometChat Demo',
      home: const InitializerScreen(),
    );
  }
}

class InitializerScreen extends StatelessWidget {
  const InitializerScreen({super.key});

  Future<void> _initCometChat() async {
    final settings = (UIKitSettingsBuilder()
      ..appId = CometChatConfig.appId
      ..region = CometChatConfig.region
      ..authKey = CometChatConfig.authKey
      ..subscriptionType = CometChatSubscriptionType.allUsers
      ..autoEstablishSocketConnection = true
      ..extensions = CometChatUIKitChatExtensions.getDefaultExtensions()
      ..callingExtension = CometChatCallingExtension()  // Optional
    ).build();

    await CometChatUIKit.init(uiKitSettings: settings);
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: _initCometChat(),
      builder: (context, snapshot) {
        if (snapshot.connectionState != ConnectionState.done) {
          return const Scaffold(
            body: Center(child: CircularProgressIndicator()),
          );
        }
        if (snapshot.hasError) {
          return Scaffold(
            body: Center(child: Text('Init failed: ${snapshot.error}')),
          );
        }
        return const LoginScreen();
      },
    );
  }
}

init() must resolve before you call login(). If you call login() before init completes, it will fail silently.

---

Step 4 — Login

After init resolves, log the user in. For development, use one of the pre-created test UIDs:

cometchat-uid-1 · cometchat-uid-2 · cometchat-uid-3 · cometchat-uid-4 · cometchat-uid-5

CometChatUIKit.login(
  "cometchat-uid-1",
  onSuccess: (user) {
    debugPrint('Login successful: ${user.name}');
    // Navigate to chat screen
  },
  onError: (error) {
    debugPrint('Login failed: $error');
  },
);

Key points:

• getLoggedInUser() checks for an existing session so you don’t re-login unnecessarily.
• Widgets must not render until login resolves — use a state flag to gate rendering.

For production, use loginWithAuthToken() instead of Auth Key. Generate tokens server-side via the REST API.

---

Step 5 — Choose a Chat Experience

Integrate a conversation view that suits your app’s UX. Each option below includes a step-by-step guide.

Conversation List + Message View

Two-panel layout — conversation list with navigation to messages. Think WhatsApp or Telegram.

• Stack-based navigation with Navigator.push()
• Switch between one-to-one and group conversations
• Real-time updates and message sync across sessions

Build Conversation List + Message View

Step-by-step guide to build this layout

---

One-to-One / Group Chat

Single chat window — no conversation list. Good for support chat, embedded widgets, or focused messaging.

• Dedicated chat window for one-on-one or group messaging
• No conversation list — users go directly into the chat
• Ideal for support chat or contextual messaging

Build One-to-One / Group Chat

Step-by-step guide to build this layout

---

Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Groups in separate tabs. Good for full-featured apps.

• BottomNavigationBar with independent screens
• Unified experience for conversations, call history, and contacts
• Scales well for adding future features

Build Tab-Based Chat

Step-by-step guide to build this layout

---

Build Your Own Chat Experience

Need full control over the UI? Use individual widgets, customize themes, and wire up your own layouts.

• Sample App — Working reference app to compare against
• Components — All prebuilt UI widgets with props and customization options
• Core Features — Messaging, real-time updates, and other capabilities
• Theming — Colors, fonts, dark mode, and custom styling
• Build Your Own UI — Skip the UI Kit entirely and build on the raw SDK

---

Next Steps

Components Overview

Browse all prebuilt UI widgets

Theming

Customize colors, fonts, and styles

Core Features

Chat features included out of the box

Methods

Init, login, and other SDK methods