# Chat ## Overview The **Chat component** displays threaded conversations on Lightning Pages. Use it for internal collaboration, customer communication, or any workflow where messaging adds value to a Salesforce record. *** ## Quick Start: Build a Case Chat in 2 Minutes **Want to see the component in action immediately?** Follow these 7 steps to add a functional Case Comment history to a Case Record Page.
{% stepper %} {% step %} #### Create a New Component * Open the **Avonni Dynamic Components** App. * Click the **New** button to create a new component. * **Name:** Enter a name (e.g., "Case Chat History"). * **Target Page Object:** Select **Case**. * *Critical:* [The Target Page Object](https://docs.avonnicomponents.com/dynamic-components/getting-started/understanding-the-essentials/target-page-object) setting tells the component it is operating in the context of a Case record, allowing variables like `{!RecordId}` to function correctly. {% endstep %} {% step %} #### Add the Component to the Canvas * From the **Component Library** (left sidebar), search for **Chat**. * Drag and drop the **Chat** component onto the main canvas {% endstep %} {% step %} #### Configure the **Data Source to Query** We need to fetch the Case Comment records from Salesforce. * Select the **Chat** component on the canvas. * In the Properties Panel (right), set **Data Source** to **Query**. * **Object:** Select `CaseComment`. * **Filter:** * Click **Add Filter**. * Field: `ParentId`. * Operator: `Equal`. * Value: `{!$Component.RecordId}`. * *Why: This ensures we only load comments for the specific Case currently being viewed.* * **Order By:** `CreatedDate ASC` (Oldest to Newest).
{% endstep %} {% step %} #### Map the Query Fields Connect the fields returned by your Query to the Chat component attributes. * Scroll down to the **Data Mappings** section. * **Content:** Select `Body`. * *Note: This maps the actual text of the comment to the message bubble.* * **Date:** Select `CreatedDate`. **Check the Preview:** The canvas should now display the conversation history for the context record. If the preview is empty, ensure the Preview Context is set to a case from the Debug Panel.
{% endstep %} {% step %} #### Configure the Publisher Set up the input box for new messages. * Scroll to the **Publisher** section. * **Mode:** Set to `Rich`. * **Button Label:** Change "Send" to `Post Comment`. * **Placeholder:** Enter `Type a reply...`.
{% endstep %} {% step %} #### Add the "Save" Logic (Interaction) Make the "Post Comment" button functional. * Click the **Interactions** tab in the Properties Panel. * Click **Add Interaction**. * **Trigger:** Select `On Message Publish`. * **Action:** Select `Enter Record Data Manually`. * **Object:** Select `CaseComment`. * **Field Mappings:** * **ParentId:** `{$Component.RecordId}` (Links the comment to this Case). * **CommentBody:** `Message: Content` (Captures your typed text).
{% endstep %} {% step %} #### Save and Activate * Click **Save**. * Use the **Deploy** button to add this dynamic component to your actual Salesforce Case Lightning Page {% endstep %} {% endstepper %} *** ## Configuration Select the Chat component on the canvas to access the Properties Panel. Configuration involves defining your participants (Resources), populating the message history, and managing how the publisher interacts with your data. ### Connecting to Message Data (Data Source) You can populate the chat history using either the **Manual** or **Query** method. #### **Option A: Manual Data Source** The Manual data source is ideal for prototyping a conversation or displaying a fixed set of messages. Setting this up is a **two-step process**: you must define the people in the conversation before you can create the messages they sent. **Step 1: Define Your Resources** Resources represent the individuals or entities involved in the chat. * **Name**: The display name of the person (e.g., "Customer Support" or "John Doe"). * **Avatar Source**: A URL for the user's profile image. * **Avatar Fallback Icon**: An icon (e.g., `standard:user`) to show if no image is available. * **Avatar Initials**: Text (e.g., "JD") used as a placeholder. **Step 2: Create the Messages** Once your Resources are saved, you can begin building the message history. {% hint style="warning" %} #### Technical Requirement You must create at least one Resource first. The system uses these resources to populate the Participant Name picklist {% endhint %} * **Participant Name**: Select the sender from the picklist (this list is automatically generated from your defined Resources). * **Type**: Define the direction of the bubble. * **Inbound**: Messages received from others. * **Outbound**: Messages sent by the current user. * **Date**: The timestamp indicating when the message was sent. * **Body**: The actual text or content of the message #### **Option B: Query Data Source** Use this to dynamically fetch records from Salesforce (e.g., pulling all comments related to a Case). 1. Select **Data Source**: Choose [Query](https://docs.avonnicomponents.com/dynamic-components/component-builder/data-sources/query). 2. **Define Query**: Select the Object (e.g., `CaseComment`) and set filters (e.g., `ParentId equals recordId`) to fetch the correct records. 3. **Data Mappings**: Map the fields from your query to the chat display. * **Content**: Select the field containing the message body (e.g., `CommentBody`). * **Date**: Select the field containing the timestamp (e.g., `CreatedDate`). *** ### General Settings These settings control the overall behavior of the chat component, including how messages are attributed and displayed. | Setting | Description | Example / Options | | ----------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------- | | **Current Resource ID** | ID of the message author; determines sent vs. received positioning. Defaults to current user if empty. | `{!$User.Id}` | | **Read Only** | Hides the publisher; users can view messages but not send new ones. (Default: off) | true / false | | **Disabled** | Grays out the entire component; prevents all interaction. (Default: off) | true / false | | **Message Date Format** | Controls how timestamps display on messages. | `MMM d, yyyy h:mm a` → "Jan 15, 2025 2:30 PM" | *** ### Publisher Settings Customize the input area where users type new messages. | Setting | Description | Example / Options | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | **Mode** | Switches between a rich text editor (with formatting toolbar) and a plain text input. | Rich, Plain (Default: Rich) | | **Allow Mentions** | Enables the `@` mention feature. When active, typing `@` followed by a name opens a searchable dropdown of participants. Only available when Mode is **Rich**. | true / false (Default: off) | | **Mentionable Participants IDs** | Restricts which participants can be mentioned. Pass a text collection of record IDs, or a semicolon-separated string. If left empty, all records from the participant object are mentionable. Only visible when **Allow Mentions** is checked. | `{!MentionableUserIds}` or `Id1;Id2;Id3` | | **Placeholder** | Ghost text displayed in the empty input area. | `Type a reply...` | | **Publish Button Label** | Label on the send button. | `Post Comment`, `Send` | | **Maximum Length** | Maximum characters allowed per message. Prevents publishing if exceeded. | 5000 | | **Minimum Length** | Required characters before sending is allowed. | 10 | | **Show Character Count** | Displays a live character counter below the input. (Default: off) | true / false | | **Toolbar Position** | Where the rich text formatting toolbar appears relative to the input. | Top, Bottom | #### Customizing the Rich Text Toolbar When the publisher Mode is set to Rich, you can choose exactly which formatting tools are available to your users. These are organized into Categories to keep the interface clean
CategoryTools IncludedBest For
FontFont Family, Font SizeStandardizing brand typography.
TextB, I, <u>U</u>, ~~S~~Basic emphasis and strike-throughs.
BodyLists (Bulleted/Numbered), Alignment, IndentsOrganizing long-form updates or technical notes.
HeaderH1, H2, H3Creating structured, easy-to-read sections.
ColorText Color PickerHighlighting specific words with custom colors.
HighlightBackground Color PickerHighlighting specific words with custom colors.
Clean UpRemove FormattingQuickly stripping copied text of messy external styling.
#### **Blocked Words** Define words that cannot be included in published messages. When users attempt to send messages containing blocked words, the publish action is prevented. *** ## Real-Time Updates (Platform Events) By default, the Chat component only refreshes when you post a message or manually reload the page. To create a true "instant messaging" experience—where replies from colleagues or customers appear the moment they are sent—you can enable Platform Events. #### How to Enable Live Updates This configuration allows the component to "listen" for database changes and automatically refresh its query. 1. Set **Data Source**: Ensure it is set to **Query**. 2. Locate **EMP Settings**: Expand **Advanced Options** and find the **Query Refresh EMP section**. 3. **Channel Name**: Enter the API name of your Platform Event (e.g., `Chat_Notification__e`). 4. **Key Field Name**: Enter the API name of the field within that event that stores the Record ID (e.g., `RecordId__c`). {% hint style="warning" %} #### Note Enabling this feature requires a pre-configured **Platform Event** and a **Trigger Flow** in Salesforce to publish the notification whenever a new message record is created. {% endhint %} Tutorial: How to Set Up Platform Events *** ## Interactions Without an Interaction, the Chat component is read-only — users can view messages, but clicking the publish button has no effect. Interactions connect the **Publish a New Message** event to a Salesforce action (such as creating a record or executing a Flow). The Chat component exposes **one trigger**: | Trigger | Fires When | Common Actions | | ------------------------- | ---------------------------------- | ---------------------------------------- | | **Publish a New Message** | The user clicks the publish button | Enter Record Data Manually, Execute Flow | When this trigger fires, two **output variables** become available for use as flow input variables: | Output Variable | Type | Contains | | ----------------------------- | --------------- | ---------------------------------------------------------------------------------------------------- | | **Last Publication Value** | Text | The full content of the published message | | **Last Publication Mentions** | Text Collection | The record IDs of all participants mentioned with `@` in the message. Empty if no one was mentioned. | ### Saving a Message (Standard Setup) This is the most common configuration — saving the published message as a new Salesforce record. 1. Click the **Interactions** tab in the Properties Panel. 2. Click **Add Interaction**. 3. **Trigger**: Select **Publish a New Message**. 4. **Action**: Select **Enter Record Data Manually**. 5. **Object**: Select `CaseComment` (or your target object). 6. **Field Mappings**: * `ParentId` → `{!$Component.RecordId}` (links the comment to the current record) * `CommentBody` → `Message: Content` (captures the typed message) ### Setting Up @Mentions Mentions work in two parts: the **UI** (the `@` dropdown) and the **action** (doing something with the mentioned IDs). Both require configuration. {% stepper %} {% step %} #### Enable the @Mention UI In the Properties Panel, scroll to the **Publisher** section: * Set **Mode** to **Rich** (mentions are not available in Plain mode). * Check **Allow Mentions**. * (Optional) Set **Mentionable Participants IDs** to a text collection of specific record IDs. If left empty, all records from the participant object are mentionable. At this point, users can type `@` in the publisher and see a searchable dropdown of participants {% endstep %} {% step %} #### Add the Publish Interaction with Execute Flow The `@` dropdown is now working, but the mentioned IDs go nowhere unless you pass them to a Flow. 1. Click the **Interactions** tab. 2. Click **Add Interaction**. 3. **Trigger**: Select **Publish a New Message**. 4. **Action**: Select **Execute Flow**. 5. Select an **Autolaunched Flow** you have built in Salesforce. 6. In the flow's **Input Variables**, map: * **Last Publication Mentions** → this is the text collection of record IDs for everyone mentioned with `@`. * **Last Publication Value** → the full message content (optional, but useful for notification context). * `{!$Component.RecordId}` → the current record ID (optional, to include a link back to the record). > **Why this step matters**: Without this interaction, the mention data is discarded after publish. The Flow is what makes it actionable — sending notifications, creating Tasks, posting to Slack, or anything else you build in Flow Builder. > {% endstep %} {% step %} #### Build the Autolaunched Flow In Salesforce Flow Builder, create an **Autolaunched Flow** that receives the input variables and acts on them. For example: * **Input**: `MentionedUserIds` (Text Collection), `MessageContent` (Text), `RecordId` (Text) * **Action**: Loop through `MentionedUserIds` and create a Task for each mentioned user, or send a custom notification. This Flow runs every time a user publishes a message that contains `@` mentions {% endstep %} {% endstepper %} {% hint style="info" %} #### You Can Combine Both Actions If you need to both save the message as a record **and** run mention-based automation, add two actions under the same **Publish a New Message** trigger: one **Enter Record Data Manually** to create the record, and one **Execute Flow** to handle the mentions {% endhint %} *** ## Example ### Project Discussion Log **Goal**: Create a chat interface on a custom "Project" object. This allows the project team to discuss updates and have those messages saved to a custom "Project Update" object. {% stepper %} {% step %} #### Create the Component * Open the **Avonni Dynamic Components** App. * Click **New**. * **Name:** Enter "Project Team Chat". * **Target Page Name:** Select your custom object (e.g., **Project** or `Project__c`). * *Why:* This is critical. It tells the component it is operating in the context of a Project record, enabling the use of the `{!RecordId}` variable. {% endstep %} {% step %} #### Add Component to Canvas * From the **Component Library** (left sidebar), search for **Chat**. * Drag and drop the **Chat** component onto the canvas. {% endstep %} {% step %} #### Connect to the Data Source We need to query the custom object that will store messages. * **Data Source:** Query. * **Object:** `Project_Update__c` (Custom Object). * **Filter:** `Project__c` equals `{!RecordId}`. * *Why:* Filters the list only to show updates related to the current Project record. * **Order By:** `CreatedDate ASC`. {% endstep %} {% step %} #### Map Data *Unlike standard objects, custom objects require explicit mapping to ensure the user's name and picture appear correctly.* * Content: `Message_Body__c` (Rich Text Area field) * Date: `CreatedDate` * Author Name: `CreatedBy.Name` * Author Avatar: `CreatedBy.SmallPhotoUrl` * *Why:* This dynamically pulls the user who posted the update's Salesforce profile picture {% endstep %} {% step %} #### Configure the Publisher *Set up the input to allow for rich formatting, helpful for project status reports.* * Mode: Rich * Placeholder: "Share a project update..." * Button Label: "Post Update" * Blocked Words: (Optional) Add sensitive internal project codenames if necessary. {% endstep %} {% step %} #### Add the "Save" Logic (Interaction) *Configure the component to create a new `Project_Update__c` record when the button is clicked.* * **Interaction Trigger**: Publish a new message * **Action**: Create Record * Select: Create `Enter Record Data Manually`. * **Target Object**: `Project_Update__c` * **Field Mappings**: 1. **Project\_\_c**: Map to `{$Component.RecordId}` * *Context:* Links the update to the specific Project. 2. **Message\_Body\_\_c**: Map to `Message: Content` * *Context:* Saves the typed content. 3. **Created Date**: `Message: Date` {% endstep %} {% step %} #### Real-Time Updates (Optional) To make messages appear instantly for all team members: 1. **Channel Name:** `Chat_Notification__e` (Assuming you created a Platform Event). 2. **Key Field Name:** `RecordId__c`. {% endstep %} {% endstepper %} *** ## Troubleshooting **The `@` dropdown doesn't appear when typing** * **Cause**: The publisher **Mode** is set to **Plain**, or **Allow Mentions** is not checked. * **Fix**: In the Publisher section, set Mode to **Rich** and check **Allow Mentions**. **The `@` dropdown appears but shows no results** * **Cause 1**: The participant object mapping (`resourcesSObjectMapping`) is not configured. The mention dropdown queries the same object used for participant data. * **Fix**: Make sure your Data Mappings include a participant/resource mapping with a valid Salesforce object. * **Cause 2**: No records exist for the participant object in this environment (common in fresh sandboxes). * **Fix**: Verify that Contact, User, or your custom participant object has records. **Typing `@` inside a word doesn't trigger the dropdown** * **Cause**: The `@` symbol must be preceded by a space, punctuation, or be at the very start of the message. `hello @john` works — `hello@john` does not. * **Fix**: Type a space before `@`. **The mention search doesn't find the right person** * **Cause**: The search matches from the beginning of the field value only. Searching "smith" matches "Smith, John" but not "John Smith". * **Fix**: For Contact and User objects, the search also checks FirstName and LastName fields. For other objects, it only searches the mapped label field — search by the first characters of that field. **Mentions appear in the message but nothing happens (no notification, no Task)** * **Cause**: No interaction is configured on the **Publish a New Message** trigger, or the interaction does not pass **Last Publication Mentions** to a Flow. * **Fix**: Add an **Execute Flow** action to the Publish trigger and map **Last Publication Mentions** as a flow input variable. See [**Setting Up @Mentions**](#setting-up-mentions). *** ## Key Considerations * **Data Model Planning**: For Query mode, ensure your Salesforce objects include the necessary fields to store message content, timestamps, and author information, and include lookup relationships to parent records. * **Resource Identification**: The Current Resource ID determines the message's position. For customer-facing implementations, consider how you'll distinguish between external participants and internal users. * **Character Limits**: Set appropriate maximum lengths based on your target object's field limits to prevent data truncation. * **Blocked Words**: Review and update your blocked words list regularly to maintain communication standards without being overly restrictive. * **Performance**: For conversations with extensive history, use query filters to limit the number of messages loaded initially, or consider pagination strategies for very active threads. ***