@salesforce/agentforce-conversation-client

The Agentforce Conversation Client SDK enables embedding the Agentforce chat experience for employee agents into external applications.

Overview

This library embeds the Agentforce Conversation Client for employee agents using Lightning Out 2.0.

Prerequisites

• One of salesforceOrigin or frontdoorUrl is required.

• Use salesforceOrigin when your app is hosted inside a Salesforce org and already has an authenticated session.

• Use frontdoorUrl when embedding the chat client outside Salesforce (for example, a localhost or external app).

• Use sitePrefix so LO 2.0 can correctly resolve asset URLs and route requests through the right site context. site-prefix is the path segment of the Experience Site URL after the host. For example, if your site URL is https://mydomain.my.site.com/sample, the site prefix is /sample

• Lightning Out 2.0 uses an existing session to initialize; without it, the embed will fail to start.

Installation

npm install @salesforce/agentforce-conversation-client

Usage

Basic Embedding

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

const { loApp, chatClientComponent } = embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
});

With agentId and agentLabel

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

const { loApp, chatClientComponent } = embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    agentId: "AGENT_ID_FROM_ORG",
    agentLabel: "My Agent",
  },
});

With rendering modes

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

// Floating (default)
embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    renderingConfig: { mode: "floating", showHeaderIcon: true },
  },
});

// Inline (width/height configurable)
// The parent container must have an explicit height for inline mode to fill properly.
embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    renderingConfig: { mode: "inline", width: 420, height: 600 },
  },
});

// Inline filling the parent container
embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    renderingConfig: { mode: "inline", width: "100%", height: "100%" },
  },
});

Header visibility (headerEnabled)

In inline mode, the header is hidden by default. Set headerEnabled: true to show it. In floating mode, the header is always visible regardless of this setting.

embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    agentLabel: "My Agent",
    renderingConfig: {
      mode: "inline",
      width: "100%",
      height: "100%",
      headerEnabled: true,
    },
  },
});

Show Agentforce header icon (showHeaderIcon)

By default, the header icon is hidden when showHeaderIcon is not set.

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    renderingConfig: {
      mode: "floating",
      showHeaderIcon: true, // set false (or omit) to hide the header icon
    },
  },
});

Theming with styleTokens

Use agentforceClientConfig.styleTokens to theme the Agentforce Conversation Client. You do not need to provide all tokens—only the ones you want to override. Tokens are grouped by UI area:

Example

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

const { loApp, chatClientComponent } = embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    styleTokens: {
      headerBlockBackground: "#7B2CBF",
      headerBlockTextColor: "#ffffff",
    },
  },
});

Style Token Reference

Share: Style Token Reference

Container

| Token name | UI area themed | | --------------------- | --------------------------- | | fabBackground | FAB button background color | | fabForegroundColor | FAB button text color | | fabFontSize | FAB button text font size | | fabBorderRadius | FAB button border radius | | containerBackground | Chat container background | | headerBackground | Header background | | containerWidth | Chat container width | | chatBorderRadius | Chat border radius | | layoutMaxWidth | Layout max width |

Agentforce Header

| Token name | UI area themed | | ------------------------------- | ---------------------------------- | | headerBlockBackground | Header block background | | headerBlockBorderBottomWidth | Header border bottom width | | headerBlockBorderBottomStyle | Header border bottom style | | headerBlockBorderBottomColor | Header border bottom color | | headerBlockBorderRadius | Header corner radius | | headerBlockPaddingBlock | Header block padding (vertical) | | headerBlockPaddingInline | Header inline padding (horizontal) | | headerBlockMinHeight | Header minimum height | | headerBlockBrandingGap | Header branding area gap | | headerBlockFontFamily | Header font family | | headerBlockFontWeight | Header title font weight | | headerBlockFontSize | Header title font size | | headerBlockLineHeight | Header title line height | | headerBlockTextColor | Header text color | | headerBlockIconDisplay | Header icon display | | headerBlockIconMargin | Header icon margin | | headerBlockIconColor | Header icon color | | headerBlockIconWidth | Header icon width | | headerBlockIconHeight | Header icon height | | headerBlockLogoMaxHeight | Header logo max height | | headerBlockLogoMaxWidth | Header logo max width | | headerBlockLogoMinWidth | Header logo min width | | headerBlockButtonHeight | Header action button height | | headerBlockButtonWidth | Header action button width | | headerBlockButtonPadding | Header action button padding | | headerBlockButtonBorderRadius | Header action button border radius | | headerBlockHoverBackground | Header hover background | | headerBlockActiveBackground | Header active background | | headerBlockFocusBorder | Header focus border |

Agentforce Welcome Block

