Events

Listen to and handle real-time events for users, groups, conversations, messages, calls, and UI interactions in Flutter UI Kit

AI Agent Component Spec

Field	Value
Package	cometchat_chat_uikit
Conversation events	ccConversationDeleted, ccUpdateConversation
User events	ccUserBlocked, ccUserUnblocked
Group events	ccGroupCreated, ccGroupDeleted, ccGroupLeft, ccGroupMemberScopeChanged, ccGroupMemberKicked, ccGroupMemberBanned, ccGroupMemberUnbanned, ccGroupMemberJoined, ccGroupMemberAdded, ccOwnershipChanged
Message events	ccMessageSent, ccMessageEdited, ccReplyToMessage, ccMessageDeleted, ccMessageRead, ccLiveReaction, ccMessageForwarded, plus SDK listener events
Call events	ccOutgoingCall, ccCallAccepted, ccCallRejected, ccCallEnded
UI events	ccActiveChatChanged, showPanel, hidePanel, openChat, ccComposeMessage, onAiFeatureTapped
Purpose	Decoupled communication between UI Kit components — subscribe to events to react to changes without direct component references

Quick Reference for AI Agents & Developers

// Add event listener
CometChatMessageEvents.addMessagesListener("LISTENER_ID", this);

// Remove event listener
CometChatMessageEvents.removeMessagesListener("LISTENER_ID");

// Implement listener methods
@override
void ccMessageSent(BaseMessage message, MessageStatus messageStatus) {
  // Handle message sent event
}

Available Event Types:

• User Events → Block/Unblock users
• Group Events → Create, delete, join, leave groups
• Conversation Events → Delete conversations, update conversations
• Message Events → Send, edit, delete, receive messages, reactions, AI messages
• Call Events → Outgoing, accepted, rejected, ended calls
• UI Events → Show/hide panels, active chat changes

Events allow for a decoupled, flexible architecture where different parts of the application can interact without having to directly reference each other. This makes it easier to create complex, interactive experiences, as well as to extend and customize the functionality provided by the CometChat UI Kit.

Both Components and Composite Components have the ability to emit events. These events are dispatched in response to certain changes or user interactions within the component. By emitting events, these components allow other parts of the application to react to changes or interactions, thus enabling dynamic and interactive behavior within the application.

---

User Events

CometChatUserEvents emit events when the logged-in user executes actions on another user. This class provides methods to add and remove listeners for user events, as well as methods to handle specific user actions such as blocking and unblocking users.

Available Events:

1. ccUserBlocked: Triggered when the logged-in user blocks another user.
2. ccUserUnblocked: Triggered when the logged-in user unblocks another user.

Dart

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

class UserEventsExample extends StatefulWidget {
  const UserEventsExample({super.key});

  @override
  State<UserEventsExample> createState() => _UserEventsExampleState();
}

class _UserEventsExampleState extends State<UserEventsExample> with CometChatUserEventListener {
  String listenerID = "unique_listener_ID";
  
  @override
  void initState() {
    super.initState();

    CometChatUserEvents.addUsersListener(listenerID, this); // Add the listener
  }

  @override
  void dispose() {
    super.dispose();

    CometChatUserEvents.removeUsersListener(listenerID); // Remove the listener
  }

  @override
  void ccUserBlocked(User user) {
    // TODO("Not yet implemented")
  }

  @override
  void ccUserUnblocked(User user) {
    // TODO("Not yet implemented")
  }

  @override
  Widget build(BuildContext context) {
    return const Placeholder();
  }
}

---

Group Events

CometChatGroupEvents Emits events when the logged-in user performs actions related to groups. This class provides methods to listen to various group-related events and handle them accordingly.

Available Events:

1. ccGroupCreated: Triggered when the logged-in user creates a group.
2. ccGroupDeleted: Triggered when the logged-in user deletes a group.
3. ccGroupLeft: Triggered when the logged-in user leaves a group.
4. ccGroupMemberScopeChanged: Triggered when the logged-in user changes the scope of another group member.
5. ccGroupMemberBanned: Triggered when the logged-in user bans a group member from the group.
6. ccGroupMemberKicked: Triggered when the logged-in user kicks another group member from the group.
7. ccGroupMemberUnbanned: Triggered when the logged-in user unbans a user banned from the group.
8. ccGroupMemberJoined: Triggered when the logged-in user joins a group.
9. ccGroupMemberAdded: Triggered when the logged-in user adds new members to the group.
10. ccOwnershipChanged: Triggered when the logged-in user transfers the ownership of their group to some other member.

