Widget UI Customization

Q: What is the difference between colored and minimal header?

Colored uses your primary (or header-bg) color as the header background with white text. Minimal uses a white background with dark text and a subtle border — a cleaner, modern look. When using minimal, the data-header-bg attribute is ignored.

Brand Your Chat Widget All widget customization is done through data-* attributes on the embed script tag. No CSS or JavaScript changes are needed — the widget uses a Shadow DOM that isolates its styles from your website.

How Customization Works

The REDA AI External Widget renders inside a Shadow DOM, which means your website’s CSS cannot reach inside the widget and the widget’s styles cannot affect your page. All customization is done by adding data-* attributes to the embed <script> tag.

CSS Classes Do Not Work

Because the widget uses a Shadow DOM, adding CSS rules targeting widget class names in your website’s stylesheet will have no effect. Use the data-* attributes listed below instead.

Agent Definition Settings

Some appearance settings come from the Agent Definition record in Salesforce, not from the embed code:

Setting	Where to Configure	Description
Welcome Message	Agent Definition → External Welcome Message	The first message visitors see when they open the chat
Mascot Image	Agent Definition → Mascot Image	Custom avatar shown in the bubble, welcome hero, and next to messages
Agent Name	Agent Definition → Display Name	Shown in the header and used in the welcome hero heading
Proactive greeting	Agent Definition → Start On Load	Off by default. When on, the panel sends a greeting the moment it mounts on a record page, so the agent opens with insights about that record instead of waiting to be asked.

Required Attributes

Attribute	Description
`data-api-key`	Your REDA AI External API Key
`data-endpoint`	Your REDA AI chat API endpoint URL

Bubble Style

The bubble is the floating button visitors click to open the chat. You can display it as a circle (default) or a pill-shaped button with a text label.

Attribute	Values	Default	Description
`data-bubble-style`	`circle` \| `pill`	`circle`	Shape of the floating button
`data-bubble-label`	Any text	(none)	Label text shown in the pill (e.g. “Ask Support”). Required for pill style.
`data-bubble-size`	Number (px)	`60`	Diameter of the circle bubble (ignored for pill style)

Pill Bubble Example

data-bubble-style="pill"
data-bubble-label="Ask REDA AI"

Displays a rounded pill button with an icon and the text “Ask REDA AI”. If a mascot image is configured on the Agent Definition, it replaces the default icon in the pill.

Header Style

The header appears at the top of the chat panel. Choose between a colored header (brand color background) or a minimal header (clean white background).

Attribute	Values	Default	Description
`data-header-style`	`colored` \| `minimal`	`colored`	Header background style
`data-header-bg`	Hex color	Same as primary color	Header background color (only applies to `colored` style)

Minimal Header Example

data-header-style="minimal"

Renders a clean, white header with dark text and a subtle bottom border. The data-header-bg attribute is ignored when using minimal style.

Welcome Hero

The welcome hero is a branded section shown in the chat panel. It displays an avatar or icon, a large heading, and optional subtext — creating a welcoming first impression.

Attribute	Values	Default	Description
`data-show-welcome-hero`	`true` \| `false`	`true`	Show or hide the welcome hero section
`data-welcome-heading`	Any text	“How can [Agent Name] help?”	Hero heading. Use `{title}` as a placeholder for the agent name.
`data-welcome-subtext`	Any text	(none)	Optional subtext below the heading

Welcome Hero Example

data-welcome-heading="How can {title} help?"
data-welcome-subtext="Ask me anything about your properties"

The {title} placeholder is replaced with the agent name and rendered in your brand color. If a mascot image is configured, it appears as a circular avatar above the heading.

Colors

Attribute	Default	Description
`data-primary-color`	`#0176D3`	Primary brand color — used for bubble, header (colored style), user messages, and accent elements
`data-header-bg`	Same as primary	Header background (colored style only)
`data-user-msg-bg`	Same as primary	User message bubble background
`data-user-msg-text-color`	`#ffffff`	Text color inside user message bubbles
`data-bg-color`	Theme default	Panel background color
`data-bg-secondary-color`	Theme default	Assistant message bubble and typing indicator background
`data-text-color`	Theme default	Main text color
`data-border-color`	Theme default	Border and divider color

Custom Brand Colors Example

data-primary-color="#1B5E20"
data-user-msg-bg="#2E7D32"
data-bg-color="#FAFAFA"

