cometchat-flutter-v6-events

Ground truth: every listener symbol below is catalog-verified against 6.1.0. There are TWO event systems and they are not interchangeable — the exact callback set for each is FETCHED from events (UI events) and the SDK's real-time-listeners via ../cometchat-flutter-v6-core/references/docs-map.md.

Companion skills (read first)

• cometchat-flutter-v6-core — install, credentials, init→login→render. This skill ASSUMES it.

Use this skill when

"do something when a message arrives", "update a badge count", "refresh my screen when a group changes", "cometchat listener" — anything reactive OUTSIDE what the kit's widgets already do for themselves.

Prerequisites & install

Covered by core. No new package.

First: do you actually need a listener?

The kit's widgets are already live. CometChatConversations updates its own unread counts, CometChatMessageList appends incoming messages, CometChatMessageHeader shows typing and presence — all without a single listener from you. Add one only for something OUTSIDE the kit's surface: an app-level badge, an analytics hook, a push registration, navigating on an incoming call.

Adding a listener to "make the list update" is the most common mistake here — it already does.

The two systems (BAKED)

	SDK listeners	UI Kit events
Source	the server, via CometChat.*	the kit's own widgets
Register	CometChat.addMessageListener(id, this)	CometChatMessageEvents.addMessagesListener(id, this)
Mixin	MessageListener · CallListener · UserListener · GroupListener · ConnectionListener	CometChatMessageEventListener · CometChatGroupEventListener · CometChatUserEventListener · CometChatConversationEventListener
Answers	"the server says X happened"	"the user did X in the kit"
Use for	badges, push, incoming calls, analytics	reacting to a kit action (message sent from the composer, group left via the kit)

SDK listener — server-side truth:

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:flutter/material.dart';

class BadgeHost extends StatefulWidget {
  const BadgeHost({super.key});
  @override
  State<BadgeHost> createState() => _BadgeHostState();
}

class _BadgeHostState extends State<BadgeHost> with MessageListener {
  static const _id = "app_badge";

  @override
  void initState() {
    super.initState();
    CometChat.addMessageListener(_id, this);
  }

  @override
  void dispose() {
    CometChat.removeMessageListener(_id);   // ALWAYS remove — see lifecycle below
    super.dispose();
  }

  @override
  void onTextMessageReceived(TextMessage message) {
    // bump an app-level unread badge
  }

  @override
  Widget build(BuildContext context) => const SizedBox.shrink();
}