Ground truth: cometchat_chat_uikit: ^5.2 (legacy/maintenance-only; calls via raw cometchat_calls_sdk ^5.0.2) — pub-cache source + ui-kit/flutter/v5. Official docs: https://www.cometchat.com/docs/ui-kit/flutter/v5/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

CometChat Flutter UIKit v5 — Events

Two layers: SDK listeners (low-level) and UIKit events (high-level component coordination).

Event System Architecture

Layer 1: SDK Listeners (CometChat SDK)

Raw message/call/user/group events from the network.

Layer 2: UIKit Events (CometChat UIKit)

High-level events emitted by UIKit components for UI coordination. Use a static Map<String, Listener> pattern.

Listener Registration Pattern

All event classes follow the same register/remove pattern:

// ✅ CORRECT — register in initState, remove in dispose
class _MyWidgetState extends State<MyWidget> {
  late final String _listenerId;

  @override
  void initState() {
    super.initState();
    _listenerId = 'my_widget_${DateTime.now().millisecondsSinceEpoch}';

    // UIKit events
    CometChatMessageEvents.addMessagesListener(_listenerId, this);
    CometChatUIEvents.addUiListener(_listenerId, this);

    // SDK listeners
    CometChat.addMessageListener(_listenerId, this);
    CometChat.addUserListener(_listenerId, this);
    CometChat.addGroupListener(_listenerId, this);
    CometChat.addCallListener(_listenerId, this);
  }

  @override
  void dispose() {
    CometChatMessageEvents.removeMessagesListener(_listenerId);
    CometChatUIEvents.removeUiListener(_listenerId);
    CometChat.removeMessageListener(_listenerId);
    CometChat.removeUserListener(_listenerId);
    CometChat.removeGroupListener(_listenerId);
    CometChat.removeCallListener(_listenerId);
    super.dispose();
  }
}

For GetxController, use onInit() / onClose() instead of initState() / dispose().

UIKit Event Classes — Registration

SDK Listeners — Registration

Key UIKit Events (commonly used)

CometChatUIEvents:

• openChat(User? user, Group? group) — request to open a chat

CometChatMessageEvents:

• ccMessageSent(BaseMessage message, MessageStatus status) — message sent
• ccMessageEdited(BaseMessage message, MessageEditStatus status) — message edited
• ccMessageDeleted(BaseMessage message, EventStatus status) — message deleted

CometChatUserEvents:

• ccUserBlocked(User user) / ccUserUnblocked(User user)

CometChatGroupEvents:

• ccGroupMemberKicked, ccGroupMemberBanned, ccGroupMemberAdded, ccOwnershipChanged

CometChatCallEvents:

• ccOutgoingCall(Call), ccCallAccepted(Call), ccCallRejected(Call), ccCallEnded(Call)

UIKit Events vs SDK Listeners

• UIKit events — react to UIKit-level actions (message sent via composer, group created via UI, user blocked via UI)
• SDK listeners — raw network events (message received, user online/offline, group member joined)
• UIKit components internally use both

Gotchas

Unique Listener IDs

// ❌ WRONG — hardcoded ID
CometChat.addMessageListener('messages', this);

// ✅ CORRECT — unique ID
final id = 'messages_${DateTime.now().millisecondsSinceEpoch}';
CometChat.addMessageListener(id, this);

Always Remove in dispose()

// ❌ WRONG — listener leaks
@override
void dispose() {
  super.dispose();
}

// ✅ CORRECT
@override
void dispose() {
  CometChat.removeMessageListener(_listenerId);
  super.dispose();
}

Never Register in build()

// ❌ WRONG — called every rebuild
@override
Widget build(BuildContext context) {
  CometChat.addMessageListener(id, this);
  return Container();
}

Checklist — Events

• [ ] Listener ID is unique (use timestamp or hashCode)
• [ ] Listener registered in initState() / onInit(), not build()
• [ ] Listener removed in dispose() / onClose() with same ID
• [ ] UIKit events for UI coordination, SDK listeners for raw events
• [ ] subscriptionType set in UIKitSettings for presence events to work