Embedded Service Chat for Web Developer Guide

Embedded Service Chat for Web Developer Guide
Adjust General Parameters
Change the Embedded Chat Window Appearance and Behavior
Customize Embedded Chat
Expand the Pre-Chat Stage
Boost Chat Stage
Add Special APIs
Bootstrap Embedded Chat
Start, End, and Clear Embedded Chat Sessions
Customize the Channel Menu
Embedded Service Customized Components
Code Snippet Versions
PDF

Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Start, End, and Clear Embedded Chat Sessions

Three APIs allow you to start, end, and clear sessions for Embedded Chat. Use the Embedded Service code snippet version 5.0 and later. The APIs are not available for Experience sites with Lightning Locker enabled.

embedded_svc.liveAgentAPI.startChat(attributes);

The legacy chat product is in maintenance-only mode, and we won't continue to build new features. You can continue to use it, but we no longer recommend that you implement new chat channels. Instead, you can modernize your customer communication with Messaging for In-App and Web. Messaging offers many of the chat features that you love plus asynchronous conversations that can be picked back up at any time.

Important

Embedded Chat must be a menu item on a Channel Menu deployment for Chat APIs to work with a Channel Menu. This API isn’t available for Experience sites.

Note

The Start Chat API launches the widget and initiates a chat request. Use the attributes object to pass more information (contact or case details) to the API. For example, directly route to another buttonId or a specific agentId based on logic you determine. Any parameters must be passed in as an object. Your code might look like this:
1embedded_svc.liveAgentAPI.startChat({
2	directToAgentRouting: {
3	buttonId: “573xx0000000000”,
4	// userId: “”,
5	fallback: true
6},
7extraPrechatInfo: [],
8extraPrechatFormDetails: []
9});

To start a chat, the attributes object contains any of these Embedded Service parameters from the table.

Name Type Description
directToAgentRouting object
Direct agent routing supported only in Start Chat.
  • buttonId (string) – The button ID to request a chat (required).
  • userId (string) – The agent ID to directly route from specified button (optional, defaults to snippet buttonId).
  • fallback (boolean) – If set as true, follows the button’s fallbackRouting rules if the button or agent is not available (required, defaults to false).
prepopulatedPrechatFields object See: Set Certain Pre-Chat Form Fields to Automatically Populate

If Pre-Chat is disabled, this setting is not supported for Start Chat.

Note
extraPrechatInfo array See: Pass Nonstandard Pre-Chat Details
extraPrechatFormDetails array See: Pass Nonstandard Pre-Chat Details
fallbackRouting array See: Set Routing Order
directToButtonRouting function See: Route Chats Based on Pre-Chat Responses

Using the API overrides the Embedded Service code snippet settings. If you don’t pass in settings to the API, you override any existing settings on the snippet.

Important

Limitations
  • Start Chat maximizes the widget if it’s minimized. Calling the API when the end user is in an active chat request or session doesn’t initiate another chat request.
  • Start Chat attributes are not supported for Offline Support and don’t pre-populate offline support forms or submit cases.
  • To avoid opening the widget in No Agents Available dialog or Offline Support states, use the OnSettingsCallCompleted event to ensure that agents are available first.

embedded_svc.liveAgentAPI.endChat();

The End Chat API ends the current chat (if active) and close the chat widget. It ends active chat requests or ongoing chat sessions (as ended by the visitor) and clears embedded service data related to the ongoing chat session. No parameters are required.

End Chat is not supported for the Post-Chat state.

Note

embedded_svc.liveAgentAPI.clearSession();

The Clear Sessions API ends any chat connections (if active), close the chat widget, and delete session data pertaining to all client-side chat sessions. No parameters are required.