| Token name | UI area themed | | ----------------------------------- | -------------------------------- | | welcomeBlockTextContainerWidth | Welcome text container width | | welcomeBlockFontFamily | Welcome block font family | | welcomeBlockFontSize | Welcome block font size | | welcomeBlockFontWeight | Welcome block font weight | | welcomeBlockLineHeight | Welcome block line height | | welcomeBlockLetterSpacing | Welcome block letter spacing | | welcomeBlockTextColor | Welcome block text color | | welcomeBlockPaddingVertical | Welcome block vertical padding | | welcomeBlockPaddingHorizontal | Welcome block horizontal padding | | welcomeBlockTextAnimationDuration | Welcome text animation duration |

Agentforce Messages

| Token name | UI area themed | | -------------------------------- | ------------------------------------------------------- | | messageBlockBorderRadius | Message block border radius | | avatarDisplay | Avatar display property (e.g. block, none) | | hideMessageActions | Message actions display (e.g. block, none to hide) | | hideCopyAction | Copy action button display (e.g. inline-flex, none) | | messageBlockPaddingContainer | Message block container padding | | messageBlockFontSize | Message block font size | | messageBlockBackgroundColor | Message block background (base) | | messageBlockInboundBorder | Inbound message border | | messageBlockOutboundBorder | Outbound message border | | messageBlockBodyWidth | Message block body width | | messageBlockPadding | Message block padding | | messageBlockContainerMarginTop | Message block container top margin | | messageBlockLineHeight | Message block line height |

Avatar visibility (behavioral config)

Use renderingConfig.showAvatar to control whether avatars are rendered in message rows.

• showAvatar: true (default) renders avatars.
• showAvatar: false hides avatars by removing them from the DOM.

Inbound message (customer → agent)

| Token name | UI area themed | | ----------------------------------------- | --------------------------------- | | inboundMessageTextColor | Inbound message text color (base) | | messageBlockInboundBorderRadius | Inbound message border radius | | messageBlockInboundBackgroundColor | Inbound message background | | messageBlockInboundTextColor | Inbound message text color | | messageBlockInboundWidth | Inbound message width | | messageBlockInboundTextAlign | Inbound message text alignment | | messageBlockInboundHoverBackgroundColor | Inbound message hover background |

Outbound message (agent → customer)

| Token name | UI area themed | | ------------------------------------- | ------------------------------- | | messageBlockOutboundBorderRadius | Outbound message border radius | | messageBlockOutboundBackgroundColor | Outbound message background | | messageBlockOutboundTextColor | Outbound message text color | | messageBlockOutboundWidth | Outbound message width | | messageBlockOutboundMarginLeft | Outbound message left margin | | messageBlockOutboundTextAlign | Outbound message text alignment |

Agentforce Input

| Token name | UI area themed | | ------------------------------------------ | ---------------------------------------------- | | messageInputPadding | Message input container padding | | messageInputFooterBorderColor | Message input footer border color | | messageInputBorderRadius | Message input border radius | | messageInputBorderTransitionDuration | Message input border transition duration | | messageInputBorderTransitionEasing | Message input border transition easing | | messageInputTextColor | Message input text color | | messageInputTextBackgroundColor | Message input text background color | | messageInputFooterBorderFocusColor | Message input footer focus border color | | messageInputFocusShadow | Message input focus shadow | | messageInputMaxHeight | Message input max height | | messageInputLineHeight | Message input line height | | messageInputTextPadding | Message input text padding | | messageInputFontWeight | Message input font weight | | messageInputFontSize | Message input font size | | messageInputOverflowY | Message input overflow Y | | messageInputScrollbarWidth | Message input scrollbar width | | messageInputScrollbarColor | Message input scrollbar color | | messageInputActionsWidth | Message input actions width | | messageInputActionsPaddingRight | Message input actions right padding | | messageInputFooterPlaceholderTextColor | Message input placeholder text color | | messageInputPlaceholderFontWeight | Placeholder font weight | | messageInputErrorTextColor | Message input error text color | | messageInputActionsGap | Message input actions gap | | messageInputActionsPadding | Message input actions padding | | messageInputActionButtonSize | Message input action button size | | messageInputActionButtonRadius | Message input action button radius | | messageInputFooterSendButton | Message input send button color | | messageInputSendButtonDisabledColor | Message input send button disabled color | | messageInputActionButtonFocusBorder | Message input action button focus border | | messageInputActionButtonActiveIconColor | Message input action button active icon color | | messageInputActionButtonActiveBackground | Message input action button active background | | messageInputSendButtonIconColor | Message input send button icon color | | messageInputFooterSendButtonHoverColor | Message input send button hover color | | messageInputActionButtonHoverShadow | Message input action button hover shadow | | messageInputFilePreviewPadding | Message input file preview padding | | messageInputTextareaMaxHeight | Message input textarea max height | | messageInputTextareaWithImageMaxHeight | Message input textarea max height (with image) |

