---
schema_version: "1"
id: 2a851ed33eba271f928f6c2e92046a7a00aab0d50be442cbaa0eae3455c475ff
title: Custom Lightning Type APIs for Enhanced Chat v2
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/messaging-web/guides/custom-lightning-type-apis.md
canonical_url: https://developer.salesforce.com/docs/service/messaging-web/guide/custom-lightning-type-apis.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 6bb8e9b2f9de1ae092122c20252b55687fd6f7a3f9d7c1f864a894bbfebbd9b1
products:
  - Enhanced Web Chat
  - Service Cloud Developer Content
---
# 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.

**note:** These APIs are only compatible with Enhanced Chat v2 deployments. See [Compare Enhanced Chat v1 to Enhanced Chat v2](https://help.salesforce.com/s/articleView?id=service.enhanced_chat_feature_comparison.htm&type=5).

## 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](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.html) and [Get Started With Lightning Web Components for Enhanced Web Chat](https://developer.salesforce.com/docs/service/messaging-web/guide/custom-ui-component.md).

Review [Context Events in Enhanced Web Chat v2](https://developer.salesforce.com/docs/service/messaging-web/guide/context-events.md) 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. 

```javascript
/**
    * Deployment configuration data.
    * @type {Object}
    */
    @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.

```javascript
this.configuration?.util?.sendTextMessage("I need help with this product", [
  {
    name: "_AgentContext",
    value: {
      valueType: "StructuredValue",
      value: {
        currentPage: "https://example.com/products/laptops",
        search: {
          result: "MacBook Pro 16-inch",
          filters: ["Brand: Apple", "Price: $2000-$3000"],
          facets: ["Laptops", "Computers", "Electronics"],
        },
      },
    },
  },
])
.then(() => {
  console.log("Successfully sent message with context.");
})
.catch((error) => {
  console.log("Error sending message with context: " + error);
});
```

## 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.

```javascript
this.configuration?.util?.setSessionContext([
  {
    name: "_AgentContext",
    value: {
      valueType: "StructuredValue",
      value: {
        currentPage: "https://example.com/search-results",
        search: {
          result: "MacBook Pro 16-inch",
          filters: ["Brand: Apple", "Price: $2000-$3000", "Memory: 16GB"],
          facets: ["Laptops", "Computers", "Electronics"],
        },
      },
    },
  },
])
.then(() => {
  console.log("Successfully set context.");
})
.catch((error) => {
  console.log("Error setting context: " + error);
});
```

## 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.

```javascript
handleAddToCart() {
  this.configuration?.util?.dispatchEventToHostPage("onAddToCartClick", {
    productId: "745-324"
  })
  .then(() => {
    console.log("event dispatched successfully");
  })
  .catch((error) => {
    console.error("error dispatching event", error);
  });
}
```

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

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

For information on host-page event listeners, see [Event Listeners](https://developer.salesforce.com/docs/service/messaging-web/guide/event-listeners.md).

## Event Handlers

If there's an error setting the context or sending a message, you can use the `catch()` event handler to try again or show an error message.

## See Also

- [Get Started with Enhanced Chat v2](https://developer.salesforce.com/docs/ai/agentforce/guide/get-started-enhanced-chat.html)
- [Event Listeners](https://developer.salesforce.com/docs/service/messaging-web/guide/event-listeners.md)