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.

Connection

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.

Content and behavior

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.

Component presentation

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.

Observe product results

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. } }, }

1## Observe widget state
2
3The widget also reports UI state changes as a browser `CustomEvent` on `window`, so a storefront can react to them from plain JavaScript without importing anything. The widget dispatches the `cimulate:ui-state-update` event whenever a tracked piece of state changes, such as the connection status or the widget's open, minimized, presentation, or entry-type state.
4
5Each event carries a `detail` object of `{ property, value }`, where `property` names what changed (for example, `"connected"`, `"isOpen"`, `"isMinimized"`, `"type"`, or `"entryType"`) and `value` is the new value.
6
7```html
8<script>
9  window.addEventListener("cimulate:ui-state-update", (event) => {
10    const { property, value } = event.detail;
11    if (property === "isOpen") {
12      // Sync your storefront UI to the widget's open state.
13    }
14  });
15</script>

Control the widget from your storefront

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.

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:

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.