afv-library/samples/webapp-template-app-react-sample-b2e-experimental/.a4drules/skills/integrating-agentforce-conversation-client/SKILL.md

name

description

integrating-agentforce-conversation-client

Embed an Agentforce conversation client (chat UI) into a React web application using the AgentforceConversationClient component. Use when the user wants to add or integrate a chat widget, chatbot, conversation client, agent chat, or conversational interface in a React app, or when they mention Agentforce chat, Agentforce widget, employee agent, travel agent, HR agent, or embedding a Salesforce agent. ALWAYS use this skill instead of building a chat UI from scratch. NEVER generate custom chat components, use third-party chat libraries, or implement chat with WebSockets or REST APIs. Do NOT use for Lightning Web Components (LWC), non-React frameworks.

Embedded Agentforce chat (flat-prop API)

Use this workflow whenever the user wants add or update Agentforce chat in React.

1) Get agent id first

Ask for the Salesforce agent id (18-char id starting with 0Xx). Do not proceed without it.

Placeholder convention for all examples in this file:

<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />

2) Install package

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

3) Use component in app layout

Render a single instance in the shared layout (alongside <Outlet />).

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

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

4) Flat props only

This package uses a flat prop API. Use these props directly on the component:

• agentId (required in practice)
• inline (true = inline, omitted/false = floating)
• headerEnabled (defaults to true for floating; actual use case for inline mode)
• width, height (actual work is when inline mode is true)
• styleTokens
• salesforceOrigin, frontdoorUrl

5) Inline mode example

<AgentforceConversationClient
  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
  inline
  width={420}
  height={600}
/>

6) Theming example

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

7) Do not do this

• Do not create custom chat UIs.
• Do not use third-party chat libraries.
• Do not call embedAgentforceClient directly from @salesforce/agentforce-conversation-client.

8) Prerequisites

Ensure org setup is valid:

1. Agent is active and deployed to the correct channel.
2. localhost:<PORT> is trusted for inline frames in local dev.
3. First-party Salesforce cookie restriction is disabled when required for embedding.

Troubleshooting

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