implementing-ui-bundle-agentforce-conversation-client

$2c

Step 1: Check if component already exists

Search for existing usage across all app files (not implementation files):

grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules

Important: Look for React files that import and USE the component (for example, shared shells, route components, or feature pages). Do NOT open files named AgentforceConversationClient.tsx or AgentforceConversationClient.jsx - those are the component implementation.

If found: Read the file and check the current agentId value.

Agent ID validation rule (deterministic):

• Valid only if it matches: ^0Xx[a-zA-Z0-9]{15}$

• Meaning: starts with 0Xx and total length is 18 characters

Decision:

• If agentId matches ^0Xx[a-zA-Z0-9]{15}$ and user wants to update other props → Go to Step 4 (update props)

• If agentId is missing, empty, or does NOT match ^0Xx[a-zA-Z0-9]{15}$ → Continue to Step 2 (need real ID)

• If not found → Continue to Step 2 (add new)

Step 2: Get agent ID

If component doesn't exist or has an invalid placeholder value, ask user for their Salesforce agent ID.

Treat these as placeholder/invalid values:

• "0Xx..."

• "Placeholder"

• "YOUR_AGENT_ID"

• "<USER_AGENT_ID_18_CHAR_0Xx...>"

• Any value that does not match ^0Xx[a-zA-Z0-9]{15}$

Skip this step if:

• Component exists with a real agent ID

• User only wants to update styling or dimensions

Step 3: Canonical import strategy

Use this import path by default in app code:

import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";

If the package is not installed, install it:

npm install @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client

Only use a local relative import (for example, ./components/AgentforceConversationClient) when the user explicitly asks to use a patched/local component in that app.

Do not infer import path from file discovery alone. Prefer one consistent package import across the codebase.

Step 4: Add or update component

Determine which sub-step applies:

• Component NOT found in Step 1 → go to 4a (New installation)

• Component found in Step 1 → go to 4b (Update existing)

#### 4a — New installation

• If the user already specified a target file, use that file. Otherwise, ask the user: "Which file should I add the AgentforceConversationClient to?" Do NOT proceed until a target file is confirmed.

• Read the target file to understand its existing imports and TSX structure.

• Add the import at the top of the file, alongside existing imports. Use the canonical package import from Step 3:

import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";

• Insert the <AgentforceConversationClient /> TSX into the component's return block. Place it as a sibling of existing content — do NOT wrap or restructure existing TSX. Use the real agentId obtained in Step 2:

Example:

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

• Do NOT add any other code (wrappers, layout components, new functions) unless the user explicitly requests it.

#### 4b — Update existing

• Read the file identified in Step 1.

• Locate the existing <AgentforceConversationClient ... /> TSX element.

• Apply only the changes the user requested. Rules:

• Add new props that the user asked for.

• Change prop values the user asked to update.

• Preserve every prop and value the user did NOT mention — do not remove, reorder, or reformat them.

• Never delete the component and recreate it.

• If the current agentId is a placeholder (failed validation in Step 1) and a real agent ID was obtained in Step 2, replace the placeholder value:

// Before

<AgentforceConversationClient agentId="Placeholder" />

// After

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

• If the current agentId is already valid and the user did not ask to change it, leave it as-is.

Step 5: Configure props

Available props (use directly on component):

• agentId (string, required) - Salesforce agent ID

• inline (boolean) - true for inline mode, omit for floating

• width (number | string) - e.g., 420 or "100%"

• height (number | string) - e.g., 600 or "80vh"

• headerEnabled (boolean) - Show/hide header

• styleTokens (object) - For all styling (colors, fonts, spacing)

• salesforceOrigin (string) - Auto-resolved

• frontdoorUrl (string) - Auto-resolved

• agentLabel (string) - header title for agent

Examples:

Floating mode (default):

<AgentforceConversationClient agentId="0Xx..." />

Inline mode with dimensions:

<AgentforceConversationClient agentId="0Xx..." inline width="420px" height="600px" />

Adding or updating agent label:

<AgentforceConversationClient agentId="0Xx..." agentLabel="<dummy-agent-label>" />

Styling rules (mandatory):

• ALL visual customization (colors, fonts, spacing, borders, radii, shadows) MUST go through the styleTokens prop. There are no exceptions.

• ONLY use token names listed in the tables below. Do NOT invent custom token names.

• NEVER apply styling via CSS files, style attributes, className, or wrapper elements. These approaches will not work and will be ignored by the component.

• If the user requests a visual change that does not map to a token below, inform them that the change is not supported by the current token set.

Container

Token name

UI area themed

fabBackground

FAB button background color

containerBackground

Chat container background

headerBackground

Header background

containerWidth

Chat container width

chatBorderRadius

Chat border radius

layoutMaxWidth

Layout max width

Agentforce Header

Token name

UI area themed

headerBlockBackground

Header block background

headerBlockBorderBottomWidth

Header border bottom width

headerBlockBorderBottomStyle

Header border bottom style

headerBlockBorderBottomColor

Header border bottom color

headerBlockBorderRadius

Header corner radius

headerBlockPaddingBlock

Header block padding (vertical)

headerBlockPaddingInline

Header inline padding (horizontal)

headerBlockMinHeight

Header minimum height

headerBlockBrandingGap

Header branding area gap

headerBlockFontFamily

Header font family

headerBlockFontWeight

Header title font weight

headerBlockFontSize

Header title font size

headerBlockLineHeight

Header title line height

headerBlockTextColor

Header text color

headerBlockIconDisplay

Header icon display

headerBlockIconMargin

Header icon margin

headerBlockIconColor

Header icon color

headerBlockIconWidth

Header icon width

headerBlockIconHeight

Header icon height

headerBlockLogoMaxHeight

Header logo max height

headerBlockLogoMaxWidth

Header logo max width

headerBlockLogoMinWidth

Header logo min width

headerBlockButtonHeight

Header action button height

headerBlockButtonWidth

Header action button width

headerBlockButtonPadding

Header action button padding

headerBlockButtonBorderRadius

Header action button border radius

headerBlockHoverBackground

Header hover background

headerBlockActiveBackground

Header active background

headerBlockFocusBorder

Header focus border

Agentforce Welcome Block

Token name

UI area themed

welcomeBlockTextContainerWidth

Welcome text container width

welcomeBlockFontFamily

Welcome block font family

welcomeBlockFontSize

Welcome block font size

welcomeBlockFontWeight

Welcome block font weight

welcomeBlockLineHeight

Welcome block line height

welcomeBlockLetterSpacing

Welcome block letter spacing

welcomeBlockTextColor

Welcome block text color

welcomeBlockPaddingVertical

Welcome block vertical padding

welcomeBlockPaddingHorizontal

Welcome block horizontal padding

welcomeBlockTextAnimationDuration

Welcome text animation duration

Agentforce Messages

Token name

UI area themed

messageBlockBorderRadius

Message block border radius

avatarDisplay

Avatar display property (e.g. block, none)

hideMessageActions

Message actions display (e.g. block, none to hide)

hideCopyAction

Copy action button display (e.g. inline-flex, none)

messageBlockPaddingContainer

Message block container padding

messageBlockFontSize

Message block font size

messageBlockBackgroundColor

Message block background (base)

messageBlockInboundBorder

Inbound message border

messageBlockOutboundBorder

Outbound message border

messageBlockBodyWidth

Message block body width

messageBlockPadding

Message block padding

messageBlockContainerMarginTop

Message block container top margin

messageBlockLineHeight

Message block line height

Avatar visibility (behavioral config)

Use renderingConfig.showAvatar to control whether avatars are rendered in message rows.

• showAvatar: true (default) renders avatars.

• showAvatar: false hides avatars by removing them from the DOM.