Dart

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

class GroupEventsExample extends StatefulWidget {
  const GroupEventsExample({super.key});

  @override
  State<GroupEventsExample> createState() => _GroupEventsExampleState();
}

class _GroupEventsExampleState extends State<GroupEventsExample> with CometChatGroupEventListener {
  String listenerID = "unique_listener_ID";

  @override
  void initState() {
    super.initState();

    CometChatGroupEvents.addGroupsListener(listenerID, this); // Add the listener
  }

  @override
  void dispose() {
    super.dispose();

    CometChatGroupEvents.removeGroupsListener(listenerID); // Remove the listener
  }

  @override
  void ccGroupCreated(Group group) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupDeleted(Group group) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupLeft(sdk.Action message, User leftUser, Group leftGroup) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupMemberScopeChanged(sdk.Action message, User updatedUser, String scopeChangedTo, String scopeChangedFrom, Group group) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupMemberBanned(sdk.Action message, User bannedUser, User bannedBy, Group bannedFrom) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupMemberKicked(sdk.Action message, User kickedUser, User kickedBy, Group kickedFrom) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupMemberUnbanned(sdk.Action message, User unbannedUser, User unbannedBy, Group unbannedFrom) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupMemberJoined(User joinedUser, Group joinedGroup) {
    // TODO("Not yet implemented")
  }

  @override
  void ccGroupMemberAdded(List<sdk.Action> messages, List<User> usersAdded, Group groupAddedIn, User addedBy) {
    // TODO("Not yet implemented")
  }

  @override
  void ccOwnershipChanged(Group group, GroupMember newOwner) {
    // TODO("Not yet implemented")
  }

  @override
  Widget build(BuildContext context) {
    return const Placeholder();
  }
}

---

Conversation Events

The CometChatConversationEvents component emits events when the logged-in user performs actions related to conversations. This allows for the UI to be updated accordingly.

Available Events:

1. ccConversationDeleted: Triggered when the logged-in user deletes a conversation.
2. ccUpdateConversation: Triggered when a conversation is updated (e.g., unread count changes).

Dart

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

class ConversationEventsExample extends StatefulWidget {
  const ConversationEventsExample({super.key});

  @override
  State<ConversationEventsExample> createState() => _ConversationEventsExampleState();
}

class _ConversationEventsExampleState extends State<ConversationEventsExample> with CometChatConversationEventListener {
  String listenerID = "unique_listener_ID";

  @override
  void initState() {
    super.initState();

    CometChatConversationEvents.addConversationListListener(listenerID, this); // Add the listener
  }

  @override
  void dispose() {
    super.dispose();

    CometChatConversationEvents.removeConversationListListener(listenerID); // Remove the listener
  }
  
  @override
  void ccConversationDeleted(Conversation conversation) {
    // TODO("Not yet implemented")
  }

  @override
  void ccUpdateConversation(Conversation conversation) {
    // TODO("Not yet implemented")
  }

  @override
  Widget build(BuildContext context) {
    return const Placeholder();
  }
}

---

Message Events

CometChatMessageEvents emits events when various actions are performed on messages within the application. These events facilitate updating the UI accordingly.

Available Events:

