Configure the Agentforce Commerce Client
Both the React component and the CDN injection function accept the same configuration object, CopilotWidgetProps. This topic describes the properties you’re most likely to set.
Styling and theming properties (theme, headerConfig, suggestionButtonConfig, searchConfig, and globalClassName) are covered in Style and Theme the Widget. Component-override properties (overrides, overridesUrl, inlineOverrides) are covered in Component Override SDK.
The widget connects through messagingConfig, which is required. It configures the Agentforce SCRT2 connection.
| Field | Type | Required | Notes |
|---|---|---|---|
scrt2Url | string | Yes | SCRT2 messaging endpoint URL. |
orgId | string | Yes | The 18-character ID of the Salesforce org that hosts your Agentforce agent, not your B2C Commerce instance or realm ID. |
esDeveloperName | string | Yes | Embedded Service messaging channel developer name. |
routingAttributes | Record<string, string> | No | Pre-chat routing attributes passed to the channel. |
capabilitiesVersion | string | No | Capabilities version for the SCRT2 token request. Set to "63" or higher (release 254) to receive action progress-indicator messages. |
enableDownloadTranscript | boolean | No | Show a transcript-download control. Requires the org’s messaging channel to allow transcript download. Defaults to true. |
enableEscalationToAgent | boolean | No | Show 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 | Show captions on product cards. |
progressStepsLimit | number | No | Maximum number of progress steps shown in the chat window. When the list grows past the limit, only the most recent steps are shown. |
onProductResult | (detail: ProductResultDetail) => void | No | Called whenever a finalized agent message carries a product result, from either a product search or a product-details lookup. See Observe product results. |
| Property | Type | Notes |
|---|---|---|
disclaimerText | string | Plain-text disclaimer shown in the widget. |
disclaimerMarkdown | string | Markdown disclaimer, as an alternative to disclaimerText. |
openLinksInNewTab | boolean | Open links from the widget in a new tab. |
showProductDescription | boolean | Show product descriptions in product displays. |
autoScroll | boolean | Auto-scroll to the latest message. Defaults to true. |
messageAlignment | "start" | "end" | Alignment of the message list. Defaults to "start". |
conversationHistory | { sinceHours?: number; limit?: number } | Bounds how much prior conversation the widget loads. |
promptsConfig | PromptsExtensionConfig | Configures the prompts extension. See Style and Theme the Widget. |
isDevelopment | boolean | Enables development logging. |
The componentConfig object controls how the widget presents itself (as inline chat, a floating dialog, or a modal) and its open state.
| Field | Type | Notes |
|---|---|---|
type | "chat" | "dialog" | "modal" | Presentation form. |
isOpen | boolean | Whether the widget starts open. |
isMinimized | boolean | Whether the widget starts minimized. |
enableMinimize | boolean | Allow the shopper to minimize the widget. |
options.dialogPosition | DialogPosition | Dialog anchor position, such as "bottom-right". |
options.dialogFullHeight | boolean | Make the dialog full height. |
options.dialogWidth | string | Dialog width. |
options.isModalFullscreen | boolean | Make the modal fullscreen. |
Set messagingConfig.onProductResult to react when the agent returns products. The widget calls it whenever a finalized agent message carries a product result, from either a product search or a product-details lookup, so your storefront can sync its own UI (for example, highlight the returned products on the page).
The callback receives a ProductResultDetail:
| Field | Type | Notes |
|---|---|---|
agentSessionId | string | The Agentforce session the result belongs to. |
kind | "search" | "detail" | Whether the result came from a product search or a product-details lookup. |
productIds | string[] | The product IDs the agent returned. |
messagingConfig: { scrt2Url: “https://your-org.my.salesforce-scrt.com”, orgId: “00Dxx0000000000”, esDeveloperName: “Your_Messaging_Channel”, onProductResult: (detail) => { if (detail.kind === “search”) { // Sync your storefront UI to the products the agent surfaced. } }, }
The CDN global window.CimulateMessaging exposes an eventHandlers.components object your storefront can call to control the widget after it’s injected. The most common use is a storefront-owned launcher: Render your own button (for example, an “Ask AI” entry point in your search suggestions) and open the widget when the shopper selects it.
These control methods are available on eventHandlers.components:
| Method | Notes |
|---|---|
toggleWidgetOpen(isOpen?) | Open or close the widget. Pass true to force open, false to force close, or omit to toggle. Opening also restores the widget if it’s minimized. |
toggleWidgetMinimized(isMinimized?) | Minimize or restore the widget. Pass a boolean to force a state, or omit to toggle. Minimizing also closes the widget. |
setWidgetType(type) | Switch the presentation form: "chat", "dialog", or "modal". |
setWidgetDialogPosition(position) | Set the dialog anchor position, such as "bottom-right". |
toggleModalFullscreen(isFullscreen) | Switch the modal’s fullscreen state on or off. |
The top-level SDK doesn’t expose a method to send a search utterance or message on the shopper’s behalf. Your launcher can open the widget, but the shopper starts the conversation from there. Component overrides are the exception: An override’s api.sendMessage can send a message from within a rendered slot. See Component Override SDK.