Cometchat Flutter Realtime

CometChat Flutter SDK v5 Real-Time Events

Five listener types handle all real-time events. Each follows the same lifecycle: register in initState, remove in dispose, use unique IDs.

Listener Types Quick Reference

Note: addloginListener has lowercase 'l' — this is the actual SDK API.

Presence (Online/Offline)

Requires subscriptionType set during init. Without it, no presence events fire — no error thrown.

// During init — REQUIRED for presence to work
AppSettings appSettings = (AppSettingsBuilder()
  ..subscriptionType = CometChatSubscriptionType.allUsers
  ..region = "us"
).build();

Three subscription options:

• CometChatSubscriptionType.allUsers — all users (use unless >10k users)
• CometChatSubscriptionType.roles — specific roles only
• CometChatSubscriptionType.friends — friends only

class _ContactsScreenState extends State<ContactsScreen> with UserListener {
  static const _listenerId = "contacts_presence_listener";

  @override
  void initState() {
    super.initState();
    CometChat.addUserListener(_listenerId, this);
  }

  @override
  void dispose() {
    CometChat.removeUserListener(_listenerId);
    super.dispose();
  }

  @override
  void onUserOnline(User user) {
    // user.status == 'online', user.lastActiveAt updated
    setState(() { _updateUserStatus(user); });
  }

  @override
  void onUserOffline(User user) {
    // user.status == 'offline', user.lastActiveAt holds last seen time
    setState(() { _updateUserStatus(user); });
  }
}

Typing Indicators

Send typing status via CometChat, receive via MessageListener.

// Send — start typing
CometChat.startTyping(
  receiverUid: "cometchat-uid-1",
  receiverType: CometChatReceiverType.user,  // or .group with GUID
);

// Send — stop typing
CometChat.endTyping(
  receiverUid: "cometchat-uid-1",
  receiverType: CometChatReceiverType.user,
);

Receive via MessageListener:

@override
void onTypingStarted(TypingIndicator typingIndicator) {
  // typingIndicator.sender — User who is typing
  // typingIndicator.receiverId — UID or GUID
  // typingIndicator.receiverType — "user" or "group"
  setState(() { _isTyping = true; });
}

@override
void onTypingEnded(TypingIndicator typingIndicator) {
  setState(() { _isTyping = false; });
}

The SDK also exposes CometChat.onTypingIndicator() which returns a Stream<TypingIndicator> for stream-based consumption.

Typing on a Conversation List (Multi-Conversation)

The single-chat example above uses a boolean _isTyping. On a conversation list screen, you need to map typing events to specific conversations using a keyed map.

Key: build a conversation key from TypingIndicator fields to match against your conversation list.

// For 1:1 chats, the key is the sender's UID.
// For groups, the key is the receiverId (the GUID).
String _typingKey(TypingIndicator indicator) {
  return indicator.receiverType == 'group'
      ? indicator.receiverId
      : indicator.sender.uid;
}

Track typing state as a map of conversation key → typer's name:

// State: conversationKey → name of user typing
final Map<String, String> _typingMap = {};

@override
void onTypingStarted(TypingIndicator indicator) {
  final key = _typingKey(indicator);
  setState(() => _typingMap[key] = indicator.sender.name);
}

@override
void onTypingEnded(TypingIndicator indicator) {
  final key = _typingKey(indicator);
  setState(() => _typingMap.remove(key));
}

Then when rendering a conversation row, check _typingMap using the conversation partner's UID (for users) or GUID (for groups):

// Look up typing status for this conversation
final entity = conversation.conversationWith;
final String convKey;
if (entity is User) {
  convKey = entity.uid;
} else if (entity is Group) {
  convKey = entity.guid;
}
final typingName = _typingMap[convKey]; // null if nobody is typing

The SDK does not send onTypingEnded if the user disconnects or goes idle without explicitly stopping. Add a safety-net timer (5-8 seconds) that auto-clears stale typing entries from the map. This prevents "ghost" typing indicators if onTypingEnded is never received.

final Map<String, String> _typingMap = {};
final Map<String, Timer> _typingTimers = {};

@override
void onTypingStarted(TypingIndicator indicator) {
  final key = _typingKey(indicator);

  // Cancel any existing safety-net timer for this key
  _typingTimers[key]?.cancel();

  setState(() => _typingMap[key] = indicator.sender.name);

  // Safety-net: auto-clear after 6s if onTypingEnded never arrives
  _typingTimers[key] = Timer(const Duration(seconds: 6), () {
    if (mounted) setState(() => _typingMap.remove(key));
    _typingTimers.remove(key);
  });
}

@override
void onTypingEnded(TypingIndicator indicator) {
  final key = _typingKey(indicator);
  _typingTimers[key]?.cancel();
  _typingTimers.remove(key);
  setState(() => _typingMap.remove(key));
}

// Cancel all timers in dispose:
@override
void dispose() {
  for (final timer in _typingTimers.values) { timer.cancel(); }
  super.dispose();
}

Delivery & Read Receipts

Mark messages as delivered/read, receive receipt events via MessageListener.

