> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/chat.md).
# Chat
The Avonni Chat component displays a threaded message history on Lightning Pages and lets users publish new messages. Use it for internal collaboration, customer support, or any workflow where conversational context adds value to a Salesforce record.
## Overview
The Chat component renders a scrollable conversation feed populated from either a static list of messages you enter manually or a live Salesforce query. An optional publisher bar at the bottom lets users compose and send new messages, with support for rich text formatting, `@` mentions, character limits, and blocked words.
## Configuration
To configure the Chat, select it on the canvas. The **Edit Chat** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.
### Data Source
Before you build your chat, you must tell the component where to get the message data it should display. You have two options:
| Option | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| **Manual** | Enter messages directly in the component configuration. Ideal for prototypes or fixed conversation examples. |
| **Query** | Fetch message records dynamically from Salesforce (for example, Case Comments filtered by the current record). |
### Data Mapping
When using the **Query** data source, configure the **Data Mappings** section to connect fields from your queried records to the chat display.
* **Content** — map to the field that holds the message body (e.g., `CommentBody`).
* **Date** — map to the timestamp field (e.g., `CreatedDate`).
* **Author Name** — map to the sender's display name (e.g., `CreatedBy.Name`).
* **Author Avatar** — map to the sender's profile photo URL (e.g., `CreatedBy.SmallPhotoUrl`). Requires the **Author Name (Resource Name)** mapping to be set.
### General
These settings control the overall behavior of the Chat.
**Current Resource ID** — the ID used as the author of new messages. It also determines whether a message appears on the sent or received side, unless the messages already define a direction. Defaults to `{!$User.Id}` if left empty.
**Read Only** — when enabled, the publisher is hidden and users can only view messages.
**Disabled** — grays out the publisher and prevents all input. Requires: **Read Only** is off.
**Message Date Format** — controls how timestamps appear on messages. The default is **Relative** ("3 days ago", "just now"). Set to **Standard**, **Preset**, or **Custom** for absolute dates.
* **Standard** — uses the browser locale's default format.
* **Relative** (default) — displays time elapsed since the message was sent.
* **Preset** — choose from a list of named Luxon formats (e.g., Date Medium → "Oct 14, 1983"). Requires **Message Date Format** = Preset.
* **Custom** — enter a Luxon format string (e.g., `MMM d, yyyy h:mm a`). Requires **Message Date Format** = Custom.
**Show Date Dividers** — when enabled, inserts a date label between messages sent on different days.
**No Results Title** — the title shown in the empty state illustration when no messages are returned. Default: "No messages yet".
**No Results Message** — the body text shown in the empty state illustration. Default: "Please publish a message to start the chat."
### Header
The Header group lets you add a title, caption, and avatar above the message feed.
**Title** — text displayed at the top of the Chat header.
**Caption** — secondary text displayed below the title.
**Avatar** — an optional image in the header. Set an **Image** URL, a **Fallback Icon Name** (shown if the image fails to load), or **Initials** (e.g., "JD"). Under Advanced Options, adjust the avatar **Size** (X-Small through XX-Large, default Medium) and **Variant** (Circle or Square, default Square).
**Actions** — add interactive buttons to the header. Each action has a **Label**, **Name** (unique identifier), optional **Icon Name**, and optional **Title** (tooltip). Use **Visible Actions Buttons** to control how many buttons are shown before the rest collapse into an overflow menu. Use **Hide Actions** to hide all header buttons, or **Disable Actions** to keep them visible but inactive.
### Publisher
The Publisher group configures the input area where users compose new messages. It is visible only when **Read Only** is off.
**Mode** — switches between a rich text editor (with a formatting toolbar) and a plain text input. Default: **Rich**.
**Allow Mentions** — enables `@` mention support. When active, typing `@` opens a searchable dropdown of participants. Requires **Mode** = Rich.
**Mentionable Participants IDs** — restricts which participants appear in the `@` dropdown. Accepts a text collection of record IDs or a semicolon-separated string. If empty, all participants from the data source are mentionable. Requires **Allow Mentions** to be enabled.
**Placeholder** — ghost text shown in the empty input area.
**Publish Button Label** — label on the send button. Default: "Publish".
**Maximum Length** — the maximum number of characters allowed per message.
**Minimum Length** — the minimum number of characters required before sending is allowed.
**Show Character Count** — displays a live character counter below the input.
**Toolbar Position** — where the rich text toolbar appears relative to the input (Top or Bottom, default Top). Requires **Mode** = Rich.
**Blocked Words** — a list of words that cannot appear in published messages. When a user tries to send a message containing a blocked word, the action is prevented. Requires **Mode** = Rich.
**Categories** — the toolbar action groups available in the rich text editor. Default: Text (bold, italic, underline, strikethrough). Available categories: Font, Text, Body, Remove Formatting, Header, Color, Highlight Color.
### Set Component Visibility
All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).
## Real-Time Updates (Platform Events)
By default, the Chat component only refreshes when a message is posted or the page is reloaded. To create a live experience where new messages appear automatically, enable Platform Events in the **Advanced Options** of the Query Refresh EMP section.
1. Ensure **Data Source** is set to **Query**.
2. Expand **Advanced Options** and find the **Query Refresh EMP** section.
3. Set **Channel Name** to the API name of your Platform Event (e.g., `Chat_Notification__e`).
4. Set **Key Field Name** to the field within that event that stores the Record ID (e.g., `RecordId__c`).
{% hint style="warning" %}
#### Note
Enabling real-time updates 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
## Use Cases
### Case Comment History
**Goal**: Display Case Comment records on a Case Record Page as a live chat feed with a reply box.
{% stepper %}
{% step %}
#### Create the Component
* Open the **Avonni Dynamic Components** App.
* Click **New**.
* **Name:** "Case Chat History".
* **Target Page Object:** Select **Case**.
{% 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 canvas.
{% endstep %}
{% step %}
#### Configure the Data Source
* Select the **Chat** component on the canvas.
* Set **Data Source** to **Query**.
* **Object:** `CaseComment`.
* **Filter:** `ParentId` equals `{!$Component.RecordId}`.
* **Order By:** `CreatedDate ASC`.
{% endstep %}
{% step %}
#### Map the Query Fields
* **Content**: `Body`.
* **Date**: `CreatedDate`.
{% endstep %}
{% step %}
#### Configure the Publisher
* **Mode**: Rich.
* **Publish Button Label**: "Post Comment".
* **Placeholder**: "Type a reply...".
{% endstep %}
{% step %}
#### Add the Save Interaction
* **Trigger**: On Message Publish.
* **Action**: Enter Record Data Manually.
* **Object**: `CaseComment`.
* **Field Mappings**:
* `ParentId` → `{!$Component.RecordId}`.
* `CommentBody` → `Message: Content`.
{% endstep %}
{% step %}
#### Save and Activate
* Click **Save**.
* Use the **Deploy** button to add this component to your Salesforce Case Lightning Page.
{% endstep %}
{% endstepper %}
### Project Discussion Log
**Goal**: Create a chat interface on a custom "Project" object, saving messages to a custom "Project Update" object.
{% stepper %}
{% step %}
#### Create the Component
* Open the **Avonni Dynamic Components** App.
* Click **New**.
* **Name:** "Project Team Chat".
* **Target Page Object:** Select your custom object (e.g., `Project__c`).
{% endstep %}
{% step %}
#### Add Component to Canvas
* From the **Component Library**, search for **Chat**.
* Drag and drop the **Chat** component onto the canvas.
{% endstep %}
{% step %}
#### Connect to the Data Source
* **Data Source:** Query.
* **Object:** `Project_Update__c`.
* **Filter:** `Project__c` equals `{!$Component.RecordId}`.
* **Order By:** `CreatedDate ASC`.
{% endstep %}
{% step %}
#### Map Data Fields
* **Content**: `Message_Body__c`.
* **Date**: `CreatedDate`.
* **Author Name**: `CreatedBy.Name`.
* **Author Avatar**: `CreatedBy.SmallPhotoUrl`.
{% endstep %}
{% step %}
#### Configure the Publisher
* **Mode**: Rich.
* **Placeholder**: "Share a project update...".
* **Publish Button Label**: "Post Update".
* **Blocked Words**: (Optional) Add any terms to restrict.
{% endstep %}
{% step %}
#### Add the Save Interaction
* **Trigger**: On Message Publish.
* **Action**: Enter Record Data Manually.
* **Object**: `Project_Update__c`.
* **Field Mappings**:
* `Project__c` → `{!$Component.RecordId}`.
* `Message_Body__c` → `Message: Content`.
{% endstep %}
{% step %}
#### Real-Time Updates (Optional)
To make messages appear instantly for all team members:
* **Channel Name**: `Chat_Notification__e`.
* **Key Field Name**: `RecordId__c`.
{% endstep %}
{% endstepper %}
## Interactions
[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Chat. Configure them from the **Interactions** tab of the Edit Chat panel.
### Publish
Fires when the user clicks the publish button to send a message. Use the **lastPublicationValue** output to capture the message content and save it as a record, and **lastPublicationMentions** to access the IDs of any participants mentioned with `@`.
### Header Action Click
Fires when the user clicks one of the header action buttons. Use the **targetName** output to identify which action was clicked and branch your flow logic accordingly.
## Output Variables
The Chat exposes these output variables you can reference elsewhere on the page after the user interacts with it.
### Message Publish
Updated each time the user sends a message.
| Output variable | Type | What it returns |
| ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
| **Last Publication Value** | Text (String) | The content of the most recently published message. |
| **Last Publication Mentions** | Text Collection | The IDs of any participants mentioned with `@` in the last published message. Empty if no mentions were made. |
> **Example:** When a user posts a reply, use **Last Publication Value** and **Last Publication Mentions** as field mappings in a Create Record interaction to save the message and its mentions to a Salesforce object.
### Header Actions
Updated when the user clicks one of the header action buttons.
| Output variable | Type | What it returns |
| ------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Clicked Header Action Name** | Text (String) | The name of the header action button the user clicked. Use it to branch your interaction logic based on which action was selected. |
### Others
| Output variable | Type | What it returns |
| ------------------- | ------ | ---------------------------------------------------------- |
| **Number of Items** | Number | The total number of messages currently loaded in the chat. |
## Troubleshooting Common Issues
* **All messages appear on the left side** — Current Resource ID does not match the resource identifier on the messages. The comparison is case-sensitive and must be an exact match. Set Current Resource ID to the value that matches your resource mapping (typically `{!$User.Id}`). If using names instead of IDs, ensure the casing matches exactly.
* **Message dates show as "2 hours ago" instead of an actual date** — The default Message Date Format is Relative. Set Message Date Format to Preset or Custom to display absolute dates.
* **Messages appear but no avatar or profile picture is shown** — The resource mapping does not include an avatar field. In your Data Mappings, map one of the avatar fields (e.g., `CreatedBy.SmallPhotoUrl`) to the Author Avatar attribute.
* **Blocked word error triggered by a word containing the blocked term (e.g., "test" blocks "testing")** — Blocked words use substring matching, so any message containing the blocked word as part of a larger word is also blocked. Be specific with blocked words; use full phrases or uncommon terms, and avoid short words like "test" that appear inside other valid words.
* **@ mention dropdown doesn't find contacts with apostrophes or special characters (e.g., O'Brien)** — The mention search only accepts letters, spaces, and hyphens. This is a known limitation; users can search by the part of the name that contains only letters (e.g., typing `@Brien` instead of `@O'Brien`).
* **Mention dropdown shows only 10 results even though more matching contacts exist** — The mention search is limited to 10 results for performance reasons. Type more characters to narrow results; for example, `@John S` returns fewer, more targeted matches than `@John`.
* **Character limit set but the stored value exceeds the Salesforce field limit** — When Mode is Rich, the character counter counts visible text only; the actual stored value includes HTML tags, which add to the total size. Set Maximum Length 20–30% lower than your Salesforce field's character limit to account for HTML overhead.
* **Chat area is empty — "No messages yet" appears even though records exist** — The Data Source query returns no results; the filter may be too restrictive, or the Preview Context is not set in the Debug Panel. Verify your query filter uses the correct field and variable, then open the Debug Panel and set a Preview Context record that has related message records.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/dynamic-components/components/chat.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.