Agentforce Error Block

| Token name | UI area themed | | ---------------------- | ---------------------------- | | errorBlockBackground | Error block background color | | errorBlockIconColor | Error block icon color |

With Configuration

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

const { loApp, chatClientComponent } = embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    agentId: "AGENT_ID_FROM_ORG",
    agentLabel: "My Agent",
    styleTokens: {
      messageBlockInboundBackgroundColor: "#0176d3",
    },
    renderingConfig: {
      mode: "inline", // or "floating"
      width: "100%",
      height: "100%",
      headerEnabled: true,
      showHeaderIcon: false,
      showAvatar: false,
    },
  },
});

With Lightning Out 2.0 App ID

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

const { loApp } = embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  appId: "18_DIGIT_SALESFORCE_ID",
});

With Experience Cloud sitePrefix

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

const { loApp } = embedAgentforceClient({
  container: "#agentforce-container",
  frontdoorUrl: "https://myorg.my.salesforce.com/secur/frontdoor.jsp?otp=...",
  sitePrefix: "/my-site",
});

Listening for Events

Callback props (recommended)

Use the onReady and onError callback options for a simpler, declarative approach:

import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";

embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  onReady: (detail) => {
    console.log("Lightning Out is ready", detail);
  },
  onError: (error) => {
    // error.type is "lo.application.error" or "lo.iframe.error"
    // error.detail contains the error payload from Lightning Out
    console.error(`[${error.type}]`, error.detail);
  },
});

| Callback | Fires when | Argument shape | | --------- | --------------------------------------------------------------- | ------------------------------------------------------------------------ | | onReady | Lightning Out application has finished loading | detail: unknown — the raw detail from the lo.application.ready event | | onError | An application-level or iframe-level Lightning Out error occurs | { type: "lo.application.error" \| "lo.iframe.error", detail: unknown } |

Both callbacks are optional.

Low-level event listeners

For finer-grained control (e.g. lo.component.ready, lo.application.logout), use the returned loApp element directly:

const { loApp } = embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
});

loApp.addEventListener("lo.application.ready", () => {
  console.log("Lightning Out 2.0 is ready");
});

loApp.addEventListener("lo.component.ready", (event) => {
  console.log("Component ready:", event.detail.componentName);
});

loApp.addEventListener("lo.application.error", (event) => {
  console.error("Error:", event.detail);
});

API

embedAgentforceClient(options)

Embeds the Agentforce Conversation Client by creating a Lightning Out 2.0 app and chat wrapper under the provided container. In floating mode, the chat is displayed as a fixed overlay; in inline mode, it renders within the container layout.

Note: The embed is initially hidden and becomes visible after the chat wrapper dispatches the accready event.

Parameters

