Custom Lightning Type APIs for Enhanced Chat v2

Define these JavaScript APIs for your Custom Lightning Type to send a message or pass context events to the agent in Enhanced Chat v2.

These APIs are only compatible with Enhanced Chat v2 deployments. See Compare Enhanced Chat v1 to Enhanced Chat v2.

Note

Prerequisites

Ensure that you’re familiar with building Lightning Web Components (LWC) and deploying them to your org before you begin. See Core Concepts of Custom Lightning Types and Get Started With Lightning Web Components for Enhanced Web Chat.

Review Context Events in Enhanced Web Chat v2 for context events schema and reference.

To use the sendTextMessage and setSessionContext APIs, your LWC must receive the configuration object that the Enhanced Chat v2 runtime injects. Declare a public property named configuration in your LWC JavaScript file so the platform can pass it in.

1/**
2    * Deployment configuration data.
3    * @type {Object}
4    */
5    @api configuration;

Use optional chaining (for example, this.configuration?.util) when calling the APIs so the component behaves safely if configuration isn’t present.

Send a Message on Behalf of the User

Use configuration.util.sendTextMessage to send a text message. You can optionally pass an array of context events as a second argument so that the agent receives context with that message.

1this.configuration?.util?.sendTextMessage("I need help with this product", [
2  {
3    name: "_AgentContext",
4    value: {
5      valueType: "StructuredValue",
6      value: {
7        currentPage: "https://example.com/products/laptops",
8        search: {
9          result: "MacBook Pro 16-inch",
10          filters: ["Brand: Apple", "Price: $2000-$3000"],
11          facets: ["Laptops", "Computers", "Electronics"],
12        },
13      },
14    },
15  },
16])
17.then(() => {
18  console.log("Successfully sent message with context.");
19})
20.catch((error) => {
21  console.log("Error sending message with context: " + error);
22});

Pass Context Events

You can pass context to the agent in two ways: with a message (second parameter of sendTextMessage) or by setting session context without sending a message (setSessionContext).

Use setSessionContext when you want to update the context the agent has for the conversation (for example, when the user navigates or changes filters) without sending a new message.

1this.configuration?.util?.setSessionContext([
2  {
3    name: "_AgentContext",
4    value: {
5      valueType: "StructuredValue",
6      value: {
7        currentPage: "https://example.com/search-results",
8        search: {
9          result: "MacBook Pro 16-inch",
10          filters: ["Brand: Apple", "Price: $2000-$3000", "Memory: 16GB"],
11          facets: ["Laptops", "Computers", "Electronics"],
12        },
13      },
14    },
15  },
16])
17.then(() => {
18  console.log("Successfully set context.");
19})
20.catch((error) => {
21  console.log("Error setting context: " + error);
22});

Dispatch an Event to the Host Page

Use dispatchEventToHostPage to emit a custom browser event from your Custom Lightning Type (CLT) to the host website page. This pattern is useful when the CLT needs the host page to perform an action outside the chat window.

For example, a product details carousel CLT includes an Add to Cart button. When the user clicks the button, the CLT dispatches an onAddToCartClick event with product details, and the host site listens for that event and adds the item to cart.

This CLT JavaScript code dispatches the event to the host page.

1handleAddToCart() {
2  this.configuration?.util?.dispatchEventToHostPage("onAddToCartClick", {
3    productId: "745-324"
4  })
5  .then(() => {
6    console.log("event dispatched successfully");
7  })
8  .catch((error) => {
9    console.error("error dispatching event", error);
10  });
11}

This JavaScript code on the host page listens for the event.

1window.addEventListener("onAddToCartClick", (event) => {
2  console.log("Received the onAddToCartClick event...");
3  console.log("Event detail: ", event.detail); // { productId: "745-324" }
4});

For information on host-page event listeners, see Event Listeners.

Event Handlers