> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-skills-v5-temp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Handle CometChat Flutter UI Kit events for users, groups, messages, conversations, calls, and UI-level interactions.

<Accordion title="AI Integration Quick Reference">
  | Field       | Value                                                                                                                                                                                                                         |
  | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package     | `cometchat_chat_uikit`                                                                                                                                                                                                        |
  | Import      | `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`                                                                                                                                                            |
  | Purpose     | Handle CometChat Flutter UI Kit events for users, groups, messages, conversations, calls, and UI-level interactions.                                                                                                          |
  | Key classes | `CometChatMessageEvents` · `CometChatCallEvents` · `CometChatConversationEvents` · `CometChatGroupEvents` · `CometChatUIEvents` · `CometChatUserEvents` · `CometChatCallEventListener`                                        |
  | Key methods | `sendCustomMessage()`                                                                                                                                                                                                         |
  | Emitting    | A message sent with `CometChat.send*Message` instead of through `CometChatMessageComposer` must emit `CometChatMessageEvents.ccMessageSent(...)` in `onSuccess`, or an already-mounted `CometChatMessageList` never shows it. |
  | Related     | [Methods](/ui-kit/flutter/methods) · [Core Features](/ui-kit/flutter/core-features)                                                                                                                                           |
</Accordion>

## Overview

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.

> The event system is identical between V5 and V6. All event classes, listeners, and APIs work the same way.

### User Events