1. ccMessageSent: Triggered whenever a logged-in user sends any message. It can have two states: inProgress and sent.
2. ccMessageEdited: Triggered whenever a logged-in user edits any message from the list of messages. It can have two states: inProgress and sent.
3. ccMessageDeleted: Triggered whenever a logged-in user deletes any message from the list of messages.
4. ccMessageRead: Triggered whenever a logged-in user reads any message.
5. ccLiveReaction: Triggered whenever a logged-in user clicks on a live reaction.
6. ccMessageForwarded: Triggered whenever a logged-in user forwards any message to a list of users or groups. It can have a state of status.
7. onTextMessageReceived: Triggered when a text message is received.
8. onMediaMessageReceived: Triggered when a media message is received.
9. onCustomMessageReceived: Triggered when a custom message is received.
10. onTypingStarted: Triggered when a typing indicator starts.
11. onTypingEnded: Triggered when a typing indicator ends.
12. onMessagesDelivered: Triggered when messages are delivered.
13. onMessagesRead: Triggered when messages are read.
14. onMessageEdited: Triggered when a message is edited.
15. onMessageDeleted: Triggered when a message is deleted.
16. onTransientMessageReceived: Triggered when a transient message is received.
17. onFormMessageReceived: Triggered when a form message is received.
18. onCardMessageReceived: Triggered when a card message is received.
19. onCustomInteractiveMessageReceived: Triggered when a custom interactive message is received.
20. onInteractionGoalCompleted: Triggered when an interaction goal is completed.
21. onSchedulerMessageReceived: Triggered when a scheduler message is received.
22. onMessageReactionAdded: Triggered when a reaction is added to a message.
23. onMessageReactionRemoved: Triggered when a reaction is removed from a message.
24. ccReplyToMessage: Triggered when the logged-in user replies to a message.
25. onMessagesDeliveredToAll: Triggered when messages are delivered to all recipients.
26. onMessagesReadByAll: Triggered when messages are read by all recipients.
27. onMessageModerated: Triggered when a message is moderated.
28. onAIAssistantMessageReceived: Triggered when an AI Assistant message is received.
29. onAIToolResultReceived: Triggered when an AI tool result is received.
30. onAIToolArgumentsReceived: Triggered when AI tool arguments are received.

Dart

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

class MessageEventsExample extends StatefulWidget {
  const MessageEventsExample({super.key});

  @override
  State<MessageEventsExample> createState() => _MessageEventsExampleState();
}

class _MessageEventsExampleState extends State<MessageEventsExample> with CometChatMessageEventListener {
  String listenerID = "unique_listener_ID";

  @override
  void initState() {
    super.initState();

    CometChatMessageEvents.addMessagesListener(listenerID, this); // Add the listener
  }

  @override
  void dispose() {
    super.dispose();

    CometChatMessageEvents.removeMessagesListener(listenerID); // Remove the listener
  }
  
  @override
  void ccMessageSent(BaseMessage message, MessageStatus messageStatus) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccMessageEdited(BaseMessage message, MessageEditStatus status) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccMessageDeleted(BaseMessage message, EventStatus messageStatus) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccMessageRead(BaseMessage message) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccLiveReaction(String reaction) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccMessageForwarded(BaseMessage message, List<User>? usersSent, List<Group>? groupsSent, MessageStatus status) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccReplyToMessage(BaseMessage message, MessageStatus status) {
    // TODO("Not yet implemented")  
  }

