Agentforce Conversation Client React

React component for embedding the Agentforce Conversation Client — the Salesforce agent chat UI for employee agents — into a UI Bundle. This is a wrapper around @salesforce/agentforce-conversation-client that handles authentication automatically and provides a declarative <AgentforceConversationClient /> component.

Use this when a user expects to add an employee agent, Agentforce chat, conversation client, or chat widget for employee agents to their React app. This package only supports Salesforce employee agents — service agents and other agent types are not supported.

How it works

The component embeds the Agentforce chat experience using Lightning Out 2.0. Authentication is resolved automatically:

• Dev (localhost): fetches a frontdoorUrl from /__lo/frontdoor
• Prod (hosted in org): uses globalThis.SFDC_ENV?.orgUrl as salesforceOrigin when available

Step 1: Install

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

This automatically installs @salesforce/agentforce-conversation-client (the underlying SDK) as a dependency.

Step 2: Embed in the app layout

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

export default function AppLayout() {
  return (
    <>
      <Outlet />
      <AgentforceConversationClient agentId="0Xx000000000000AAA" />
    </>
  );
}

Step 3: Configure (flat props)

Props

| Prop | Type | Required | Description | | ------------------ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------- | | agentId | string | Yes | Agent id to load (18-char Salesforce id, starts with 0Xx). | | agentLabel | string | No | Optional display name shown in the chat header. | | inline | boolean | No | If true renders inline; otherwise floating. | | headerEnabled | boolean | No | Header visibility toggle (primarily for inline mode). Floating mode displays a header by default. | | showHeaderIcon | boolean | No | Show/hide the icon in the header. | | width | number \| string | No | Inline width (px number or CSS string). | | height | number \| string | No | Inline height (px number or CSS string). | | styleTokens | Record<string, string> | No | Theme tokens for chat UI styling. Passed through to the underlying SDK. | | salesforceOrigin | string | No | Salesforce org origin URL. Resolved automatically if not provided. | | frontdoorUrl | string | No | Frontdoor URL for authentication. Resolved automatically in dev if not provided. | | onReady | AgentforceReadyHandler | No | Callback invoked when Lightning Out is ready. Receives the event detail. | | onError | AgentforceErrorHandler | No | Callback invoked on Lightning Out errors. Receives { type, detail }. |

Rendering Modes

Floating (default)

A persistent chat widget overlay pinned to the bottom-right corner. No extra config needed.

<AgentforceConversationClient agentId="0Xx000000000000AAA" />

Inline

The chat renders within the page layout at a specific size.

<AgentforceConversationClient agentId="0Xx000000000000AAA" inline width={420} height={600} />

Agent Selection

Pass agentId to load a specific agent (e.g. travel agent, HR agent). agentId is required.

<AgentforceConversationClient agentId="0Xx000000000000AAA" />

Theming with styleTokens

Use styleTokens to theme the Agentforce Conversation Client. Only override the tokens you need.

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

Header visibility

Use headerEnabled to explicitly show or hide the chat header. In this wrapper, floating mode shows a header by default; this prop is most useful for inline mode.

<AgentforceConversationClient
  agentId="0Xx000000000000AAA"
  inline
  width={420}
  height={600}
  headerEnabled
/>

Header icon visibility

Use showHeaderIcon to explicitly show or hide the icon in the header.

<AgentforceConversationClient agentId="0Xx000000000000AAA" showHeaderIcon={false} />

Error and ready callbacks

Use onReady and onError to react programmatically to Lightning Out lifecycle events — for example, to show a loading spinner until the agent is ready, or to report errors to an observability service.

<AgentforceConversationClient
  agentId="0Xx000000000000AAA"
  onReady={(detail) => {
    console.log("Agent chat is ready", detail);
  }}
  onError={(error) => {
    // error.type: "lo.application.error" | "lo.iframe.error"
    // error.detail: the raw error payload from Lightning Out
    reportError(error);
  }}
/>

Both callbacks are optional. When omitted, the SDK still logs errors and readiness to the console.

Wrapper defaults and initialization behavior

This React wrapper applies a few defaults around the underlying SDK:

• showAvatar is set to false.
• channel is set to "Vibes".
• The embed is initialized once per browser window (singleton). If multiple instances mount, only the first successful initialization performs the embed.

Available Style Tokens

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

@salesforce/agentforce-conversation-client README or node_modules/@salesforce/agentforce-conversation-client/README.md (lines 94-177)

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

Prerequisites

• The SDK requires one of salesforceOrigin or frontdoorUrl.
• The wrapper auto-resolves auth in common cases:
  • localhost: fetches frontdoorUrl from /__lo/frontdoor
  • org-hosted UI Bundle: reads salesforceOrigin from globalThis.SFDC_ENV?.orgUrl
• If your runtime does not provide either source, pass salesforceOrigin or frontdoorUrl explicitly.
• The org must allow localhost:<PORT> in Trusted Domains for Inline Frames (session settings) for local development.

If used outside a Salesforce web app (React app)

When this package is used in an external React app (not running inside a Salesforce-hosted UI Bundle), you should pass frontdoorUrl explicitly so Lightning Out can start with an authenticated Salesforce session.

<AgentforceConversationClient
  agentId="0Xx000000000000AAA"
  frontdoorUrl="https://your-org.my.salesforce.com/secur/frontdoor.jsp?otp=<OTP>"
/>

Underlying SDK

This component wraps @salesforce/agentforce-conversation-client. For lower-level usage (vanilla JS, non-React frameworks), see the Agentforce Conversation Client SDK.

Rules and Skills

This package includes coding-agent rules and skills for automated workflows:

• Rule (rules/embedded-agent-rule.md): Conventions for which component to use, authentication, rendering modes, and placement. Copy into .cursor/rules/ (Cursor) or .clinerules/ (Cline).
• Skill (skills/managing-agentforce-conversation-client/): Step-by-step workflow for adding, updating, and configuring the agent — install (or detect existing via patches), add component, update existing instances, configure inline/theming/agent. Copy into .cursor/skills/ (Cursor) or .cline/skills/ (Cline).

Development

npm run build   # apply patches -> dist
npm run dev     # run from dist
npm run watch   # watch and re-apply