@salesforce/agentforce-conversation-client(Beta)

Beta: This package is currently in beta. APIs and behavior may change in future releases.

Agentforce Conversation Client SDK for embedding the Agentforce chat experience into external applications. By default, Lightning Out 2.0 is embedded within the target container.

Overview

This library embeds the Agentforce Conversation Client using Lightning Out 2.0. The salesforceOrigin option is passed to the Lightning Out application as the org-url attribute. You can also pass appId to set the Lightning Out app-id attribute. The appId is the 18-digit Lightning Out 2.0 app ID (for example, 1Usfi200000006TCAQ). You can find this value in the Lightning Out 2.0 App Manager in Setup.

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).
• Lightning Out 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

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",
  },
});

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)
embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    renderingConfig: { mode: "inline", width: 420, height: 600 },
  },
});

Show Agentforce header icon

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",
    },
  },
});

Agentforce Header

| Token name | UI area themed | | ------------------------------- | ---------------------------------- | | headerBlockBackground | Header background | | headerBlockBorderColor | Header border | | headerBlockBorderRadius | Header corner radius | | headerBlockPadding | Header inner padding | | headerBlockMinHeight | Header minimum height | | headerBlockSideMinWidth | Header side area minimum width | | headerBlockCenterGap | Header center content gap | | headerBlockCenterMargin | Header center content margin | | 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 Messages

| Token name | UI area themed | | -------------------------------- | ---------------------------------- | | messageBlockBodyPaddingBottom | Message block body bottom padding | | messageBlockTextPadding | Message block text padding | | messageBlockPaddingContainer | Message block container padding | | messageBlockContainerMarginTop | Message block container top margin | | messageBlockPadding | Message block padding | | messageBlockBorderRadius | Message block border radius | | messageBlockFontSize | Message block font size | | messageBlockLineHeight | Message block line height | | messageBlockBackgroundColor | Message block background (base) | | messageBlockBodyWidth | Message block body width |

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 | | ----------------------------------------- | -------------------------------- | | messageBlockInboundHoverBackgroundColor | Inbound message hover background | | messageBlockInboundBackgroundColor | Inbound message background | | messageBlockInboundTextColor | Inbound message text color | | messageBlockInboundWidth | Inbound message width | | messageBlockInboundTextAlign | Inbound message text alignment |

Outbound message (agent → customer)

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

With Configuration

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

const { loApp, chatClientComponent } = embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    // styleTokens supports theming the Agentforce Conversation Client
    styleTokens: {
      MessageBlockInboundColor: "#0176d3",
    },
    renderingConfig: {
      mode: "inline", // or "floating"
      width: 420,
      height: 600,
    },
  },
});

With Lightning Out 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",
});

Listening for Events

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

loApp.addEventListener("lo.application.ready", () => {
  console.log("Lightning Out 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 into a specified DOM container. By default, Lightning Out is embedded within the target container.

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) | | 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) | | options.agentforceClientConfig | AgentforceClientConfig | No | Configuration for the Agentforce client |

Returns

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

Types

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

interface AgentforceClientConfig {
  // styleTokens supports theming the Agentforce Conversation Client
  styleTokens?: StyleTokens;
  renderingConfig?: {
    mode?: "inline" | "floating";
    width?: string | number;
    height?: string | number;
    headerEnabled?: boolean;
    showHeaderIcon?: boolean;
    showAvatar?: boolean;
  };
}

interface EmbedAgentforceClientOptions {
  container: string | HTMLElement;
  salesforceOrigin?: string;
  appId?: string;
  frontdoorUrl?: string;
  agentforceClientConfig?: AgentforceClientConfig;
}

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.