Integrate and Customize ACC in React
Learning Objectives
After completing this unit, you’ll be able to:
- Configure how the Employee Agent conversation interface is displayed and themed with supported rendering settings and UI style tokens.
- Explain how to initialize the Agentforce Conversation Client in a React component using authenticated session values.
- Apply the Agentforce Conversation Client to a frontend DOM container.
Add ACC to the React Application
You know how to configure the External Client App, trusted domain, and Salesforce cookie policy. You also can generate the frontdoorUrl and retrieve the agentId required by the external integration.
Now use those values to render Agentforce Conversation Client (ACC) in the React application.
Here’s what the React component does.
- Provides a DOM container for ACC
- Calls embedAgentforceClient() after the container mounts
- Passes the authenticated frontdoorUrl
- Identifies the Employee Agent with agentId
- Selects Floating or Inline Mode
- Optionally applies supported labels, images, and UI style tokens
Install the Package
Open a terminal in the root directory of the React frontend—the directory that contains the application’s .json file.
Install the @salesforce/agentforce-conversation-client package.
npm install @salesforce/agentforce-conversation-client
The package supplies the embedAgentforceClient() function and the configuration options used to create and render the external ACC conversation interface.
Prepare the ACC Initialization Values
Before reviewing the React component, identify the ACC values that the application passes during initialization.
- frontdoorUrl: Supplies the authenticated Salesforce UI session generated by the backend.
- agentId: Identifies the Employee Agent that ACC loads
- agentLabel: Sets the label displayed in the conversation interface
- renderingConfig: Determines whether ACC renders in Floating or Inline Mode
- styleTokens: Optionally controls supported visual properties of the ACC interface
For external applications:
- Pass frontdoorUrl as a top-level option to embedAgentforceClient().
- Pass agentId, agentLabel, renderingConfig, and styleTokens inside agentforceClientConfig.
The package accepts either a CSS selector or an HTMLElement as the container. For an application hosted outside Salesforce, the package uses frontdoorUrl for the authenticated session.
Initialize ACC in a React Component
After your backend generates a frontdoor URL and you retrieve the Employee Agent ID, pass both values to a React component.
import { useEffect, useRef } from 'react';
import { embedAgentforceClient } from
'@salesforce/agentforce-conversation-client';
export default function AgentforceConversation({
frontdoorUrl,
agentId,
}) {
const containerRef = useRef(null);
const initializedRef = useRef(false);
useEffect(() => {
const container = containerRef.current;
if (
!container ||
!frontdoorUrl ||
!agentId ||
initializedRef.current
) {
return;
}
embedAgentforceClient({
container,
frontdoorUrl,
agentforceClientConfig: {
agentId,
agentLabel: 'Employee Agent',
},
});
initializedRef.current = true;
}, [frontdoorUrl, agentId]);
return <div ref={containerRef} />;
}Understand How the React Component Works
The example uses React references and an effect to wait until the application is ready to initialize ACC.
- containerRef references the div in which ACC renders.
- useEffect runs after React mounts the component and makes the referenced DOM container available.
- The guard clause prevents initialization until container, frontdoorUrl, and agentId are available.
- embedAgentforceClient() creates the ACC interface in the referenced container.
- initializedRef prevents the example from calling embedAgentforceClient() more than once during the same mounted component instance.
- The component returns the div that acts as the ACC container.
The initialization guard is sample React application logic. It prevents repeated initialization within this mounted example. It’s not an ACC Web SDK lifecycle API.
Configure Floating Mode
Use Floating Mode when the conversation experience takes place in an overlay rather than a dedicated location. The user typically opens the conversation from a floating action button.
The base React example defines the Floating Mode configuration outside the component.
const floatingRenderingConfig = {
mode: 'floating',
};Pass the object inside agentforceClientConfig.renderingConfig.
agentforceClientConfig: {
agentId,
agentLabel: 'Employee Agent',
renderingConfig:
floatingRenderingConfig,
}When you keep the rendering configuration in a named object, it’s easier to replace Floating Mode with Inline Mode without rewriting the rest of the initialization call.
Configure Inline Mode
Use Inline Mode when the Employee Agent conversation takes place in a dedicated region, such as a support workspace, side panel, or full-page conversation area.
Define an Inline Mode configuration.
const inlineRenderingConfig = {
mode: 'inline',
headerEnabled: true,
width: '100%',
height: '600px',
};Then locate this floating rendering configuration value in the base React component.
renderingConfig: floatingRenderingConfig,
Replace that value with the inline rendering configuration value.
renderingConfig: inlineRenderingConfig,
Your final configuration placement should match this code.
agentforceClientConfig: {
agentId,
agentLabel: 'Employee Agent',
renderingConfig:
inlineRenderingConfig,
}Customize the ACC UI with Style Tokens
The ACC interface renders inside an iframe. As a result, CSS rules from the React host page can style the outer container, but they can’t directly style the interior of the ACC interface.
Use supported styleTokens to control supported visual properties of the Employee Agent conversation interface and make it better match the application’s visual design.
Style-token values are strings. Define only the tokens that the application needs to override.
const styleTokens = {
headerBlockBackground: '#3F2A56',
headerBlockTextColor: '#FFFFFF',
};Add the tokens to the existing initialization configuration.
embedAgentforceClient({
container,
frontdoorUrl,
agentforceClientConfig: {
agentId,
renderingConfig:
inlineRenderingConfig,
styleTokens,
},
});Supported style token names and values are documented in the @salesforce/agentforce-conversation-client npm package. Check the package documentation for the latest token names before implementing.
You’ve now reviewed what ACC provides, configured the Salesforce requirements for an external application, and embedded and customized the Employee Agent conversation interface in React. Because the external Web SDK initializes in a DOM container, the same overall integration pattern can be adapted to another supported frontend technology.