`CometChatUserEvents` emit events when the logged-in user executes actions on another user.

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class _YourScreenState extends State<YourScreen> with CometChatUserEventListener {
      @override
      void initState() {
        super.initState();
        CometChatUserEvents.addUsersListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatUserEvents.removeUsersListener("listenerId");
      }

      @override
      void ccUserBlocked(User user) {
        // Handle user blocked
      }

      @override
      void ccUserUnblocked(User user) {
        // Handle user unblocked
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### Group Events

`CometChatGroupEvents` emits events when the logged-in user performs actions related to groups.

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.
6. `ccGroupMemberKicked`: Triggered when the logged-in user kicks a group member.
7. `ccGroupMemberUnbanned`: Triggered when the logged-in user unbans a user.
8. `ccGroupMemberJoined`: Triggered when the logged-in user joins a group.
9. `ccGroupMemberAdded`: Triggered when the logged-in user adds new members.
10. `ccOwnershipChanged`: Triggered when the logged-in user transfers ownership.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class _YourScreenState extends State<YourScreen> with CometChatGroupEventListener {
      @override
      void initState() {
        super.initState();
        CometChatGroupEvents.addGroupsListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatGroupEvents.removeGroupsListener("listenerId");
      }

      @override
      void ccGroupCreated(Group group) {
        // Handle group created
      }

      @override
      void ccGroupDeleted(Group group) {
        // Handle group deleted
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### Message Events

`CometChatMessageEvents` emit events when the logged-in user executes actions on a message.

1. `ccMessageSent`: Triggered when the logged-in user sends a message.
2. `ccMessageEdited`: Triggered when the logged-in user edits a message.
3. `ccMessageDeleted`: Triggered when the logged-in user deletes a message.
4. `ccMessageRead`: Triggered when the logged-in user reads a message.
5. `ccLiveReaction`: Triggered when the logged-in user sends a live reaction.
6. `ccMessageForwarded`: Triggered when the logged-in user forwards a message.
7. `ccReplyToMessage`: Triggered when the logged-in user replies to a message.
8. `onFormMessageReceived`: Triggered when a [form message](/sdk/flutter/interactive-form-message) is received.
9. `onSchedulerMessageReceived`: Triggered when a [scheduler message](/sdk/flutter/interactive-scheduler-message) is received.
10. `onCustomInteractiveMessageReceived`: Triggered when a custom interactive message is received.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'package:flutter/material.dart';

    class _YourScreenState extends State<YourScreen> with CometChatMessageEventListener {
      @override
      void initState() {
        super.initState();
        CometChatMessageEvents.addMessagesListener("listenerId", this);
      }

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

      @override
      void ccMessageRead(BaseMessage message) {
        // Handle message read
      }

      @override
      void ccReplyToMessage(BaseMessage message) {
        // Handle reply
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

#### Emitting `ccMessageSent` for messages you send yourself

`CometChatMessageComposer` emits `ccMessageSent` for you. If you send a message with the SDK directly
— `CometChat.sendCustomMessage`, `sendTextMessage`, `sendMediaMessage` — you must emit it yourself, or
an already-mounted `CometChatMessageList` will not show that message.

CometChat does not deliver your own sends back to you over the real-time listener, so a list that is
already on screen has no way to learn about them and only picks them up on its next fetch. That hides
the problem whenever a chat screen is opened fresh each time, and surfaces it as soon as a list stays
mounted — for example a chat panel kept alongside other UI.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    // `ccMessageSent` takes the `MessageStatus` declared in the UI Kit's core constants.
    // The package barrel exports a different enum of the same name, so import this one
    // under a prefix. The same applies to `ccMessageEdited` (`MessageEditStatus`),
    // `ccMessageDeleted` (`EventStatus`) and `ccMessageForwarded` — whether you are
    // emitting these events or overriding them in a listener.
    import 'package:cometchat_chat_uikit/shared_ui/src/clean_architecture/core/constants/enums.dart'
        as core_enums;

    Future<void> sendGameEvent(CustomMessage message) async {
      await CometChat.sendCustomMessage(
        message,
        onSuccess: (sent) {
          CometChatMessageEvents.ccMessageSent(sent, core_enums.MessageStatus.sent);
        },
        onError: (e) {
          // Handle send failure
        },
      );
    }
    ```
  </Tab>
</Tabs>

***

### Conversation Events

`CometChatConversationEvents` emits events related to conversations.

1. `ccConversationDeleted`: Triggered when a conversation is deleted.
2. `ccUpdateConversation`: Triggered when a conversation is updated — for example when it is marked as unread.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class _YourScreenState extends State<YourScreen> with CometChatConversationEventListener {
      @override
      void initState() {
        super.initState();
        CometChatConversationEvents.addConversationListListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatConversationEvents.removeConversationListListener("listenerId");
      }

      @override
      void ccConversationDeleted(Conversation conversation) {
        // Handle conversation deleted
      }

      @override
      void ccUpdateConversation(Conversation conversation) {
        // Handle conversation updated
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### Call Events

`CometChatCallEvents` emit events when the logged-in user acts on a call. They are UI-Kit
events — distinct from the Calls SDK's own listeners — and fire for calls started or
answered through the kit's calling widgets.

1. `ccOutgoingCall`: Triggered when the logged-in user initiates an outgoing call.
2. `ccCallAccepted`: Triggered when the logged-in user accepts an incoming call.
3. `ccCallRejected`: Triggered when the logged-in user rejects an incoming call.
4. `ccCallEnded`: Triggered when a call the logged-in user was on has ended.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'package:flutter/material.dart';

    class _YourScreenState extends State<YourScreen> with CometChatCallEventListener {
      @override
      void initState() {
        super.initState();
        CometChatCallEvents.addCallEventsListener("listenerId", this);
      }

      @override
      void dispose() {
        super.dispose();
        CometChatCallEvents.removeCallEventsListener("listenerId");
      }

      @override
      void ccOutgoingCall(Call call) {
        // Handle outgoing call initiated
      }

      @override
      void ccCallEnded(Call call) {
        // Handle call ended
      }

      @override
      Widget build(BuildContext context) {
        return const Placeholder();
      }
    }
    ```
  </Tab>
</Tabs>

***

### UI Events

`CometChatUIEvents` emits `CometChatUIEventListener` callbacks for UI-level actions such as panel visibility, active chat changes, and card action taps. Add a listener with `CometChatUIEvents.addUiListener(listenerId, this)` and remove it in `dispose()`.

**Event types:**

| Event                                                                   | Description                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showPanel(id, uiPosition, child)`                                      | Triggered to show an additional UI panel with custom elements.                                                                                                                                                                                                  |
| `hidePanel(id, uiPosition)`                                             | Triggered to hide a previously shown UI panel.                                                                                                                                                                                                                  |
| `ccActiveChatChanged(id, lastMessage, user, group, unreadMessageCount)` | Triggered when the active chat changes.                                                                                                                                                                                                                         |
| `openChat(user, group)`                                                 | Triggered to open a chat with a specific user or group.                                                                                                                                                                                                         |
| `ccComposeMessage(text, status)`                                        | Triggered when composing a message with a specific text and status.                                                                                                                                                                                             |
| `onAiFeatureTapped(user, group)`                                        | Triggered when an AI feature is tapped for a specific user or group.                                                                                                                                                                                            |
| `ccCardActionClicked(message, action)`                                  | Triggered when a user taps an interactive element (button/link) inside a [card message](/sdk/flutter/send-message#card-message) (`CardMessage`) or an AI agent card (`AIAssistantMessage`). `action` is typed `dynamic`; cast it to `CometChatCardActionEvent`. |
| `requestComposerFocus(id)`                                              | Ask `CometChatMessageComposer` to focus its text field, which opens the OS keyboard.                                                                                                                                                                            |
| `lockBottomPadding(id, height)`                                         | Hold the composer's bottom padding at a fixed `height` instead of tracking the keyboard — use it while your own panel occupies that space.                                                                                                                      |
| `unlockBottomPadding(id)`                                               | Release a previous `lockBottomPadding` and return to normal keyboard-based padding.                                                                                                                                                                             |

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class _YourScreenState extends State<YourScreen> with CometChatUIEventListener {
      final String listenerId = "unique_listener_id";

      @override
      void initState() {
        super.initState();
        CometChatUIEvents.addUiListener(listenerId, this);
      }

      @override
      void dispose() {
        CometChatUIEvents.removeUiListener(listenerId);
        super.dispose();
      }

      @override
      void ccCardActionClicked(BaseMessage message, dynamic action) {
        // message -> CardMessage (standalone) or AIAssistantMessage (agent card)
        if (action is CometChatCardActionEvent) {
          debugPrint("Action: ${action.action}");
          debugPrint("Element ID: ${action.elementId}");
          debugPrint("Card JSON: ${action.cardJson}");
          // Handle navigation, API calls, etc.
        }
      }

      @override
      Widget build(BuildContext context) => const Placeholder();
    }
    ```
  </Tab>
</Tabs>

<Note>
  The UI Kit renders card bubbles automatically (`CometChatCardBubble`) and emits `ccCardActionClicked` when a user taps an action inside one — so a single subscriber handles every card action across your app. `message` is a `CardMessage` for standalone [card messages](/sdk/flutter/send-message#card-message) and an `AIAssistantMessage` for cards embedded in AI agent replies. Cast `action` to `CometChatCardActionEvent` to read its `action`, `elementId`, and `cardJson`. See also [Methods → UI Events — Card Actions](/ui-kit/flutter/methods#ui-events--card-actions).
</Note>