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:
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).Key Field: the unique identifier of the message, usually the record Id. Available under advanced options.
Participant ID: map to the field identifying who sent the message (e.g.,
CreatedById). Available under advanced options.Participant: when Participant ID points at a record on another object, this group maps that record into the sender shown on the message. It holds a Label for the display name (e.g.,
Name), a Key Field, an Avatar Source for the profile photo URL (e.g.,SmallPhotoUrl), an Avatar Fallback Icon Name, and Avatar Initials. Requires Participant ID to be set. Available under advanced options.Type — the message direction:
inboundoroutbound. If empty, the current user is treated as the only outbound sender. Available under advanced options.Pinned — a boolean indicating whether the message should appear pinned at the top of the conversation. Takes effect only when Can Pin is enabled. Available under advanced options.
Reply To — map to the field that holds the key of the message this one answers. A message whose Reply To matches another loaded message's Key Field is displayed under a card quoting that message, whether or not Allow Reply is on. Available under advanced options.
Content
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.
Can Pin — when enabled, users can pin messages to the top of the conversation.
Max Pinned Messages — the maximum number of messages that can be pinned at once. Defaults to 10. Requires Can Pin to be enabled.
Message Actions — define custom actions that appear in each message's menu. Each action has a Label, a Name (unique identifier), and an optional Icon Name. Selecting one fires the Message Action Click interaction.
Allow Reply — when enabled, each message carries a reply button. Clicking it shows the message being answered above the publisher, and the message published from there is displayed under a card quoting that message, which users can click to jump back to it. The button is hidden while Read Only or Disabled is on.
No Results Message — the body text shown in the empty state illustration. Default: "Please publish a message to start the chat."
No Results Title — the title shown in the empty state illustration when no messages are returned. Default: "No messages yet".
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, optional Title (tooltip), and, under advanced options, Disabled, Hidden, and Alternative Text. 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.
Help Text — a hoverable help icon in the header that reveals guidance text for users.
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. Available under advanced options.
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.
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.
Ensure Data Source is set to Query.
Expand Advanced Options and find the Query Refresh EMP section.
Set Channel Name to the API name of your Platform Event (e.g.,
Chat_Notification__e).Set Key Field Name to the field within that event that stores the Record ID (e.g.,
RecordId__c).
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.
Use Cases
Case Comment History
Goal: Display Case Comment records on a Case Record Page as a live chat feed with a reply box.
Project Discussion Log
Goal: Create a chat interface on a custom "Project" object, saving messages to a custom "Project Update" object.
Interactions
Interactions define what happens when users interact with the Chat. Configure them from the Interactions tab of the Edit Chat panel.
Publish a New Message
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.
Pin a Message
Fires when the user pins a message. Exposes the pinned message as the Item interaction variable (same shape as a chat message item).
Unpin a Message
Fires when the user unpins a message from the message menu or the pinned banner. Exposes the unpinned message as the Item interaction variable.
Message Action Click
Fires when the user selects one of the custom Message Actions from a message's menu. Use the Clicked Message Action - Action Name output to identify which action was chosen, and Clicked Message Action - Message to access the message it was invoked on.
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.
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.
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.
Message Actions
Updated when the user selects a custom action from a message's menu.
Clicked Message Action - Action Name
Text (String)
The name of the message action the user selected.
Clicked Message Action - Message
Record
The message the action was invoked on. Has the same properties as the data source items.
Clicked Message Action - Message sObject
Record (SObject)
The Salesforce record behind that message. Requires the Query data source.
Pinned Messages
Updated when the user pins or unpins a message.
Last Pin Toggled - Message
Record
The message that was most recently pinned or unpinned. Has the same properties as the data source items.
Last Pin Toggled - Message sObject
Record (SObject)
The Salesforce record behind that message. Requires the Query data source.
Others
Number of Items
Number
The total number of messages currently loaded in the chat.
Styling
Configure the Chat's appearance from the Style tab of the Edit Chat panel.
Controls the outer spacing around the component.
Top / Right / Bottom / Left: Adjust the space on each side.
Controls the inner spacing between the component's content and its border.
Top / Right / Bottom / Left: Adjust the inner spacing on each side.
Controls the component's dimensions.
Width / Height: Set fixed dimensions for the chat.
Min Width / Max Width / Min Height / Max Height: Constrain the size within bounds.
Overflow: Control how content that exceeds the bounds is handled.
Overflow X / Overflow Y: Control overflow per axis.
Customizes the border surrounding the component.
Color / Size / Style / Radius: Set the border color, thickness, style, and corner rounding.
Styles the header background and spacing.
Background Color: Set the header background color.
Padding Top / Right / Bottom / Left: Adjust the inner spacing of the header.
Margin Bottom: Set the space below the header.
Styles messages received from other participants.
Background Color: Set the bubble background color.
Text Color: Set the message text color.
Styles messages sent by the current user.
Background Color: Set the bubble background color.
Text Color: Set the message text color.
Styles the highlight flash shown when jumping to a pinned message.
Flash Background Color: Set the color at the peak of the flash.
Rest Background Color: Set the color the message settles back to.
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 participant mapping does not include an avatar field. In your Data Mappings, set Participant ID, then map an avatar field (e.g.,
SmallPhotoUrl) to Avatar Source inside the Participant group.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
@Brieninstead 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 Sreturns 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.
Last updated
Was this helpful?