mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-08 16:25:58 +08:00
168 lines
7.7 KiB
Markdown
168 lines
7.7 KiB
Markdown
---
|
|
name: salesforce-webapp-feature-react-agentforce-conversation-client-embedded-agent
|
|
description: 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
|
|
|
|
```bash
|
|
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`.**
|
|
|
|
```tsx
|
|
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](docs/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.
|
|
|
|
```tsx
|
|
<AgentforceConversationClient
|
|
agentforceClientConfig={{
|
|
agentId: "0Xx000000000000AAA",
|
|
}}
|
|
/>
|
|
```
|
|
|
|
### Inline
|
|
|
|
The chat renders within the page layout at a specific size.
|
|
|
|
```tsx
|
|
<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`:
|
|
|
|
```tsx
|
|
<AgentforceConversationClient
|
|
agentforceClientConfig={{
|
|
agentId: "0Xx000000000000AAA",
|
|
renderingConfig: {
|
|
mode: "inline",
|
|
width: 420,
|
|
height: 600
|
|
headerEnabled: true,
|
|
},
|
|
}}
|
|
/>
|
|
```
|
|
|
|
### Theming
|
|
|
|
Use `styleTokens` to customize the chat appearance.
|
|
|
|
```tsx
|
|
<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](docs/troubleshooting.md).
|