Inbound message (agent → customer)

Token name

UI area themed

inboundMessgeTextColor

Inbound message text color (base)

messageBlockInboundBorderRadius

Inbound message border radius

messageBlockInboundBackgroundColor

Inbound message background

messageBlockInboundTextColor

Inbound message text color

messageBlockInboundWidth

Inbound message width

messageBlockInboundTextAlign

Inbound message text alignment

messageBlockInboundHoverBackgroundColor

Inbound message hover background

Outbound message (customer → agent)

Token name

UI area themed

messageBlockOutboundBorderRadius

Outbound message border radius

messageBlockOutboundBackgroundColor

Outbound message background

messageBlockOutboundTextColor

Outbound message text color

messageBlockOutboundWidth

Outbound message width

messageBlockOutboundMarginLeft

Outbound message left margin

messageBlockOutboundTextAlign

Outbound message text alignment

Agentforce Input

Token name

UI area themed

messageInputPadding

Message input container padding

messageInputFooterBorderColor

Message input footer border color

messageInputBorderRadius

Message input border radius

messageInputBorderTransitionDuration

Message input border transition duration

messageInputBorderTransitionEasing

Message input border transition easing

messageInputTextColor

Message input text color

messageInputTextBackgroundColor

Message input text background color

messageInputFooterBorderFocusColor

Message input footer focus border color

messageInputFocusShadow

Message input focus shadow

messageInputMaxHeight

Message input max height

messageInputLineHeight

Message input line height

messageInputTextPadding

Message input text padding

messageInputFontWeight

Message input font weight

messageInputFontSize

Message input font size

messageInputOverflowY

Message input overflow Y

messageInputScrollbarWidth

Message input scrollbar width

messageInputScrollbarColor

Message input scrollbar color

messageInputActionsWidth

Message input actions width

messageInputActionsPaddingRight

Message input actions right padding

messageInputFooterPlaceholderText

Message input placeholder text color

messageInputPlaceholderFontWeight

Placeholder font weight

messageInputErrorTextColor

Message input error text color

messageInputActionsGap

Message input actions gap

messageInputActionsPadding

Message input actions padding

messageInputActionButtonSize

Message input action button size

messageInputActionButtonRadius

Message input action button radius

messageInputFooterSendButton

Message input send button color

messageInputSendButtonDisabledColor

Message input send button disabled color

messageInputActionButtonFocusBorder

Message input action button focus border

messageInputActionButtonActiveIconColor

Message input action button active icon color

messageInputActionButtonActiveBackground

Message input action button active background

messageInputSendButtonIconColor

Message input send button icon color

messageInputFooterSendButtonHoverColor

Message input send button hover color

messageInputActionButtonHoverShadow

Message input action button hover shadow

messageInputFilePreviewPadding

Message input file preview padding

messageInputTextareaMaxHeight

Message input textarea max height

messageInputTextareaWithImageMaxHeight

Message input textarea max height (with image)

Agentforce Error Block

Token name

UI area themed

errorBlockBackground

Error block background color

Styling with styleTokens:

<AgentforceConversationClient

  agentId="0Xx..."

  styleTokens={{

    headerBlockBackground: "#0176d3",

    headerBlockTextColor: "#ffffff",

    messageBlockInboundBackgroundColor: "#4CAF50",

  }}

/>

For complex patterns, consult references/examples.md for:

• Sidebar containers and responsive sizing

• Dark theme and advanced theming combinations

• Inline without header, calculated dimensions

• Complete host component examples

Common mistakes to avoid: Consult references/constraints.md for:

• Invalid props (containerStyle, style, className)

• Invalid styling approaches (CSS files, style tags)

• What files NOT to edit (implementation files)

Common Issues

If component doesn't appear or authentication fails, see references/troubleshooting.md for:

• Agent activation and deployment

• Localhost trusted domains

• Cookie restriction settings