--- schema_version: "1" id: 62daa54b50c5ffa811632bcc64e95e8ef774a1f57eda8578370d893a5417a1b2 title: utilAPI collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/messaging-web/references/utilAPI.md canonical_url: https://developer.salesforce.com/docs/service/messaging-web/references/m4w-reference/utilAPI.html source_site: developer.salesforce.com content_type: documentation content_hash: d715426e7356381c350ca626bb808c02f0379131f940311ec5360d8e7faac111 products: - Enhanced Web Chat - Service Cloud Developer Content --- # 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](https://help.salesforce.com/s/articleView?id=service.miaw_business_hours.htm). 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 ```javascript 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](https://help.salesforce.com/s/articleView?id=service.miaw_business_hours.htm). 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 ```javascript embeddedservice_bootstrap.utilAPI.showChatButton(); ``` ## launchChat This API launches the web chat client with the messaging conversation window maximized. See [Launch Chat](/docs/service/messaging-web/guide/launch-chat.html). ### 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 ```javascript 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`](https://developer.salesforce.com/docs/service/messaging-web/references/m4w-reference/userVerificationAPI.md#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](https://help.salesforce.com/s/articleView?id=ai.agent_enhanced_chat_channel.htm) 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](https://help.salesforce.com/s/articleView?id=service.agent_context_variables.htm). | 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](/docs/service/messaging-web/guides/context-events.html#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 `" "` (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": [ "" ] } } } } ]) ```