@salesforce/agentforce-conversation-client

@salesforce/agentforce-conversation-client

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

// Inline (width/height configurable)
embedAgentforceClient({
  container: "#agentforce-container",
  salesforceOrigin: "https://myorg.my.salesforce.com",
  agentforceClientConfig: {
    renderingConfig: { mode: "inline", width: 420, height: 600 },
  },
});

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
headerBlockFontFamily	Header font family
headerBlockTextColor	Header text color
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

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;
  };
}

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.