Managing Webapp Agentforce Conversation Client

Managing Agentforce Conversation Client

Instructions

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/webapp-template-feature-react-agentforce-conversation-client-experimental";

If the package is not installed, install it:

npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental

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

For new installations:

Add to the target React component file using the canonical package import:

import { Outlet } from "react-router";
import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";

export default function AgentChatHost() {
  return (
    <>
      <Outlet />
      <AgentforceConversationClient agentId="0Xx..." />
    </>
  );
}

Fallback note: Use a local relative import only when the user explicitly requests patched/local component usage in that app.

For updates:

Read the file where component is used and modify only the props that need to change. Preserve all other props. Never delete and recreate.

Replacing placeholder values:

If the component has a placeholder agentId (e.g., agentId="Placeholder" or agentId="0Xx..."), replace it with the real agent ID:

// Before (template with placeholder)
<AgentforceConversationClient agentId="Placeholder" />

// After (with real agent ID)
<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

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

Examples:

Floating mode (default):

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

Inline mode with dimensions:

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

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

For styling: For ANY color, font, or spacing changes, use styleTokens prop only. See references/style-tokens.md for complete token list and 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

Prerequisites

Before the component will work, the following Salesforce settings must be configured by the user:

Cookie settings:

• Setup → My Domain → Disable "Require first party use of Salesforce cookies"

Trusted domains (required only for local development):

• Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
• Local development: localhost:<PORT> (e.g., localhost:3000)

Constraints and Anti-Patterns

This document lists all invalid approaches and patterns to avoid when working with AgentforceConversationClient.

Never Edit Implementation Files

CRITICAL: Only edit files where the component is USED, never the component implementation itself.

• ✅ DO edit: Any React files that import and use <AgentforceConversationClient /> (for example, shared shells, route components, or feature pages)
• ❌ DO NOT edit: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
• node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/
• packages/template/feature/feature-react-agentforce-conversation-client/src/
• src/components/AgentforceConversationClient.tsx (patched templates)
• Any path containing /components/AgentforceConversationClient.

If you're reading a file named `AgentforceConversationClient.tsx`, you're in the wrong place. Stop and search for the USAGE instead.

Invalid Props

AgentforceConversationClient uses a flat prop API and does NOT accept these props:

• ❌ containerStyle - Use width and height props directly instead
• ❌ style - Use styleTokens for theming
• ❌ className - Not supported
• ❌ Any standard React div props - This wraps an embedded iframe, not a div

Why: The component is a wrapper around an embedded iframe using Lightning Out 2.0. Standard React styling props don't apply.

Invalid Styling Approaches

CRITICAL: For ALL styling, theming, branding, or color changes - ONLY use `styleTokens` prop.

Never use these approaches:

• ❌ Creating CSS files (e.g., agent-styles.css, theme.css)
• ❌ Creating <style> tags or internal stylesheets
• ❌ Using style attribute on the component
• ❌ Using className prop
• ❌ Inline styles
• ❌ CSS modules
• ❌ Styled-components or any CSS-in-JS libraries

Why: The component controls its own internal styling through the styleTokens API. External CSS cannot reach into the embedded iframe.

Invalid Implementation Approaches

Never do these:

• ❌ Create custom chat UIs from scratch
• ❌ Use third-party chat libraries (socket.io, WebSocket libraries, etc.)
• ❌ Call embedAgentforceClient directly from @salesforce/agentforce-conversation-client
• ❌ Build custom WebSocket or REST API chat implementations

Why: The AgentforceConversationClient component is the official wrapper that handles authentication, Lightning Out 2.0 initialization, and all communication with Salesforce agents. Custom implementations will not work.

Invalid Update Patterns

When updating an existing component:

• ❌ Delete and recreate the component
• ❌ Remove all props and start over
• ❌ Copy the entire component to a new file

Why: This loses configuration, introduces errors, and creates unnecessary diffs. Always update props in place.

Examples

❌ Wrong - Using containerStyle

<AgentforceConversationClient agentId="0Xx..." containerStyle={{ width: 420, height: 600 }} />

✅ Correct - Using width/height directly

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

❌ Wrong - Creating CSS file

/* agent-styles.css */
.agentforce-chat {
  background: red;
  color: white;
}

import "./agent-styles.css";

<AgentforceConversationClient className="agentforce-chat" />;

✅ Correct - Using styleTokens

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    headerBlockBackground: "red",
    headerBlockTextColor: "white",
  }}
/>

❌ Wrong - Creating style tag

<>
  <style>{`.agent-chat { background: blue; }`}</style>
  <AgentforceConversationClient agentId="0Xx..." />
</>

✅ Correct - Using styleTokens

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    headerBlockBackground: "blue",
  }}
/>

❌ Wrong - Editing implementation file

Reading or editing: node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx

✅ Correct - Editing usage file

Reading and editing: usage files where the component is imported and used (for example, src/app.tsx, a route component, or a feature page)

Additional Examples

Essential examples for common patterns and combinations. All use flat props API.

---

Layout Patterns

Sidebar Chat

export default function DashboardWithChat() {
  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <main style={{ flex: 1 }}>{/* Main content */}</main>
      <aside style={{ width: 400 }}>
        <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="100%" />
      </aside>
    </div>
  );
}

Full Page Chat

export default function SupportPage() {
  return (
    <div>
      <h1>Customer Support</h1>
      <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="600px" />
    </div>
  );
}

---

Size Variations

Responsive sizing

<AgentforceConversationClient agentId="0Xx..." inline width="100%" height="80vh" />

Calculated dimensions

