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.
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. |
expressCheckoutEnabled | boolean | No | Shows express checkout payment methods so shoppers can check out faster. 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. |
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. |
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. |
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
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.
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. |