  @override
  void onTextMessageReceived(TextMessage textMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMediaMessageReceived(MediaMessage mediaMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onCustomMessageReceived(CustomMessage customMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onTypingStarted(TypingIndicator typingIndicator) {
    // TODO("Not yet implemented")  
  }

  @override
  void onTypingEnded(TypingIndicator typingIndicator) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessagesDelivered(MessageReceipt messageReceipt) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessagesRead(MessageReceipt messageReceipt) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessageEdited(BaseMessage message) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessageDeleted(BaseMessage message) {
    // TODO("Not yet implemented")  
  }

  @override
  void onTransientMessageReceived(TransientMessage message) {
    // TODO("Not yet implemented")  
  }

  @override
  void onFormMessageReceived(FormMessage formMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onCardMessageReceived(CardMessage cardMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onCustomInteractiveMessageReceived(
      CustomInteractiveMessage customInteractiveMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onInteractionGoalCompleted(InteractionReceipt receipt) {
    // TODO("Not yet implemented")  
  }

  @override
  void onSchedulerMessageReceived(SchedulerMessage schedulerMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessageReactionAdded(ReactionEvent reactionEvent) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessageReactionRemoved(ReactionEvent reactionEvent) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccReplyToMessage(BaseMessage message, MessageStatus status) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessagesDeliveredToAll(MessageReceipt messageReceipt) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessagesReadByAll(MessageReceipt messageReceipt) {
    // TODO("Not yet implemented")  
  }

  @override
  void onMessageModerated(BaseMessage message) {
    // TODO("Not yet implemented")  
  }

  @override
  void onAIAssistantMessageReceived(AIAssistantMessage aiAssistantMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onAIToolResultReceived(AIToolResultMessage aiToolResultMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  void onAIToolArgumentsReceived(AIToolArgumentMessage aiToolArgumentMessage) {
    // TODO("Not yet implemented")  
  }

  @override
  Widget build(BuildContext context) {
    return const Placeholder();
  }
}

---

Call Events

CometChatCallEvents emits events related to calls within the application. This class provides methods to listen to call-related events and handle them accordingly.

Available Events:

1. ccOutgoingCall: Triggered when the logged-in user initiates an outgoing call.
2. ccCallAccepted: Triggered when a call is accepted.
3. ccCallRejected: Triggered when a call is rejected.
4. ccCallEnded: Triggered when a call is ended.

Dart

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

class CallEventsExample extends StatefulWidget {
  const CallEventsExample({super.key});

  @override
  State<CallEventsExample> createState() => _CallEventsExampleState();
}

class _CallEventsExampleState extends State<CallEventsExample> with CometChatCallEventListener {
  String listenerID = "unique_listener_ID";

  @override
  void initState() {
    super.initState();

    CometChatCallEvents.addCallEventsListener(listenerID, this); // Add the listener
  }

  @override
  void dispose() {
    super.dispose();

    CometChatCallEvents.removeCallEventsListener(listenerID); // Remove the listener 
  }

  @override
  void ccOutgoingCall(Call call) {
    // TODO("Not yet implemented")
  }

  @override
  void ccCallAccepted(Call call) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccCallRejected(Call call) {
    // TODO("Not yet implemented")  
  }

  @override
  void ccCallEnded(Call call) {
    // TODO("Not yet implemented")  
  }

  @override
  Widget build(BuildContext context) {
    return const Placeholder();
  }
}

---

UI Events

CometChatUIEvents emits events related to UI components within the CometChat UI. This class provides methods to listen to UI-related events and handle them accordingly.

Available Events:

1. showPanel: Triggered to show an additional UI panel with custom elements.
2. hidePanel: Triggered to hide a previously shown UI panel.
3. ccActiveChatChanged: Triggered when the active chat changes, providing information about the current message, user, and group.
4. openChat: Triggered to open a chat with a specific user or group.
5. ccComposeMessage: Triggered when composing a message with a specific text and status.
6. onAiFeatureTapped: Triggered when an AI feature is tapped for a specific user or group.

Dart

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

class UIEventsExample extends StatefulWidget {
  const UIEventsExample({super.key});

  @override
  State<UIEventsExample> createState() => _UIEventsExampleState();
}

class _UIEventsExampleState extends State<UIEventsExample> with CometChatUIEventListener {
  String listenerID = "unique_listener_ID";

  @override
  void initState() {
    super.initState();

    CometChatUIEvents.addUiListener(listenerID, this); // Add the listener
  }

  @override
  void dispose() {
    super.dispose();

    CometChatUIEvents.removeUiListener(listenerID); // Remove the listener
  }

  @override
  void showPanel(Map<String, dynamic>? id, CustomUIPosition uiPosition, WidgetBuilder child) {
    // TODO("Not yet implemented")
  }

  @override
  void hidePanel(Map<String, dynamic>? id, CustomUIPosition uiPosition) {
    // TODO("Not yet implemented")
  }

  @override
  void ccActiveChatChanged(Map<String, dynamic>? id, BaseMessage? lastMessage, User? user, Group? group, int unreadMessageCount) {
    // TODO("Not yet implemented")
  }

  @override
  void openChat(User? user, Group? group) {
    // TODO("Not yet implemented")
  }

  @override
  void ccComposeMessage(String text, MessageEditStatus status) {
    // TODO("Not yet implemented")
  }

  @override
  void onAiFeatureTapped(User? user, Group? group) {
    // TODO("Not yet implemented")
  }

  @override
  Widget build(BuildContext context) {
    return const Placeholder();
  }
}

---

Best Practices

Always Remove Listeners

Always remove event listeners in the dispose() method to prevent memory leaks:

Dart

@override
void dispose() {
  super.dispose();
  CometChatMessageEvents.removeMessagesListener(listenerID);
}

Use Unique Listener IDs

Use unique listener IDs for each widget to avoid conflicts:

Dart

String listenerID = "message_list_${widget.key}";

Handle Events Efficiently

Keep event handlers lightweight and avoid heavy operations:

Dart

@override
void ccMessageSent(BaseMessage message, MessageStatus messageStatus) {
  if (messageStatus == MessageStatus.sent) {
    // Update UI efficiently
    setState(() {
      // Minimal state update
    });
  }
}

---

Next Steps

Message List

Learn how to display and manage messages with events

Conversations

Handle conversation events and updates

Groups

Manage group events and member actions

Methods

Explore available methods for UI Kit operations

---