> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-feat-user-history-moderation-detail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation Chat

> Complete messaging interface for one-on-one and group conversations with rich media support and real-time interactions

<Info>
  **Key Benefit**: Seamlessly integrate complete chat functionality into your application with pre-built components that handle messaging, media sharing, reactions, and replies out of the box.
</Info>

## Feature Overview

This UIKit is designed to seamlessly integrate messaging functionalities into your application, enabling rich conversations between users. Whether you're building a social network, a community platform, or a customer support system, our Conversation Chat UIKit equips you with everything you need to create engaging messaging experiences.

<CardGroup cols={2}>
  <Card title="Core Messaging" icon="comments">
    **Complete Chat Experience**

    * Send and receive text messages
    * Rich media support (images and videos)
    * Message editing and deletion
    * Real-time message delivery
  </Card>

  <Card title="Interactive Features" icon="heart">
    **Enhanced Engagement**

    * Message reactions with emojis
    * Message replies and quoted context
    * User action controls
    * Conversation management
  </Card>
</CardGroup>

<Info>
  **Platform Support**: Conversation Chat components are available on **iOS, Android, React, React Native, and Flutter**. On **React Native**, these screens ship from v4.3.0 as part of `AmityUiKitChat`, and from v4.3.1 each page can also be rendered on its own inside `AmityPageRenderer` — see [Quick Start](/uikit/components/chat/overview#quick-start-example). Only pages are exported on React Native; the building-block components shown here (list, bubble, composer, action sheets) aren't.
</Info>

## Implementation Guide

<Tabs>
  <Tab title="Main Chat Interface">
    **Complete chat conversation interface**

    The AmityChatPage serves as the main component for displaying and interacting with individual chat conversations in your application.

    ### Required Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `channelId` | String | Unique identifier for the chat channel |
    | `userId` | String | Current user's unique identifier |
    | `userDisplayName` | String | Display name for the current user |
    | `avatarUrl` | String | URL for the user's avatar image |

    ### Features

    | Feature | Description |
    | - | - |
    | Conversation View | Complete chat interface with message history and input controls |
    | Channel Management | Mute/unmute toggle and conversation settings |
    | Network Awareness | Offline mode indication and automatic reconnection |
    | Message Organization | Chronological display with date separators |
    | Link Preview | Automatic rich preview for shared URLs |

    ### Code Examples

    <CodeGroup>
      ```swift iOS theme={null}
      let page = AmityChatPage(channelId: "channelId")
      let viewController = AmitySwiftUIHostingController(rootView: page)
      ```

      ```kotlin Android theme={null}
      @Composable
      fun chatPage() {
          AmityChatPage(channelId = "channelId")
      }
      ```

      ```tsx React theme={null}
      import { AmityChatPage } from '@amityco/ui-kit';

      <AmityChatPage channelId="channelId" />;
      ```

      ```dart Flutter theme={null}
      Widget chatPage() {
        return AmityChatPage(
          channelId: 'channelId',
          userId: 'userId',
          userDisplayName: 'displayName',
          avatarUrl: 'avatarUrl',
        );
      }
      ```

      ```jsx React Native theme={null}
      // channelId is required; userDisplayName and jumpToMessageId are optional.
      <AmityPageRenderer>
        <AmityChatPage channelId="channelId" />
      </AmityPageRenderer>
      ```
    </CodeGroup>

    <Note>
      **Important Note**: The AmityChatPage automatically handles message loading, real-time updates, link previews, and user interactions.
    </Note>

    ### Chat Page Behavior

    Customize navigation and interaction behavior for the chat page.

    <CodeGroup>
      ```swift iOS theme={null}
      class CustomChatPageBehavior: AmityChatPageBehavior {
          override func onAvatarTap(context: AmityChatPageBehavior.Context) {
              // Route the header-avatar tap to your own screen.
          }
      }

      // Register once, e.g. at app start.
      AmityUIKit4Manager.behaviour.chatPageBehavior = CustomChatPageBehavior()
      ```

      ```kotlin Android theme={null}
      class CustomChatPageBehavior : AmityChatPageBehavior() {
          override fun onAvatarTap(context: Context, userId: String, avatarUrl: String?) {
              // Route the header-avatar tap to your own screen.
          }
      }

      // Register once, e.g. at app start.
      AmityChatBehaviorHelper.chatPageBehavior = CustomChatPageBehavior()
      ```

      ```dart Flutter theme={null}
      class CustomChatPageBehavior extends AmityChatPageBehavior {
        @override
        void onAvatarTap(
          BuildContext context,
          String? avatarUrl,
          String? userId,
        ) {
          // Route the header-avatar tap to your own screen.
        }
      }

      // Register once, e.g. at app start.
      AmityUIKit4Manager.behavior.chatPageBehavior = CustomChatPageBehavior();
      ```

      ```jsx React Native theme={null}
      // Pass handlers through the behaviour prop of AmityUiKitProvider.
      <AmityUiKitProvider
        /* ...credentials */
        behaviour={{
          AmityChatPageBehavior: {
            onAvatarTap: ({ userId, avatarUrl }) => {
              // Route the header-avatar tap to your own screen.
            },
          },
        }}
      >
        <AmityUiKitChat />
      </AmityUiKitProvider>
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Message Components">
    **Individual message rendering and composition**

    Components for displaying and creating messages within the chat interface.

    ### Message Bubble Rendering

    The AmityMessageBubble renders individual chat messages as bubbles in the conversation view.

    ### Features

    | Feature | Description |
    | - | - |
    | Content Rendering | Support for text, images, videos |
    | Interaction Handlers | Tap, long-press actions for message operations |
    | Rich Content | URL detection, media previews, and thumbnails |
    | Error Handling | Retry options for failed messages |

    ### Message Composition

    The AmityMessageComposer provides functionality for composing and sending messages within chat conversations.

    ### Required Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `subChannelId` | String | Sub-channel identifier for the conversation |
    | `avatarUrl` | String | URL for the user's avatar image |
    | `action` | MessageComposerAction | Callback actions for message events |

    ### Optional Parameters

    | Parameter | Type | Default | Platforms | Description |
    | - | - | - | - | - |
    | `mediaAttachmentLimit` | int | `10` | Flutter, from UIKit 4.20.18 | Maximum number of media files a user can select in one picker session |

    ### Code Examples

    <CodeGroup>
      ```swift iOS - Message List & Compose Bar theme={null}
      // Both components share one chat room view model.
      let viewModel = AmityChatRoomViewModel(channelId: "channelId")

      AmityChatMessageListComponent(viewModel: viewModel)
      AmityChatMessageComposeBar(viewModel: viewModel)
      ```

      ```kotlin Android - Message List & Compose Bar theme={null}
      @Composable
      fun conversationMessages() {
          // Both composables share one page view model.
          val viewModel = remember { AmityChatPageViewModel(channelId = "channelId") }

          AmityChatMessageList(viewModel = viewModel)
          AmityMessageComposer(viewModel = viewModel)
      }
      ```

      ```tsx React - Message List & Compose Bar theme={null}
      import { AmityChatPage } from '@amityco/ui-kit';

      // React does not expose the message list or compose bar separately for
      // conversation and group chat — they are rendered by the page component.
      // (AmityLiveChatMessageList and AmityLiveChatMessageComposeBar belong to Live Chat.)
      <AmityChatPage channelId="channelId" />;
      ```

      ```dart Flutter - Message List & Compose Bar theme={null}
      // Flutter renders each message with AmityMessageBubble rather than
      // exposing a list component.
      Widget messageBubbleView(AmityMessage message) {
        return AmityMessageBubble(
          message: message,
        );
      }

      Widget messageComposer() {
        return AmityMessageComposer(
          subChannelId: 'channelId',
          avatarUrl: 'avatarUrl',
          // Optional: cap how many media files the picker allows.
          mediaAttachmentLimit: 10,
          action: MessageComposerAction(
            onMessageCreated: () {
              // Handle message created callback
              print('Message created');
            },
            onDissmiss: () {
              // Handle dismiss callback
              print('Composer dismissed');
            },
          ),
        );
      }
      ```
    </CodeGroup>

    ### Message Bubble Behavior

    Override `AmityMessageBubbleBehavior` to route taps on a sender's **avatar** and on a **mentioned user** to your own screens. The mention-user tap override is available on iOS (UIKit 4.28.0), Android (UIKit 4.26.0), and React Native (UIKit 4.3.0).

    The two taps start from different defaults:

    | Override | Default behavior | Effect of overriding |
    | - | - | - |
    | `onAvatarTap` | Opens the full-screen avatar viewer. Does nothing if the user has no avatar. | Replaces the viewer — it no longer opens unless you open it yourself. |
    | `onMentionUserTap` | Does nothing. | Adds behavior where there was none. |

    <CodeGroup>
      ```swift iOS theme={null}
      class CustomMessageBubbleBehavior: AmityMessageBubbleBehavior {
          override func onAvatarTap(context: AmityMessageBubbleBehavior.Context) {
              // Route the sender-avatar tap to your own screen.
          }

          override func onMentionUserTap(context: AmityMessageBubbleBehavior.Context) {
              // Route a tap on a mentioned user to your own screen.
          }
      }

      // Register once, e.g. at app start.
      AmityUIKit4Manager.behaviour.messageBubbleBehavior = CustomMessageBubbleBehavior()
      ```

      ```kotlin Android theme={null}
      class CustomMessageBubbleBehavior : AmityMessageBubbleBehavior() {
          override fun onAvatarTap(context: Context, userId: String, avatarUrl: String?) {
              // Route the sender-avatar tap to your own screen.
          }

          override fun onMentionUserTap(context: Context, userId: String) {
              // Route a tap on a mentioned user to your own screen.
          }
      }

      // Register once, e.g. at app start.
      AmityChatBehaviorHelper.messageBubbleBehavior = CustomMessageBubbleBehavior()
      ```

      ```dart Flutter theme={null}
      class CustomMessageBubbleBehavior extends AmityMessageBubbleBehavior {
        @override
        void onAvatarTap(
          BuildContext context,
          String? avatarUrl,
          String? userId,
        ) {
          // Route the sender-avatar tap to your own screen.
        }
      }
      ```

      ```jsx React Native theme={null}
      // Pass handlers through the behaviour prop of AmityUiKitProvider.
      // Handlers receive { userId, avatarUrl? } and { userId } respectively.
      <AmityUiKitProvider
        /* ...credentials */
        behaviour={{
          AmityMessageBubbleBehavior: {
            onAvatarTap: ({ userId, avatarUrl }) => {
              // Route the sender-avatar tap to your own screen.
            },
            onMentionUserTap: ({ userId }) => {
              // Route a tap on a mentioned user to your own screen.
            },
          },
        }}
      >
        <AmityUiKitChat />
      </AmityUiKitProvider>
      ```
    </CodeGroup>

    <Note>
      **The header avatar is a separate hook.** `AmityMessageBubbleBehavior.onAvatarTap` covers only the sender avatar on a message bubble. The peer avatar in the conversation header is served by `AmityChatPageBehavior.onAvatarTap`, which takes the same arguments and also opens the avatar viewer by default. Override that one to redirect the header tap.
    </Note>
  </Tab>

  <Tab title="User Actions">
    **User interaction and management features**

    Bottom sheet component for performing actions on users within conversations.

    ### Features

    | Feature | Description |
    | - | - |
    | Notification Control | Mute/unmute notifications for the conversation |
    | User Management | Report/unreport and block/unblock user options |
    | Action Sheet UI | Clean bottom sheet interface for user actions |

    ### Required Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `user` | AmityUser | User object for the target user |
    | `isMute` | Boolean | Current mute status of the conversation |
    | `isUserBlocked` | Boolean | Current block status of the user |

    ### Code Examples

    <CodeGroup>
      ```dart Flutter theme={null}
      Widget conversationChatUserActionComponent() {
        // Create a user for this example
        final AmityUser user = AmityUser();

        return AmityConversationChatUserActionComponent(
          user: user,
          isMute: false,
          isUserBlocked: false,
        );
      }
      ```
    </CodeGroup>

    <Note>
      **User Actions**: This component provides a comprehensive set of user management actions while maintaining a clean and intuitive interface.
    </Note>

    ### User Actions Configuration

    Control which user actions are available in conversation chats through JSON configuration.

    #### Configuration Overview

    Configure which actions appear in the user action menu by enabling or disabling specific options in your AmityUIKitConfig.json file. Set `"enabled": false` for any action you want to hide from the user action menu.

    #### Available Actions

    | Action | Description | Default |
    | - | - | - |
    | `mute` | Mute/unmute notifications for the conversation | Enabled |
    | `report` | Report the user for inappropriate behavior | Enabled |
    | `block` | Block/unblock the user | Enabled |

    #### Configuration Examples

    <CodeGroup>
      ```json Default Configuration theme={null}
      {
        "conversation_chat_user_actions": [
          {
            "name": "mute",
            "enabled": true
          },
          {
            "name": "report",
            "enabled": true
          },
          {
            "name": "block",
            "enabled": true
          }
        ]
      }
      ```

      ```json Hide Report Action theme={null}
      {
        "conversation_chat_user_actions": [
          {
            "name": "mute",
            "enabled": true
          },
          {
            "name": "report",
            "enabled": false
          },
          {
            "name": "block",
            "enabled": true
          }
        ]
      }
      ```

      ```json Only Mute Action theme={null}
      {
        "conversation_chat_user_actions": [
          {
            "name": "mute",
            "enabled": true
          },
          {
            "name": "report",
            "enabled": false
          },
          {
            "name": "block",
            "enabled": false
          }
        ]
      }
      ```

      ```json All Actions Disabled theme={null}
      {
        "conversation_chat_user_actions": [
          {
            "name": "mute",
            "enabled": false
          },
          {
            "name": "report",
            "enabled": false
          },
          {
            "name": "block",
            "enabled": false
          }
        ]
      }
      ```
    </CodeGroup>

    <Note>
      **Global Configuration**: These user action configurations are set at the global level in AmityUIKitConfig.json and apply to all conversation chat components automatically.
    </Note>

    <Warning>
      **React Native**: v4.3.0 doesn't read `conversation_chat_user_actions`. All three actions — notification toggle, report, and block — are always shown.
    </Warning>

    #### Configuration Benefits

    | Benefit | Description |
    | - | - |
    | **Flexibility** | Enable only the actions that make sense for your app's use case |
    | **User Safety** | Control moderation and safety features available to users |
    | **Simplified UI** | Reduce clutter by hiding unnecessary options |
    | **Consistent Experience** | Global configuration ensures consistency across all conversations |

    #### Best Practices

    <AccordionGroup>
      <Accordion title="Action Selection Strategy" icon="sliders">
        **Choosing appropriate user actions**

        Consider your app's moderation strategy when configuring user actions. If you have a separate reporting system, you might disable the built-in report action. For community-focused apps, keep all safety features enabled to empower users.
      </Accordion>

      <Accordion title="User Safety Considerations" icon="shield">
        **Maintaining safe conversation environments**

        While you can disable actions, consider the impact on user safety. Block and report features are important safety tools. Only disable them if you have alternative mechanisms in place.
      </Accordion>

      <Accordion title="Configuration Testing" icon="flask">
        **Validating action configurations**

        Test your configuration changes thoroughly across different user scenarios. Ensure that disabling actions doesn't negatively impact user experience or safety features in your application.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Component Management Strategies

<AccordionGroup>
  <Accordion title="Component Integration" icon="puzzle-piece">
    **Integrating chat components into your app**

    The UIKit components are designed to work seamlessly together. Use AmityChatPage as your main interface, and leverage individual components like AmityMessageBubble and MessageComposer when you need granular control over specific parts of the chat experience.
  </Accordion>

  <Accordion title="UI Customization Strategy" icon="palette">
    **Tailoring the chat interface**

    Customize the appearance and behavior of chat components to match your app's design. The UIKit provides theming options and component configuration to align with your brand while maintaining core functionality.
  </Accordion>

  <Accordion title="User Flow Optimization" icon="route">
    **Designing intuitive chat experiences**

    Plan your navigation flow between chat components and other parts of your app. Consider how users will access conversations, manage settings, and interact with message features for the best user experience.
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Component Configuration" icon="gear">
    **Optimizing UIKit setup**

    Configure the UIKit components properly for your use case. Ensure proper parameter passing between components and handle callback functions appropriately. The underlying SDK handles all performance optimization automatically.
  </Accordion>

  <Accordion title="User Experience Design" icon="user">
    **Creating engaging chat interfaces**

    Focus on clear visual hierarchy, intuitive interaction patterns, and responsive design. The UIKit provides pre-built interactions while allowing you to customize the presentation layer to match your app's experience.
  </Accordion>

  <Accordion title="Error Handling & Feedback" icon="triangle-exclamation">
    **Managing user interactions gracefully**

    Implement proper error handling for user actions and provide clear feedback for loading states, connection issues, and user interactions. The SDK manages network reliability while the UIKit handles user interface feedback.
  </Accordion>
</AccordionGroup>

## Related Features

<CardGroup cols={3}>
  <Card title="Chat Overview" href="/uikit/components/chat" icon="book">
    **All Chat Components**
    Summary & architecture
  </Card>

  <Card title="Group Chat" href="/uikit/components/chat/group-chat" icon="users">
    **Multi-user Features**
    Roles & member tools
  </Card>

  <Card title="Live Chat" href="/uikit/components/chat/live-chat" icon="tobroadcast">
    **Streaming Chat**
    High-volume events
  </Card>
</CardGroup>

<Tip>
  **Implementation Strategy**: Start with the AmityChatPage component for a complete chat experience, then customize individual components like AmityMessageBubble and MessageComposer as needed for your specific use case.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.