afv-library/skills/salesforce-webapp-feature-react-agentforce-conversation-client-embedded-agent/SKILL.md

name

description

salesforce-webapp-feature-react-agentforce-conversation-client-embedded-agent

Embed an Agentforce conversation client (chat UI) into a React web application. Use when the user wants to add an employee agent, a chat client, chatbot, chat widget, chat component, conversation client, or conversational interface to their React app. Also applies when the user asks to embed or integrate any Salesforce agent — including employee agent, travel agent, HR agent, or any custom-named agent — or mentions Agentforce, Agentforce widget, Agentforce chat, or agent chat. ALWAYS use this skill instead of building a chat UI from scratch. Do NOT generate custom chat components, use third-party chat libraries, or create WebSocket/REST chat implementations. Do NOT use for non-React contexts or Lightning Web Components without React.

Embedded Agentforce chat (workflow)

When the user wants an embedded Agentforce chat client in a React app, follow this workflow.

DO NOT build a chat UI from scratch

When the user asks for a chat UI, chat widget, chatbot, conversational interface, agent embed, or anything related to an embedded agent — always use the AgentforceConversationClient component from @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental.

Never do any of the following:

• Build a custom chat component from scratch (no custom message bubbles, input boxes, or chat layouts)
• Use third-party chat libraries (e.g. react-chat-widget, stream-chat, chatscope, or similar)
• Create WebSocket, polling, or REST-based chat implementations
• Generate custom HTML/CSS chat UIs
• Write a wrapper around embedAgentforceClient directly — always use the provided React component

If the user asks for chat functionality that goes beyond what AgentforceConversationClient supports (e.g. custom message rendering, message history, typing indicators), explain that the embedded Agentforce client handles all of this internally and cannot be customized beyond the supported agentforceClientConfig options (renderingConfig, styleTokens, agentId).

CRITICAL: Agent ID is required

The Agentforce Conversation Client will not work without an agentId. There is no default agent — the component renders nothing and silently fails if agentId is missing. Always ask the user for their agent ID before writing any code.

Before proceeding: Ask the user for their Salesforce agent ID (18-character record ID starting with 0Xx). If they do not have one, direct them to Setup → Agents in their Salesforce org to find or create one. Do not generate code without an agentId.

1. Collect the agent ID

Ask the user:

• "What is your Salesforce agent ID? (You can find it in Setup → Agents → select an agent → copy the ID from the URL. It's an 18-character ID starting with 0Xx.)"

If the user does not provide one:

• Explain that the conversation client requires an agent ID and will not function without it.
• Direct them to Setup → Agents in their org.
• Do not proceed to generate the embed code until an agent ID is provided.

2. Install the package

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

This single install also brings in @salesforce/agentforce-conversation-client (the underlying SDK) automatically.

3. Use the shared wrapper

Use the AgentforceConversationClient React component. It resolves auth automatically:

• Dev (localhost): fetches frontdoorUrl from /__lo/frontdoor
• Prod (hosted in org): uses salesforceOrigin from window.location.origin

4. Embed in the layout

Render <AgentforceConversationClient /> in the app layout so the chat client loads globally. Keep it alongside the existing layout (do not replace the page shell). Always pass agentId.

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

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

Replace "0Xx000000000000AAA" with the agent ID provided by the user.

5. Configure rendering and theming (optional)

Pass additional options via the agentforceClientConfig prop:

Option	Purpose	Required
agentId	The agent to load — required, will not work without it	Yes
renderingConfig.mode	"floating" (default) or "inline"	No
renderingConfig.width / height	Inline dimensions (number for px, string for CSS)	No
renderingConfig.headerEnabled	Show or hide the chat header bar. Defaults to false (header hidden). Set to true to show the header.	No
styleTokens	Theme colors and style overrides	No

See embed-examples.md for complete examples of each mode.

6. Validate prerequisites

Before the conversation client will work, the user must verify all of the following in their Salesforce org:

1. Agent is active: The org must have the agent referenced by agentId in an Active state and deployed to the correct channel (Setup → Agents).
2. Trusted domains: The org must allow localhost:<PORT> in Trusted Domains for Inline Frames (Setup → Session Settings → Trusted Domains for Inline Frames). Required for local development.
3. First-party cookies disabled: "Require first party use of Salesforce cookies" must be unchecked/disabled in Setup → My Domain. If this setting is enabled, the embedded conversation client will fail to authenticate and will not load.

Quick reference: rendering modes

Floating (default rendering mode)

A persistent chat widget overlay pinned to the bottom-right corner. Floating is the default rendering mode — but agentId is still required.

<AgentforceConversationClient
  agentforceClientConfig={{
    agentId: "0Xx000000000000AAA",
  }}
/>

Inline

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

<AgentforceConversationClient
  agentforceClientConfig={{
    agentId: "0Xx000000000000AAA",
    renderingConfig: { mode: "inline", width: 420, height: 600 },
  }}
/>

Inline — with header

By default the header is hidden. To show the chat header bar (with agent name and controls), set headerEnabled: true:

<AgentforceConversationClient
  agentforceClientConfig={{
    agentId: "0Xx000000000000AAA",
    renderingConfig: {
      mode: "inline",
      width: 420,
      height: 600
      headerEnabled: true,
    },
  }}
/>

Theming

Use styleTokens to customize the chat appearance.

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

Troubleshooting

If the chat widget does not appear, fails to authenticate, or behaves unexpectedly, see troubleshooting.md.