Salesforce Docs Portal

utilAPI

This object contains utility-related APIs.

hideChatButton

This method hides the chat button.

By default, the chat button is always shown if no business hours are specified. If business hours are specified, the chat button is shown during business hours and hidden outside of business hours. To learn how to configure business hours, see Set Business Hours in Enhanced Chat.

This command can override the default behavior.

note: You can't hide the chat button if the chat window is already showing. Also, this method doesn’t have session continuity. For example, after a refresh, the button returns to its initial state. If business hours are specified, this call overrides the current visibility only until the next business hours interval.

Parameters

None.

Example

embeddedservice_bootstrap.utilAPI.hideChatButton();

showChatButton

This method shows the chat button.

By default, the chat button is always shown if no business hours are specified. If business hours are specified, the chat button is shown during business hours and hidden outside of business hours. To learn how to configure business hours, see Set Business Hours in Enhanced Chat.

This command can override the default behavior.

note: This method doesn’t have session continuity. For example, after a refresh, the button returns to its initial state. Also, if business hours are specified, this call overrides the current visibility only until the next business hours interval.

Parameters

None.

Example

embeddedservice_bootstrap.utilAPI.showChatButton();

launchChat

This API launches the web chat client with the messaging conversation window maximized. See Launch Chat.

Parameters

Parameter Type Description
shouldStartNewConversation Boolean Optional. Available only in Enhanced Web Chat v2 deployments. If set to true and the current conversation is in the ended state, calling launchChat starts a new conversation. If the current conversation is still open, this parameter is ignored. The default value is false.

Event Handlers

Use the event handlers of this method to perform actions after the chat client launches.

Event Handler Description
then Runs actions if the web chat client launches successfully.
catch Runs actions when the web chat client launch fails.
finally Runs actions after the chat client launches successfully or not.

Example

embeddedservice_bootstrap.utilAPI
  .launchChat()
  .then(function (success) {
    // Add actions to run after the chat client launches successfully.
  })
  .catch(function (error) {
    // Add actions to run after the chat client launch fails.
  })
  .finally(function () {
    // Add actions to run whether the chat client launches
    // successfully or not.
  });

Response

This method returns a Promise object.

removeAllComponents

This method removes all Enhanced Web Chat components from a page on your website. Call the clearSession method first to completely clean up both authenticated and unauthenticated conversations.

Parameters

None.

Example

embeddedservice_bootstrap.userVerificationAPI.clearSession(true).then(() => {
  embeddedservice_bootstrap.utilAPI.removeAllComponents()
});

setSessionContext

important: The setSessionContext method is only available through Enhanced Web Chat v2 deployments. For more information, see Enhanced Chat in Salesforce Help.

This method enables you to pass information like the current page or a recent search to the agent, as well as custom context variables defined in Agentforce Builder.

Parameters

Parameter Type Description
contextVariables Context[] An array of context variables. See the Context object schema.
options Options Optional. Controls how the context variables are delivered. See the Options object schema.

Context Object

The top-level object defines a single context variable. Read more about creating context variable fields in agent conversations.

Field Name Type Description
name String The name of the context variable. Use _AgentContext for the reserved page and search variable, or the Agent Builder API name of a custom context variable.
value Value An object containing the value and its data type. See the Value (Parent) object schema for details.

Value (Parent)

This object acts as a wrapper, defining the type and containing the payload of the context variable. The key that holds the payload depends on the valueType.

Field Name Type Description
valueType String The data type of the payload. Supported values: StructuredValue, TextValue, BooleanValue, IntegerValue, DoubleValue, DateValue, DateTimeValue, ListValue. See Custom Context Variable Types for the mapping to Agentforce Builder types.
value Object Payload for StructuredValue. A complex JSON object. See the Value (Child) object schema.
textValue String Payload for TextValue. Also used for Currency values, in the format "<CurrencyCode> <Amount>" (for example, "USD 1499.99").
booleanValue Boolean Payload for BooleanValue.
integerValue Number Payload for IntegerValue. Whole numbers only.
doubleValue Number Payload for DoubleValue. Decimal numbers.
dateValue String Payload for DateValue. YYYY-MM-DD format.
dateTimeValue String Payload for DateTimeValue. ISO-8601 format.
listValue Array of Values Payload for ListValue. Each item is itself a Value (Parent) object; all items must share the same valueType.

Value (Child)

This nested object contains the specific, structured data for the reserved _AgentContext variable. value must be an object, but there are no required fields.

Field Name Type Description
currentPage String Optional. The web page URL of the page the chat user is currently viewing.
search Search[] Optional. An object containing details about a search the user performed. See the Search object schema.

Options Object

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.

Search

This object provides details about a user's search activity. All fields are optional and can be populated if the information is available.

Field Name Type Description
result String The specific search item the user is currently on.
filters Array of Strings A list of product or category filters applied to the search.
facets Array of Strings The categories or facets the user was browsing or searching within.

Example

embeddedservice_bootstrap.utilAPI.setSessionContext([
  {
    "name": "_AgentContext",
    "value": {
      "valueType": "StructuredValue",
      "value": {
        "currentPage": "",
        "search": {
          "result": "",
          "filters": [
            ""
          ],
          "facets": [
            ""
          ]
        }
      }
    }
  }
])