Context Events in Enhanced Web Chat v2

This method of passing context events is only available in Enhanced Web Chat v2. For more information, see Enhanced Chat in Salesforce Help.

Important

The optional utilAPI method enables you to pass information like the current page or a recent search to the agent. See the reference for setSessionContext.

Context events aren’t processed for the agent welcome message. The agent processes context events with each user prompt. To pass information that the agent can use in the welcome message, use pre-chat variables instead. See Create a Custom Pre-Chat Form Using LWC.

Note

Set Context Variables

The input parameter to setSessionContext must follow the exact schema shown in the example. Valid variables are currentPage and search. Both variables are optional.

1// Basic example with current page context
2embeddedservice_bootstrap.utilAPI.setSessionContext([
3  {
4    name: "_AgentContext",
5    value: {
6      valueType: "StructuredValue",
7      value: {
8        currentPage: "https://example.com/products/laptops",
9      },
10    },
11  },
12]);
13
14// Complete example with search context and event handlers
15embeddedservice_bootstrap.utilAPI
16  .setSessionContext([
17    {
18      name: "_AgentContext",
19      value: {
20        valueType: "StructuredValue",
21        value: {
22          currentPage: "https://example.com/search-results",
23          search: {
24            result: "MacBook Pro 16-inch",
25            filters: ["Brand: Apple", "Price: $2000-$3000", "Memory: 16GB"],
26            facets: ["Laptops", "Computers", "Electronics"],
27          },
28        },
29      },
30    },
31  ])
32  .then(() => {
33    console.log("Successfully set context.");
34  })
35  .catch((error) => {
36    console.log("Error setting context: " + error);
37  });

Call embeddedservice_bootstrap.utilAPI.setSessionContext only after onEmbeddedMessagingReady fires; don’t call it in initEmbeddedMessaging.

Note

Set Context Variables and Send a Message

You can set context variables and send a user utterance in a single call with sendTextMessage. Setting variables and sending a message in a single call makes sure that the context is immediately available for the agent.

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

Create Context Variables in Agentforce Builder

Before you can access context variables in new agents, manually create them in Agentforce Builder. See Create Variables In Agentforce Builder.

For the currentPage and search variables supported by ECv2, create four variables with these settings.

Enable API write access for each variable.

Note

Name	API Name	Data Type	List Item Type
`currentPage`	`currentPage`	String	N/A
`search_result`	`search_result`	String	N/A
`search_filters`	`search_filters`	List	String
`search_facets`	`search_facets`	List	String

Access Context Variables

You can access the context variables in Agent Script using ${!@variables.<apiName>}. For example, use {!@variables.currentPage} to reference the current page in an action input. For more information on agent variables, see Agent Script Reference: Variables.

Event Handlers

You can use event handlers in both setSessionContext() and sendTextMessage() methods to perform actions after the operation completes.

then event handler— If the context is set successfully, you can use this handler to, for example, update the UI or record analytics.
catch event handler— If there’s an error setting the context, you can use this handler to, for example, try again or show an error message.
finally event handler— This handler runs after the attempt to set context completes, whether it succeeds or fails. Use this handler to run any clean-up actions.