// Mark as read — pass the BaseMessage object
CometChat.markAsRead(message,
  onSuccess: (String unused) { debugPrint("Marked as read"); },
  onError: (CometChatException e) { debugPrint("Failed: ${e.message}"); },
);

// Mark as delivered
CometChat.markAsDelivered(message,
  onSuccess: (String unused) { debugPrint("Marked as delivered"); },
  onError: (CometChatException e) { debugPrint("Failed: ${e.message}"); },
);

Receive receipt events:

@override
void onMessagesDelivered(MessageReceipt messageReceipt) {
  // messageReceipt.messageId, .sender, .receiverId, .deliveredAt
}

@override
void onMessagesRead(MessageReceipt messageReceipt) {
  // messageReceipt.messageId, .sender, .receiverId, .readAt
}

// Group-only (requires Enhanced Messaging Status feature):
@override
void onMessagesDeliveredToAll(MessageReceipt messageReceipt) { }

@override
void onMessagesReadByAll(MessageReceipt messageReceipt) { }

When to call markAsRead:

1. When message list is fetched (mark the last message)
2. When a real-time message arrives while the chat window is open

Connection Status

Monitor WebSocket connection state:

class _AppState extends State<App> with ConnectionListener {
  static const _listenerId = "app_connection_listener";

  @override
  void initState() {
    super.initState();
    CometChat.addConnectionListener(_listenerId, this);
  }

  @override
  void dispose() {
    CometChat.removeConnectionListener(_listenerId);
    super.dispose();
  }

  @override
  void onConnected() { debugPrint("WebSocket connected"); }

  @override
  void onConnecting() { debugPrint("WebSocket connecting..."); }

  @override
  void onDisconnected() { debugPrint("WebSocket disconnected"); }

  @override
  void onFeatureThrottled() { debugPrint("Features throttled"); }

  @override
  void onConnectionError(CometChatException error) {
    debugPrint("Connection error: ${error.message}");
  }
}

// Get current status synchronously
String status = CometChat.getConnectionStatus();
// Returns: CometChatWSState.connected / .connecting / .disconnected / .featureThrottled

The SDK auto-reconnects on disconnect. In auto mode: connected in foreground, disconnected in background.

Web-Specific Behavior

The SDK adapts WebSocket handling for web browsers:

• Lifecycle: AppLifecycleState.inactive is ignored on web (tab focus changes briefly trigger it, causing false disconnects on native). Only paused/detached/hidden trigger background disconnect on web.
• Pong timeout: 10 seconds on web (vs 3s on native). Browser timer throttling in background tabs can delay pong responses — the longer timeout prevents false reconnections.
• Tab resume: When a browser tab returns to foreground, the SDK resets any queued reconnection attempts before reconnecting. This prevents a storm of simultaneous reconnect attempts from timers that were throttled while the tab was in the background.

Anti-Patterns

No subscriptionType → no presence events:

// ❌ WRONG — presence silently disabled, no error
AppSettings appSettings = (AppSettingsBuilder()..region = "us").build();
// UserListener.onUserOnline/onUserOffline will NEVER fire

// ✅ CORRECT
AppSettings appSettings = (AppSettingsBuilder()
  ..subscriptionType = CometChatSubscriptionType.allUsers
  ..region = "us"
).build();

Listener leak — not removing in dispose():

// ❌ WRONG — events fire on disposed widget, causes setState errors
@override void initState() { CometChat.addUserListener("id", this); }
// Missing dispose cleanup

The SDK logs a warning when any listener map exceeds 10 entries — this strongly suggests a leak from missing removeListener() calls in dispose().

Duplicate listener IDs across screens:

// ❌ WRONG — second replaces first silently
CometChat.addMessageListener("listener", screenA);
CometChat.addMessageListener("listener", screenB);  // screenA stops receiving

Calling markAsRead without checking featureThrottled: The SDK validates connection state internally. If featureThrottled, markAsRead throws ERROR_RECEIPTS_TEMPORARILY_BLOCKED.

Re-fetching full conversation list on every new message:

// ❌ WRONG — nukes list, causes full screen rebuild on every message
void onNewMessage() {
  conversations = [];
  fetchAllConversations(); // O(n) network call, UI flashes
}

// ✅ CORRECT — use getConversation() to patch single item in-place
void onNewMessage(BaseMessage message) async {
  final (partner, type) = extractPartner(message, loggedInUid);
  final updated = await getConversation(partner, type);
  conversations.removeWhere((c) => c.conversationId == updated.conversationId);
  conversations.insert(0, updated); // move to top with updated lastMessage/unreadCount
}

See cometchat-flutter-compositions skill for the full partner extraction and patching pattern.

Checklist

• subscriptionType set during init (required for presence events)
• All listeners registered in initState, removed in dispose
• Unique listener IDs per screen/widget instance
• Typing indicators: startTyping on text input change, endTyping on send or pause
• Conversation list typing: use keyed map (not boolean) to track per-conversation typing state, with safety-net timer (5-8s) to auto-clear stale entries
• markAsRead called when chat window opens and on new real-time messages
• ConnectionListener registered at app level to handle reconnection UI
• onError callbacks handled (not empty) on markAsRead/markAsDelivered