Sets a green color scheme: green bubble and header, slightly darker green user messages, and a light gray panel background.

Layout & Position

Attribute	Values / Type	Default	Description
`data-display-mode`	`bubble` \| `docked-right` \| `docked-left`	`bubble`	How the panel opens — a floating card, or a full-height panel docked to the right or left edge. See Display Mode below.
`data-position`	`bottom-right` \| `bottom-left`	`bottom-right`	Which corner the bubble appears in. Independent of Display Mode — you can keep the bubble bottom-left and still dock the panel to the right.
`data-panel-width`	Number (px)	`400`	Width of the chat panel. Bubble mode only — ignored when docked.
`data-panel-height`	Number (px)	`550`	Height of the chat panel. Bubble mode only — a docked panel is always full height.
`data-dock-width`	Number (px), or any CSS width (`30vw`)	Adapts to the screen	Width of the docked panel. Docked modes only. Leave it out and the panel sizes itself to the screen (roughly a third of the window, within sensible limits).
`data-border-radius`	Number (px)	`12`	Corner radius for the panel and bubble
`data-z-index`	Number	`999999`	CSS z-index of the widget (increase if other elements overlap)
`data-title`	Text	`AI Assistant`	Widget panel title shown in the header

Display Mode

Display Mode controls how the chat panel opens. The launcher bubble is always there in every mode — visitors click it to open the assistant, and Display Mode decides what they get.

Mode	What the visitor sees	Best for
`bubble` (default)	A floating chat card that opens just above the bubble, leaving most of the page visible.	Marketing and content sites, where the page is the main event and chat is a helper.
`docked-right`	A full-height panel that slides in from the right edge and stays alongside the page.	Longer conversations, comparing options, or reading results while browsing.
`docked-left`	The same full-height panel, docked to the left edge instead.	Sites whose own content or controls sit on the right.

A docked panel gives the assistant far more room — useful when answers include property cards, photos or comparisons that feel cramped in the floating card.

data-display-mode="docked-right"
data-dock-width="420"

The bubble never disappears. Display Mode only changes how the panel opens — the launcher bubble is shown in all three modes, and data-position still decides which corner it sits in. If you leave data-display-mode out entirely, the widget behaves exactly as before, so existing embeds need no changes.

Sizing: panel width vs dock width. data-panel-width and data-panel-height size the floating card and are ignored when docked. data-dock-width sizes the docked panel and is ignored in bubble mode. If a size setting seems to have no effect, check you are setting the one that matches your Display Mode. Leave data-dock-width out and the panel sizes itself to the visitor’s screen.

On phones. All modes open full-screen on phones, so a docked panel needs no special mobile handling. See Mobile Behavior to change that.

Also on the Community portal. The same three modes are available for the Community widget — choose Display Mode (Bubble, Docked Right, Docked Left) on the REDA AI component in Experience Builder. No embed code needed.

Theme

Attribute	Values	Default	Description
`data-theme`	`light` \| `dark`	`light`	Color theme for the widget. Dark mode uses dark backgrounds with light text.

Typography

Attribute	Type	Default	Description
`data-font-family`	CSS font stack	System font stack	Custom font family (e.g. `'Poppins', sans-serif`). The font must be loaded on your page.
`data-font-size`	Number (px)	`14`	Base font size for messages and input

Mobile Behavior

Attribute	Values / Type	Default	Description
`data-mobile-breakpoint`	Number (px)	`640`	Screen width below which mobile behavior activates
`data-mobile-fullscreen`	`true` \| `false`	`true`	When enabled, the chat panel expands to full screen on mobile devices

Behavior

Attribute	Values / Type	Default	Description
`data-open-on-load`	`true` \| `false`	`false`	Automatically open the chat panel when the page loads
`data-enable-voice`	`true` \| `false`	`true`	Show the voice (microphone) button so visitors can dictate messages. Set to `false` to hide it. The button only appears in browsers that support voice input. See Voice Input.
`data-typing-speed`	Number	`25`	Words per second for the typing animation when revealing responses
`data-cache-ttl-minutes`	Number (min 1)	`5`	How often the widget script cache refreshes (in minutes)

Text & Internationalization (i18n)

All user-facing text in the widget can be overridden for branding or translation purposes:

