Agentforce Conversation Client API

Use the Agentforce Conversation Client (ACC) API to programmatically manage the state of the native Agentforce side panel within the Salesforce Lightning desktop interface. The ACC API is implemented as a headless LWC module (lightning/accApi) that acts as a router of app-to-panel messages. It enables communication between custom LWC components and Agentforce panel.

With the ACC API, interact with your agent inside Salesforce application programmatically to:

• Open and close a panel
• Execute utterances

Before implementing the API, ensure your environment meets the following requirements:

• Interface: This feature is supported exclusively in the Salesforce Lightning Experience desktop environment.
• Compatibility: This feature is for the default Lightning Experience panel only; other interfaces like Tableau or SentOS are not supported.
• API Version: The lightning/accApi module requires API version 59.0 or later.
• Feature Access: Your Salesforce org must have Agentforce enabled.

Use this API for programmatic control to open, close, or send a text utterance to the native Agentforce side panel from a custom LWC.

To interact with the panel, import the methods from the lightning/accApi module into your custom Lightning web component JavaScript file.

1import { open, close, execute } from "lightning/accApi";

To make your custom component available on record and home pages, add targets to the component’s meta.xml file:

1<?xml version="1.0" encoding="UTF-8"?>
2<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
3    <apiVersion>65.0</apiVersion>
4    <isExposed>true</isExposed>
5    <targets>
6        <target>lightning__AppPage</target>
7        <target>lightning__HomePage</target>
8        <target>lightning__RecordPage</target>
9    </targets>
10</LightningComponentBundle>

After adding the targets and deploying your component, you can use the Lightning App Builder to include the component on a record or home page. See Create and Configure Lightning Experience Record Pages.

Communicate directly with the panel from your custom LWC components.

All Panel API methods are asynchronous and return a void promise (Promise<void>).

• Signature: export function open(botId?: string): Promise<void>;

  Description: This function opens the Agentforce chat panel and resolves once the panel is successfully opened. It accepts an optional botId to open the panel with a specific agent; if a botId string isn’t provided, the panel opens using the last used agent.

  Example: Open with a Specific Agent

  JavaScript

  1import { open } from 'lightning/accApi';
  2
  3async handleOpenPanel() {
  4    // Define the botId as a string
  5    const botId = '0Xx...';
  6
  7    // Open the panel with a specific agent
  8    await open(botId);
  9}

• Signature: export function close(): Promise<void>;

  Description: This function hides the Agentforce chat panel and resolves once it is successfully closed. This method requires no parameters.

  Example: Close the Panel

  JavaScript

  1import { close } from 'lightning/accApi';
  2
  3async handleClosePanel() {
  4    // Close the panel
  5    await close();
  6}

The execute method programmatically sends a command to the agent as if the user had typed it into the panel. This method executes the utterance for the provided botID.

• Signature: export function execute(utterance: string, botId: string): Promise<void>;

  Description: Provide a natural language string directly to the execute method. This method requires a botId parameter to execute the utterance for the specific agent. If multiple execute requests are made, they are queued and executed strictly in sequence.

  Example: Execute a Natural Language Utterance

  JavaScript

  1import { execute } from 'lightning/accApi';
  2
  3async askForSummary() {
  4    // Define the utterance as a string
  5    const utteranceString = 'Summarize this Account';
  6
  7    // Execute the natural language utterance
  8    await
  9}

This example showcases a custom Lightning Web Component (LWC), CustomAgentforceLauncher, that demonstrates the core programmatic control features of the Agentforce Conversation Client API. This component uses methods imported from the lightning/accApi module to manage the native Agentforce side panel. The component includes three asynchronous methods:

• handleOpenChat(): Calls the open() method to display the Agentforce chat panel.
• handleCloseChat(): Calls the close() method to hide the Agentforce chat panel.
• handleSendMessage(): Calls the execute(utterance, botId) method to programmatically send a natural language utterance, “What is my account balance?”, to the agent.

This functional snippet illustrates how custom host applications can communicate directly with the panel to manage its state (open/close) and invoke actions on the agent (execute utterance).

Example

1import { LightningElement } from "lwc";
2import { open, close, execute } from "lightning/accApi";
3
4export default class CustomAgentforceLauncher extends LightningElement {
5  async handleOpenChat() {
6    await open();
7  }
8
9  async handleCloseChat() {
10    await close();
11  }
12
13  async handleSendMessage() {
14    const utterance = "What is my account balance?";
15    await execute(utterance, botId);
16  }
17}

Review these limitations and best practices when building with the ACC API:

• Queueing Behavior: All requests that are made would be queued and executed strictly in sequence. The platform ensures that the next query is only executed after the previous one has completed.
• Executing Actions: Currently, only natural language utterances are supported. You cannot execute an action directly by passing its name.
• Finding the Bot ID: Retrieve the botId for your agents by checking the URL within the Agent Builder in Salesforce Setup.
• Multiple Panels: Use the botId to explicitly target a specific agent to prevent behavior overlap if multiple agents are active in the same org.
• No Return Data: The execute method does not return the agent’s textual response to your component.
• Asynchronous Methods: open, close, and execute are asynchronous and must be handled using standard JavaScript Promise patterns.

j

Agentforce Conversation Client Developer Guide

Introducing Agentforce Conversation Client

Integrate with External Applications

Agentforce Conversation Client API