---
schema_version: "1"
id: 962352052ff40934fa448f1bfd4098310ab5aca158a624432ac3bdd5722183db
title: Configure the Agentforce Commerce Client
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/configure-the-commerce-client.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 8b73d13cefe9af74a7212db41ec17990d73dc8ea25286d8cbdcac3bb028b4fde
products:
  - Composable Storefront
  - Salesforce APIs
---
# 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md). Component-override properties (`overrides`, `overridesUrl`, `inlineOverrides`) are covered in [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md).

## 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](#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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md). |
| `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.
    }
  },
}
```

## Observe widget state

The 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.

Each 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.

```html
<script>
  window.addEventListener("cimulate:ui-state-update", (event) => {
    const { property, value } = event.detail;
    if (property === "isOpen") {
      // Sync your storefront UI to the widget's open state.
    }
  });
</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.

```html
<div id="messaging-widget"></div>

<!-- Storefront-owned launcher: style and position this button yourself. -->
<button type="button" onclick="openShopperAgent()">Ask AI</button>

<script>
  function openShopperAgent() {
    // Pass true to force open, false to force close, or omit to toggle.
    window.CimulateMessaging?.eventHandlers.components.toggleWidgetOpen(true);
  }
</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. |

:::note
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](component-override-sdk.md).
:::

## Related resources

- [Install the Agentforce Commerce Client](install-the-commerce-client.md)
- [Style and Theme the Widget](style-and-theme-the-widget.md)
- [Component Override SDK](component-override-sdk.md)