Attribute	Default	Description
`data-input-placeholder`	Type a message...	Input field placeholder text
`data-aria-open`	Open chat	ARIA label for the bubble when chat is closed
`data-aria-close`	Close chat	ARIA label for the bubble when chat is open
`data-aria-send`	Send message	ARIA label for the send button
`data-aria-typing`	Assistant is typing	ARIA label for the typing indicator
`data-error-rate-limited`	Please wait a moment before sending again.	Rate limit error message
`data-error-max-messages`	This conversation has reached its limit. Please start a new one.	Maximum messages reached error
`data-error-session-expired`	Session expired. Reconnecting...	Session expiry message
`data-error-generic`	Something went wrong. Please try again.	Generic error message
`data-error-connect`	Unable to connect. Please refresh and try again.	Connection failure message

Complete Examples

Minimal Embed (All Defaults)

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1">
</script>

Uses all defaults: circle bubble, colored header, welcome hero, light theme, bottom-right position.

Modern Pill Bubble with Minimal Header

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-bubble-style="pill"
  data-bubble-label="Ask REDA AI"
  data-header-style="minimal"
  data-welcome-heading="How can {title} help?"
  data-welcome-subtext="Ask me anything about your properties">
</script>

Docked Side Panel

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-display-mode="docked-right"
  data-dock-width="420"
  data-bubble-style="pill"
  data-bubble-label="Ask REDA AI"
  data-welcome-subtext="Ask me anything about your properties">
</script>

A full-height panel slides in from the right edge when the visitor clicks the pill; the page stays readable beside it. Drop data-dock-width to let the panel size itself to the screen, or swap in docked-left to dock the other side. Note that data-panel-width and data-panel-height do not apply here — a docked panel is always full height, and data-dock-width sets its width.

Custom Brand Colors with Dark Theme

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-theme="dark"
  data-primary-color="#6C63FF"
  data-title="Support Agent"
  data-position="bottom-left">
</script>

Colored Header without Welcome Hero

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-bubble-style="pill"
  data-bubble-label="Chat with us"
  data-show-welcome-hero="false"
  data-primary-color="#D32F2F">
</script>

Internationalized (Spanish)

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-title="Asistente"
  data-bubble-style="pill"
  data-bubble-label="Pregunte"
  data-input-placeholder="Escribe un mensaje..."
  data-welcome-heading="¿Cómo puede {title} ayudarte?"
  data-welcome-subtext="Pregúntame sobre tu cuenta"
  data-aria-open="Abrir chat"
  data-aria-close="Cerrar chat"
  data-aria-send="Enviar mensaje"
  data-error-generic="Algo salió mal. Inténtalo de nuevo.">
</script>

Testing Customizations

Add or modify data-* attributes on the embed script tag
Refresh your page (hard refresh with Ctrl+Shift+R or Cmd+Shift+R to bypass cache)
Verify the bubble, header, and welcome hero appear as expected
Test on desktop, tablet, and mobile screen sizes
Test in multiple browsers (Chrome, Firefox, Safari, Edge)
Send a test message to verify chat functionality still works

Cache Refreshing

The widget loader includes automatic cache-busting that refreshes every 5 minutes by default (configurable via data-cache-ttl-minutes). If you don’t see your changes immediately, wait a few minutes or do a hard refresh.

Frequently Asked Questions

No. The widget uses a Shadow DOM, which means external CSS cannot reach its internal elements. All styling is controlled through data-* attributes on the embed script tag.

Load the font on your website (e.g. via Google Fonts), then set data-font-family="'Your Font', sans-serif" on the embed tag. The widget will use the font if it’s available on the page.

PNG with transparency is recommended. JPEG also works. Upload a square image (at least 200×200px) to the Mascot Image field on the Agent Definition. The image appears in the bubble, welcome hero, and next to messages.

The welcome message is set on the Agent Definition record in Salesforce (External Welcome Message field), not in the embed code. The welcome hero heading and subtext are separate — those are set via data-welcome-heading and data-welcome-subtext.

Yes. Only include the embed script tag on the pages where you want the widget to appear. Alternatively, use conditional logic in your site’s template to include or exclude the script.

Colored uses your primary (or header-bg) color as the header background with white text. Minimal uses a white background with dark text and a subtle border — a cleaner, modern look. When using minimal, the data-header-bg attribute is ignored.

Next Steps

Review the External Widget Setup guide for initial configuration, or explore Community Agent Setup for portal deployment.

← Previous: External Widget Setup

Next: Community Agent →