| Parameter | Type | Required | Description | | ----------------------------------------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | options.container | string \| HTMLElement | Yes | CSS selector or HTMLElement to embed into | | options.salesforceOrigin | string | No | Salesforce org origin URL (use when hosted in a Salesforce org). At least one of salesforceOrigin or frontdoorUrl is required | | options.appId | string | No | 18-digit Lightning Out 2.0 app ID (app-id); find it in Lightning Out 2.0 App Manager in Setup; not required for apps created before Spring '26 | | options.frontdoorUrl | string | No | Frontdoor URL for authentication (use when embedding outside Salesforce). At least one of salesforceOrigin or frontdoorUrl is required | | options.sitePrefix | string | No | Experience Cloud site prefix used by Lightning Out (for example, "/my-site"). Set as site-prefix on the LO app | | options.agentforceClientConfig | AgentforceClientConfig | No | Configuration for the Agentforce client (see sub-properties below) | | agentforceClientConfig.agentId | string | Yes* | The agent to load — required in practice, will not work without it | | agentforceClientConfig.agentLabel | string | No | Display name shown in the chat header. Falls back to the agent's configured name if omitted | | agentforceClientConfig.styleTokens | Record<string, string> | No | Theme colors and style overrides (see Style Tokens section) | | agentforceClientConfig.renderingConfig.mode | "inline" \| "floating" | No | Rendering mode. Defaults to "floating" | | agentforceClientConfig.renderingConfig.width | string \| number | No | Width of the inline frame. Number values are treated as px, strings as CSS values (e.g. "100%") | | agentforceClientConfig.renderingConfig.height | string \| number | No | Height of the inline frame. Number values are treated as px, strings as CSS values (e.g. "100%") | | agentforceClientConfig.renderingConfig.headerEnabled | boolean | No | Show or hide the chat header bar. Defaults to hidden in inline mode. Set true to show it | | agentforceClientConfig.renderingConfig.showHeaderIcon | boolean | No | Show or hide the icon in the header. Omit or set false to hide | | agentforceClientConfig.renderingConfig.showAvatar | boolean | No | Show or hide avatars in message rows. Defaults to true | | agentforceClientConfig.renderingConfig.agentAvatarUrl | string | No | Custom avatar image URL for agent messages | | agentforceClientConfig.renderingConfig.agentAvatarAltText | string | No | Alt text for the custom agent avatar image | | agentforceClientConfig.renderingConfig.headerIconName | string | No | SLDS icon name for the header (e.g. "utility:agent") | | agentforceClientConfig.renderingConfig.headerIconSize | string | No | Header icon size | | agentforceClientConfig.renderingConfig.headerImageUrl | string | No | Custom header logo image URL | | agentforceClientConfig.renderingConfig.headerImageAlt | string | No | Alt text for the custom header logo image | | agentforceClientConfig.channel | string | No | Channel identifier for analytics/instrumentation | | agentforceClientConfig.messageInputPlaceholderText | string | No | Custom placeholder text for the message input field | | agentforceClientConfig.isHistoryIntroNeeded | boolean | No | Show a conversation history intro block | | agentforceClientConfig.typewriterConfig | TypewriterConfig | No | Customize typewriter animation (see TypewriterConfig type below) | | agentforceClientConfig.floatingButtonLabel | string | No | Label text for the floating action button (floating mode) | | agentforceClientConfig.floatingButtonIcon | string | No | SLDS icon name for the FAB (e.g. "utility:agent") | | agentforceClientConfig.floatingButtonImage | string | No | URL to an external image (PNG/SVG) shown in place of the FAB icon | | agentforceClientConfig.floatingButtonImageAlt | string | No | Alt text for the floating button image | | agentforceClientConfig.iconPosition | "left" \| "right" | No | Icon position in the FAB. Defaults to "left" | | options.onReady | AgentforceReadyHandler | No | Callback invoked when the Lightning Out application is ready. Receives the event detail | | options.onError | AgentforceErrorHandler | No | Callback invoked on Lightning Out errors. Receives { type, detail } with the error source and payload |

Returns

| Property | Type | Description | | --------------------- | ------------------------- | --------------------------------- | | loApp | LightningOutApplication | The Lightning Out 2.0 application | | chatClientComponent | HTMLElement | The chat client component element |

Types

// Accepts any style property key-value pairs
type StyleTokens = Record<string, string>;

interface TypewriterConfig {
  charsPerFrame?: number;
  charsPerFrameMarkdown?: number;
  queueThresholdMedium?: number;
  queueThresholdHigh?: number;
  queueThresholdCritical?: number;
  frameDelayMs?: number;
  idleCursorTimeoutMs?: number;
  rushToEndMs?: number;
}

interface AgentforceClientConfig {
  styleTokens?: StyleTokens;
  agentId?: string;
  agentLabel?: string;
  renderingConfig?: {
    mode?: "inline" | "floating";
    width?: string | number;
    height?: string | number;
    headerEnabled?: boolean;
    showHeaderIcon?: boolean;
    showAvatar?: boolean;
    agentAvatarUrl?: string;
    agentAvatarAltText?: string;
    headerIconName?: string;
    headerIconSize?: string;
    headerImageUrl?: string;
    headerImageAlt?: string;
  };
  channel?: string;
  messageInputPlaceholderText?: string;
  isHistoryIntroNeeded?: boolean;
  typewriterConfig?: TypewriterConfig;
  floatingButtonLabel?: string;
  floatingButtonIcon?: string;
  floatingButtonImage?: string;
  floatingButtonImageAlt?: string;
  iconPosition?: "left" | "right";
}

// Error event passed to the onError callback
interface AgentforceLoErrorEvent {
  type: "lo.application.error" | "lo.iframe.error";
  detail: unknown;
}

type AgentforceErrorHandler = (error: AgentforceLoErrorEvent) => void;
type AgentforceReadyHandler = (detail: unknown) => void;

interface EmbedAgentforceClientOptions {
  container: string | HTMLElement;
  salesforceOrigin?: string;
  appId?: string;
  frontdoorUrl?: string;
  sitePrefix?: string;
  agentforceClientConfig?: AgentforceClientConfig;
  onReady?: AgentforceReadyHandler;
  onError?: AgentforceErrorHandler;
}

interface EmbedAgentforceClientResult {
  loApp: LightningOutApplication;
  chatClientComponent: HTMLElement;
}

Development

# Build the package
npm run build

# Watch mode for development
npm run dev

License

See LICENSE file in the repository root.