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.

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.

The input parameter to setSessionContext is an array of context variables. Each context variable has a name and a typed value. The reserved variable _AgentContext holds page and search information under the StructuredValue type; custom context variables use their Agent Builder API name and can be any of the supported types.

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

In addition to the _AgentContext structured object, you can pass any custom context variable that you’ve defined in Agentforce Builder. ECv2 supports all eight Agentforce Builder variable types. Each type maps to a specific valueType on the wire, with the value stored under a type-specific key.

Agentforce Builder Type	`valueType`	Value Key
String	`TextValue`	`textValue`
Boolean	`BooleanValue`	`booleanValue`
Number	`IntegerValue` or `DoubleValue`	`integerValue` or `doubleValue`
Currency	`TextValue`	`textValue` (`"<CurrencyCode> <Amount>"`)
Date	`DateValue`	`dateValue` (`YYYY-MM-DD`)
Timestamp	`DateTimeValue`	`dateTimeValue` (ISO-8601)
List	`ListValue`	`listValue` (array of typed values)
Object	`StructuredValue`	`value` (nested object)

Each context variable’s name must match its API name in Agentforce Builder, and API write access must be enabled for the variable.

Non-conforming context variable payloads can be silently dropped by the server. See Handle Rejected Context Variables for how to detect drops and the two rejection modes.

Accepts the boolean literals true and false.

Use IntegerValue for whole numbers and DoubleValue for decimals. The numeric value must be a JSON number, not a string.

Currency values use TextValue with a string in the format "<CurrencyCode> <Amount>", for example "USD 1499.99". Sending a bare number, an amount without a currency code, or an amount with a currency symbol causes the server to drop the variable.

Date-only value in YYYY-MM-DD format.

ISO-8601 date and time. Both YYYY-MM-DDTHH:MM:SS and YYYY-MM-DDTHH:MM:SSZ are accepted.

ListValue wraps an array of typed values under listValue. Each item is itself a value with its own valueType, and all items must share the same valueType — the type must also match what’s configured for the variable in Agentforce Builder.

Object variables use the StructuredValue shape with an arbitrary nested object under value. This is the same shape used by the reserved _AgentContext variable shown in Set Context Variables.

The server validates each context variable payload against its declared valueType. There are two rejection modes.

Rejection Mode	Trigger	Client Behavior
Hard rejection	Schema violation. For example, a `valueType` of `IntegerValue` with a string in `integerValue`, or an unquoted string literal in `textValue`.	The entire request is rejected.
Soft rejection	Type or format mismatch. For example, a Currency variable sent as `DoubleValue`, a `DateValue` in the wrong format, or a `ListValue` with mixed item types.	The individual variable is silently dropped. The request otherwise proceeds. Dropped variable names are listed in a warning message in the next send-message or create-conversation response.

setSessionContext resolves successfully even when a variable is soft-rejected — the promise resolution only indicates that the call was queued on the client. To confirm that a variable was accepted by the server, inspect the response to the next send-message or create-conversation call for a warning naming the dropped variable.

By default, context variables set through setSessionContext are held on the client and included with the next end-user message. To pass context variables when a new conversation is created — before the end user sends their first message — pass an options object as the second argument with sendWithNewConversation set to true.

Field Name	Type	Description
`sendWithNewConversation`	Boolean	Optional. Defaults to `false`. When `true`, the context variables are sent as part of creating a new conversation instead of being deferred to the next end-user message turn.

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.

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.

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

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.

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.