<AgentforceConversationClient agentId="0Xx..." inline width="500px" height="calc(100vh - 100px)" />

---

Theming Combinations

Brand theme with custom sizing

<AgentforceConversationClient
  agentId="0Xx..."
  inline
  width="500px"
  height="700px"
  styleTokens={{
    headerBlockBackground: "#0176d3",
    headerBlockTextColor: "#ffffff",
    messageBlockInboundBackgroundColor: "#0176d3",
    messageBlockInboundTextColor: "#ffffff",
    messageInputFooterSendButton: "#0176d3",
  }}
/>

Dark theme

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    headerBlockBackground: "#1a1a1a",
    headerBlockTextColor: "#ffffff",
    messageBlockInboundBackgroundColor: "#2d2d2d",
    messageBlockInboundTextColor: "#ffffff",
    messageBlockOutboundBackgroundColor: "#3a3a3a",
    messageBlockOutboundTextColor: "#f0f0f0",
  }}
/>

Inline without header

<AgentforceConversationClient
  agentId="0Xx..."
  inline
  width="100%"
  height="600px"
  headerEnabled={false}
  styleTokens={{
    messageBlockBorderRadius: "12px",
  }}
/>

---

Complete Host Component Example

import { Outlet } from "react-router";
import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";

export default function AgentChatHost() {
  return (
    <>
      <Outlet />
      <AgentforceConversationClient
        agentId="0Xx..."
        styleTokens={{
          headerBlockBackground: "#0176d3",
          headerBlockTextColor: "#ffffff",
        }}
      />
    </>
  );
}

---

For complete style token reference, see references/style-tokens.md or node_modules/@salesforce/agentforce-conversation-client/README.md.

Style Tokens Reference

This document explains how to use styleTokens for theming and styling the AgentforceConversationClient.

Overview

The styleTokens prop is the ONLY way to customize the appearance of the Agentforce conversation client. It accepts an object with style token keys and CSS values.

Source of Truth

For the complete and always up-to-date list of all 60+ style tokens, see:

[@salesforce/agentforce-conversation-client on npm](https://www.npmjs.com/package/@salesforce/agentforce-conversation-client)

The npm package README contains the definitive documentation with all available style tokens.

Token Categories

Style tokens are organized by UI area:

• Header (7 tokens): background, text color, hover, active, focus, border, font family
• Messages (10 tokens): colors, padding, margins, border radius, fonts, body width
• Inbound messages (5 tokens): background, text color, width, alignment, hover
• Outbound messages (5 tokens): background, text color, width, alignment, margin
• Input (33 tokens): colors, borders, fonts, padding, buttons, scrollbar, textarea, actions

Common Use Cases

Change header color

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    headerBlockBackground: "#0176d3",
    headerBlockTextColor: "#ffffff",
  }}
/>

Change message colors

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    messageBlockInboundBackgroundColor: "#4CAF50",
    messageBlockInboundTextColor: "#ffffff",
    messageBlockOutboundBackgroundColor: "#f5f5f5",
    messageBlockOutboundTextColor: "#333333",
  }}
/>

Apply brand colors

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    headerBlockBackground: "#1a73e8",
    headerBlockTextColor: "#ffffff",
    messageBlockInboundBackgroundColor: "#1a73e8",
    messageBlockInboundTextColor: "#ffffff",
    messageInputFooterSendButton: "#1a73e8",
    messageInputFooterSendButtonHoverColor: "#1557b0",
  }}
/>

Adjust spacing and fonts

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    messageInputFontSize: "16px",
    messageBlockBorderRadius: "12px",
    messageBlockPadding: "16px",
    messageInputPadding: "12px",
  }}
/>

How to Find Token Names

1. Check the @salesforce/agentforce-conversation-client npm package for the complete list of all tokens

2. Token names follow a pattern:

• headerBlock* - Header area
• messageBlock* - Message bubbles
• messageBlockInbound* - Messages from customer to agent
• messageBlockOutbound* - Messages from agent to customer
• messageInput* - Input field and send button

Important Notes

• You do NOT need to provide all tokens - only override the ones you want to change
• Token values are CSS strings (e.g., "#FF0000", "16px", "bold")
• Invalid token names are silently ignored
• The component uses default values for any tokens you don't specify

Troubleshooting

Common issues when using the Agentforce Conversation Client.

---

Component throws "requires agentId"

Cause: agentId was not passed.

Solution: Pass agentId directly as a flat prop:

<AgentforceConversationClient agentId="0Xx000000000000AAA" />

---

Chat widget does not appear

Cause: Invalid agentId or inactive agent.

Solution:

1. Confirm the id is correct (18-char Salesforce id, starts with 0Xx). 2. Ensure the agent is Active in Setup → Agentforce Agents. 3. Verify the agent is deployed to the target channel.

---

Authentication error on localhost

Cause: localhost:<PORT> is not trusted for inline frames.

Solution:

1. Go to Setup → Session Settings → Trusted Domains for Inline Frames. 2. Add localhost:<PORT> (example: localhost:3000).

Important:

• This setting should be temporary for local development only.
• Remove `localhost:<PORT>` from trusted domains after development.
• Recommended: Test the Agentforce conversation client in a deployed app instead of relying on localhost trusted domains for extended periods.

---

Blank iframe / auth session issues

Possible cause: First-party Salesforce cookie restriction may block embedded auth flow in some environments.

Solution:

1. Go to Setup → Session Settings. 2. Find Require first party use of Salesforce cookies. 3. Disable it only if needed and approved by your security/admin team. 4. Save and reload.