Integrate the Client Widget into Your Custom Application

Instead of using the Agentforce Commerce Client, add the client widget to your custom React application by passing the CopilotWidgetProps configuration object to the widget’s React component.

The React component provides the settings it needs, such as connection details, contextual information, supported capabilities, and presentation options. This approach lets you embed the commerce experience in your own application while tailoring the integration to your client’s architecture and user experience. For guidance, look at the out-of-the-box implementation for your storefront.

Customize these parts of the copilotWidgetProps object:

Client connection properties
Widget appearance and behavior
Widget component configuration

Example of the configuration structure for the widget.

1const copilotWidgetProps = {
2  messagingConfig: {
3    scrt2Url: "https://your-org.my.salesforce-scrt.com",
4    orgId: "00Dxx0000000000",
5    esDeveloperName: "Your_Messaging_Channel",
6    capabilitiesVersion: "63",
7  },
8  autoScroll: true,
9  componentConfig: {
10    type: "dialog",
11    isOpen: true,
12  },
13};

Client Connection Properties

The messagingConfig property controls the widget’s backend SCRT2 messaging connection and behavior. It’s a required property.

The table lists all the settings. Required settings are noted.

Setting	Type	Required	Description
`scrt2Url`	`string`	Yes	SCRT2 messaging endpoint URL
`orgId`	`string`	Yes	The 18-character ID of the Salesforce org that hosts your Agentforce agent. This isn’t your B2C Commerce instance or realm ID.
`esDeveloperName`	`string`	Yes	Embedded Service Deployment messaging channel developer name.
`routingAttributes`	`Record <string, string>`	No	Pre-chat routing attributes passed to the messaging channel.
`capabilitiesVersion`	`string`	No	Capabilities version for the SCRT2 token request. Set to `63` or higher to receive action progress-indicator messages.
`enableDownloadTranscript`	`boolean`	No	Shows a transcript-download control. Requires the org’s messaging channel to allow transcript download. Defaults to `true`.
`enableEscalationToAgent`	`boolean`	No	Shows an escalate-to-agent control. Requires the Agentforce agent to be configured with an escalation path. Otherwise, the button is a no-op. Defaults to `false`.
`showProductCaptions`	`boolean`	No	Shows captions on product cards.
`progressStepsLimit`	`number`	No	Maximum number of actions shown in the chat window as the agent processes a shopper’s prompt. When the list goes past the limit, only the most recent actions are shown.
`onProductResult`	`(detail: ProductResultDetail) => void`	No	The widget calls this setting after the agent returns a result from a product search or a product-details lookup. For example, it highlights the returned products on the page.

When the widget calls onProductResult, it passes a ProductResultDetail object.

Field	Type	Description
`agentSessionId`	`string`	ID of the Agentforce session with the agent results.
`kind`	`“search"	"detail”`
`productIds`	`string[]`	The product IDs the agent returns.

Widget Appearance and Behavior

These configuration properties provide you greater flexibility to customize the widget’s appearance and behavior.

The table lists the widget’s available configuration properties and their expected values.

Setting	Type	Description
`disclaimerText`	`string`	Plain-text disclaimer shown in the widget.
`disclaimerMarkdown`	`string`	Markdown disclaimer, as an alternative to `disclaimerText`.
`headerConfig`	`headerConfig`	Customizes the header of the dialog or modal component with your own header text and logo. See Customize the Agentforce Commerce Client.
`searchConfig`	`searchConfig`	Sets your own placeholder text and button label on the widget’s search bar. See Customize the Agentforce Commerce Client.
`openLinksInNewTab`	`boolean`	Opens links from the widget in a new tab.
`showProductDescription`	`boolean`	Shows product descriptions in product displays.
`autoScroll`	`boolean`	Auto-scrolls to the latest message. Defaults to `true`.
`messageAlignment`	`“start"	"end”`
`conversationHistory`	`{ sinceHours?: number; limit?: number }`	Limits how much of a prior conversation the widget loads. The value `sinceHours` defaults to 24.
`promptsConfig`	`PromptsExtensionConfig`	Configures the prompts extension. See Customize the Agentforce Commerce Client.
`isDevelopment`	`boolean`	Enables development logging.

Widget Component Configuration

The componentConfig object controls how the widget component presents itself, for example as inline chat, a floating dialog, or a modal. It also controls the widget’s open or minimized state.

The table lists the available settings.

Setting	Type	Description
`type`	`“chat"	"dialog"
`isOpen`	`boolean`	Determines whether the widget chat window starts open.
`isMinimized`	`boolean`	Determines whether the widget is minimized when it initially starts.
`enableMinimize`	`boolean`	Allows the shopper to minimize the widget.
`options.dialogPosition`	`DialogPosition`	Places the dialog anchor position, such as `"bottom-right"`.
`options.dialogFullHeight`	`boolean`	Chat window is full height.
`options.dialogWidth`	`string`	Chat window’s width.
`options.isModalFullscreen`	`boolean`	Makes the chat window fullscreen.

Open and Close the Widget Programmatically

After the CDN script injects the widget into your storefront page, you can use window.CimulateMessaging.eventHandlers.components to control it programmatically.

The most common use is a storefront-owned launcher. For example, you can create a custom storefront button, such as Ask AI in search suggestions, and open the widget when a shopper selects the button.

Example

1<div id="messaging-widget"></div>
2
3<!-- Storefront-owned launcher: style and position this button yourself. -->
4<button type="button" onclick="openShopperAgent()">Ask AI</button>
5
6<script>
7  function openShopperAgent() {
8    // Pass true to force open, false to force close, or omit to toggle.
9    window.CimulateMessaging?.eventHandlers.components.toggleWidgetOpen(true);
10  }
11</script>

These control methods are available on eventHandlers.components:

Setting	Description
`toggleWidgetOpen(isOpen?)`	Opens or closes the widget. Pass `true` to force open, `false` to force close, or omit the argument to toggle. Opening also restores the widget if it’s minimized.
`toggleWidgetMinimized(isMinimized?)`	Minimizes or restores the widget. Pass a boolean to force a state, or omit the argument to toggle. Minimizing also closes the widget.
`setWidgetType(type)`	Switches the presentation form. Specify `"chat"`, `"dialog"`, or `"modal"`.
`setWidgetDialogPosition(position)`	Sets the dialog anchor position, such as `"bottom-right"`.
`toggleModalFullscreen(isFullscreen)`	Switches the modal’s fullscreen state on or off.

An override’s api.sendMessage can send a message from within a rendered slot.

Manage Client Chat Sessions Programmatically

You can manage sessions using event handlers.

These control methods are available on eventHandlers.session:

Setting	Description
`resetConversation`	Ends the current conversation and starts a new one
`endConversation`	Ends the current conversation. The client doesn’t automatically create a new one.
`sendMessage`	Submits a user prompt to the agent, similar to a user input on the widget’s search bar. Component overrides can use `api.sendMessage` to send a message.

Client Connection Properties

Widget Appearance and Behavior

Widget Component Configuration

Open and Close the Widget Programmatically

Manage Client Chat Sessions Programmatically

Related resources