0% found this document useful (0 votes)

5 views62 pages

Chat Dev Guide

The Service Cloud Chat Developer Guide provides detailed instructions on customizing chat deployments using the Deployment APIs, including creating chat windows, buttons, and pre-chat forms. It emphasizes the upcoming retirement of the legacy chat product on February 14, 2026, urging users to migrate to Messaging for In-App and Web. The guide includes various code samples and prerequisites for effective customization.

Uploaded by

gmanrubia

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

5 views62 pages

Chat Dev Guide

Uploaded by

gmanrubia

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

Service Cloud Chat Developer

Guide
Version 64.0, Summer ’25

Last updated: August 8, 2025

names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS

Chapter 1: About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2: Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 3: API Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 4: Customize Deployments with the Deployment APIs . . . . . . . . . . . . . . . . . . 4

Create Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Log Deployment Activity with the Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
enableLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Customize Your Chat Window with the Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
setChatWindowHeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
setChatWindowWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Customize Chat Buttons with the Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
showWhenOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
showWhenOffline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
addButtonEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
startChat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
startChatWithWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Corresponding Calls for Chat Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Find and Create Records Automatically with the Deployment APIs . . . . . . . . . . . . . . . . . . . . 16
addCustomDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
findOrCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
setName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Search for Knowledge Articles with the Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . 21
Find and Create Records Deployment API Code Sample . . . . . . . . . . . . . . . . . . . . . . . 22
Customize Automated Chat Invitations with the Deployment APIs . . . . . . . . . . . . . . . . . . . . 23
setCustomVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
rejectChat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
addButtonEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Automated Chat Invitation Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Deployment API Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 5: Use Pre-Chat to Gather Visitor Information and Set Context for the
Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Find and Create Records Automatically with the Pre-Chat APIs . . . . . . . . . . . . . . . . . . . . . . 33
[Link] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
[Link] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
[Link] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
[Link] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Contents

[Link] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Find and Create Records Pre-Chat API Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Access Chat Details with the Pre-Chat APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
preChatInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 6: Implement a Custom Chat Window Using Visualforce . . . . . . . . . . . . . . . 44

Chat Visualforce Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chat Visualforce Components Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 7: Use Post-Chat to Wrap Up the Chat Interaction with Your Customer . . . . . 50
Post-Chat Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 8: Set Up Direct-to-Agent Chat Routing with the Deployment APIs . . . . . . . . 54

Direct-to-Agent Routing with the Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Direct-to-Agent Routing Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Fallback Routing in Pre-Chat Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Fallback Routing Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
CHAPTER 1 About This Guide

Customize Chat to fit your company’s needs. This guide provides several examples to help you understand and create customized chat
windows, buttons, forms, and pages.

Important: The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then.
During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid
service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the
chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement
in Help.
Chat lets service organizations connect with customers or website visitors in real time through a Web-based, text-only live chat. You
can customize Chat to create a personalized chat experience for your customer service agents and the customers they serve using
custom code. In this guide, we’ll show you how to:
• Customize deployments using the Deployment API.
• Customize the appearance of customer-facing chat windows using Visualforce pages and components.
• Create pre-chat forms to gather information from customers before they begin a chat with an agent.
• Create post-chat pages that appear to customers after a chat is complete.
Additionally, you can customize these and other Chat components through Salesforce settings. For more information, see Chat with
Customers on Your Website in Salesforce Help.

SEE ALSO:
Salesforce Help: Chat with Customers on Your Website
Embedded Service for Web Developer Guide
Embedded Service SDK for Mobile Devices

1
CHAPTER 2 Prerequisites

Note: When using a Salesforce site for Chat custom chat pages, avoid using the path “/liveagent” in the URL. This path sometimes
causes errors with the incoming and outgoing chat notification sounds, so agents will be unable to hear their chat updates.

2
CHAPTER 3 API Versions

Different methods and parameters are available in different versions of Chat’s APIs. Before you begin developing with the Deployment
API or the Pre-Chat API, make sure you’re using the correct API version number in your code.

Deployment API Versions

You can find out what version of the Deployment API your organization uses from the deployment code that’s generated after you
create a deployment.
Summer ’13 and earlier releases support version 28.0 of the Deployment API. The URL for API version 28.0 looks like this:
[Link]
Winter ’14 supports version 29.0 of the Deployment API. The URL for API version 29.0 contains the version number:
[Link]

Note: To use new methods and parameters in your deployments, you must update the deployment code on each of your Web
pages to use the URL for version 29.0 of the Deployment API.

Pre-Chat Information API Versions

Winter ’14 supports version 29.0 of the Pre-Chat API. The URL for API version 29.0 contains the version number:
[Link]
You can find your organization’s hostname by looking in the deployment code that’s generated after you create a deployment.

3
CHAPTER 4 Customize Deployments with the
Deployment APIs

Customize deployments using the Chat Deployment API.

Important: The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then.
During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid
service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the
chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement
in Help.
A deployment is a place on your company’s website that’s enabled for Chat. A deployment consists of a few lines of JavaScript that you
add to a Web page. Your organization can have a single Chat deployment or multiple deployments. For example, if you have a single
service center that supports multiple websites, creating a separate deployment for each site enables you to present multiple chat windows
to your visitors. Each deployment includes a chat window, which visitors use to chat with support agents.
The Deployment API is a JavaScript-based API that lets you customize your deployments to specify back-end functionality.

Create Deployments
Create a deployment to host Chat on your website. Each deployment includes a chat window, which visitors use to chat with support
agents.
Log Deployment Activity with the Deployment APIs
Log the activity that occurs in a particular deployment.
Customize Your Chat Window with the Deployment APIs
Customize the dimensions of your customer-facing chat windows. This doesn’t apply for mobile-based browsers.
Customize Chat Buttons with the Deployment APIs
Customize your chat buttons and set how chats start for your customers.
Find and Create Records Automatically with the Deployment APIs
Use the Deployment API to search for or create Salesforce records—like a case, contact, account, or lead—automatically when an
agent begins a chat with a customer.
Customize Automated Chat Invitations with the Deployment APIs
Customize automated chat invitations that appear to customers on your website.
Deployment API Code Sample
Test and preview how the Deployment API can help you customize your deployments.

Create Deployments
Create a deployment to host Chat on your website. Each deployment includes a chat window, which visitors use to chat with support
agents.

4
Customize Deployments with the Deployment APIs Log Deployment Activity with the Deployment APIs

You can customize your Chat deployments using the Deployment API to meet your company’s needs. After completing these steps, the
deployment code generates for you to place on the pages that you want to enable for chat and tracking. Pages with the deployment
code are automatically tracked as part of the visitor’s chat session, and they’re shown to the agent in the Console when the visitor requests
a chat. This tracking also enables automated invitations to be presented to customers.
To create a deployment:
1. From Setup, enter Deployments in the Quick Find box, then select Deployments.
2. Click New.
3. Enter a name for the deployment. This name, or a version of it, automatically becomes the Developer Name.
4. Enter a title for the chat window.
5. Select Allow Visitors to Save Transcripts to let visitors download a copy of the chat session.
6. If you want to use branding images that you’ve hosted on a Salesforce site, select the site to associate it with the deployment.
7. (Optional) In Chat Window Branding Image, select the graphic to appear in the chat window.
8. (Optional) In Mobile Chat Window Branding Image, select the graphic that visitors using mobile devices see in the
chat window.
9. Click Save. Salesforce generates the deployment code.
10. Copy the deployment code and paste it on each Web page where you want to deploy Chat. For best performance, paste the code
right before the closing body tag.

Log Deployment Activity with the Deployment APIs

Log the activity that occurs in a particular deployment.

enableLogging
Use the enableLogging deployment method to enable logging on a particular deployment. Available in API versions 28.0 and
later.

5
Customize Deployments with the Deployment APIs enableLogging

Usage
Enables logging for a particular deployment, allowing your Web browser’s JavaScript console to store information about the activity
that occurs within a deployment. You can retrieve the information from your browser’s developer console, so check the help for your
browser if you’re not sure how to find it.

Syntax
[Link]();

Parameters
None

Messages for Logged Events

Message Triggered Meaning
System initialized. Waiting for the DOM to When [Link]() is called, usually at Chat endpoint URL, org ID and deployment
be ready. page load ID have been set, now waiting for DOM to
be ready before continuing.

No available event model. Exiting. During [Link](), if there is an error This means no DOM event listener was
found, which would be very rare. We would
not be able to continue at this point, so it
would be a hard stop.

DOM is ready. Setting up environment. Upon DOM ready of the page The page has fully loaded and the DOM is
ready, so we perform our first "ping" to the
server, which is to get the
settings/information about the given
deployment ID.

Setting state for button {Button ID} to online When the state of a button has changed to The button is available for a chat request to
online be made.

Setting state for button {Button ID} to offline When the state of a button has changed to The button is not available for a chat request
offline to be made.

Requesting new session During the first ping to the server No session ID cookie was found, so a new
one must be generated. This means it was
the first time visiting the site with this
deployment code for this browsing session.

Reusing existing session During the first ping to the server A session cookie exists, so it is reused. This
means the visitor has already been to this
site during this browsing session (e.g., going
from one page to another).

Received new session ID As a response to the first ping The server generated a new session ID, and
it is being stored as a session cookie named
"liveagent_sid.”

6
Customize Deployments with the Deployment APIs enableLogging

Message Triggered Meaning

Ping rate set to {Rate}ms As a response to the first ping Indicates how frequently (in milliseconds)
the page will ping the Chat server. The
default is 50000 (50 seconds). This effectively
indicates when button refreshes will occur.

Pinging server to keep presence When a ping to the server is made Indicates the visitor is still connected to and
pinging the Chat server, meaning no errors
or disconnects have occurred.

Disconnecting from Chat When an error occurs An error was thrown, whether in response
from the server or due to network
connectivity issues. Indicates that the visitor
will no longer ping Chat for this page load
(i.e., they will need to refresh).

Received updated Chat server url: {URL}! When an org has moved to a new core The Chat instance specified in the
Consider updating this site's deployment instance deployment code is no longer valid for this
code. org, so the new URL has been provided. For
better performance, we recommend
updating the deployment code if they
receive this.

Server Warning: {Message} A non-fatal exception occurred A warning condition was encountered, but
processing can continue. The message
provides further details.

Server sent an anonymous warning A non-fatal exception occurred A warning condition was encountered, but
processing can continue. No message was
provided.

Server Error: {Message} A fatal exception occurred An error condition was encountered, and
processing cannot be continued. The
message provides further details.

Server responded with an error A fatal exception occurred An error condition was encountered, and
processing cannot be continued. No
message was provided.

Group Start: Invite {Button ID} Rule Rule evaluation has been triggered Evaluation of the filter logic for the given
Evaluation invite button ID has begun. This means the
button is online and available for chat, and
the filter logic will be used to determine if
it should be displayed/presented or not.

Filter Logic: {Filter Logic} Rule evaluation has been triggered An information log containing the string
representation of the filter logic of the invite
rules as specified in the admin setup area.
Useful to understand how the rules will be
evaluated.

Evaluating StandardInviteRule When a standard rule is being evaluated Standard rules are "Number of Page Views"
and "URL Match." They are part of the

7
Customize Deployments with the Deployment APIs enableLogging

Message Triggered Meaning

out-of-the-box rules that are provided in
the admin setup area.

Evaluating TimerInviteRule When a timer-based rule is being evaluated Timer-based rules are "Seconds on Page"
and "Seconds on Site." They are part of the
out-of-the-box rules as well, except these
rules will be re-evaluated again in the future
when the required number of seconds has
passed if the criteria was not met the first
time (e.g., on page load).

Evaluating CustomInviteRule When a custom rule is being evaluated "Custom Variable" rules allow variable
names to be specified which will be
compared against upon evaluating these
rules. The "setCustomVariable" API is used
in conjunction with these to specify the
value to compare with against the value
specified in the admin setup area.

CustomInviteRule evaluation failed due to When a custom rule is being evaluated A "Custom Variable" rule was set up, but the
missing custom variable "setCustomVariable" API was never called
with this variable name specified, therefore
the rule can not be evaluated.

Evaluate: {From Value} == {To Value} When a rule with an "equals" comparator is A rule is being evaluated by comparing that
being evaluated the two values match exactly.

Not Equals - Evaluate: {From Value} != {To When a rule with a "not equal to" A rule is being evaluated by comparing that
Value} comparator is being evaluated the two values do not match.

Starts With - Evaluate: {From Value} indexOf When a rule with a "starts with" comparator A rule is being evaluated by comparing that
{To Value} == 0 is being evaluated. the first value starts with the second value.

Contains - Evaluate: {From Value} indexOf When a rule with a "contains" comparator A rule is being evaluated by comparing that
{To Value} != -1 is being evaluated the first value contains the second value.

Does Not Contain - Evaluate: {From Value} When a rule with a "does not contain" A rule is being evaluated by comparing that
indexOf {To Value} == -1 comparator is being evaluated the first value does not contain the second
value.

Less Than - Evaluate: {From Value} < {To When a rule with a "less than" comparator A rule is being evaluated by comparing that
Value} is being evaluated the first value is less than the second value.

Greater Than - Evaluate: {From Value} > {To When a rule with a "greater than" A rule is being evaluated by comparing that
Value} comparator is being evaluated the first value is greater than the second
value.

Less or Equal - Evaluate: {From Value} <= When a rule with a "less or equal" A rule is being evaluated by comparing that
{To Value} comparator is being evaluated the first value is less than or equal to the
second value.

8
Customize Deployments with the Deployment APIs Customize Your Chat Window with the Deployment APIs

Message Triggered Meaning

Greater or Equal - Evaluate: {From Value} >= When a rule with a "greater or equal" A rule is being evaluated by comparing that
{To Value} comparator is being evaluated the first value is greater than or equal to the
second value.

Evaluating Atom Node: {Rule ID} When a rule is being evaluated Indicates that an actual rule is being
evaluated.

Group Start: Evaluating And Node When two rules are being evaluated with When multiple rules are used, this indicates
an "AND" clause when the criteria of a pair of rules must both
be "true."

Group Start: Evaluating Or Node When two rules are being evaluated with When multiple rules are used, this indicates
an "OR" clause when the criteria of a pair of rules must be
"true" for one of them.

Group Start: Evaluating Not Node When two rules are being evaluated with a This indicates to check for the opposite of
"NOT" clause what the criteria evaluates to.

Setting invite delay to: {Invite Delay} When a timer-based rule has not yet met If the criteria for a timer-based rule is not
the criteria met, a delay is set to attempt to evaluate
the rules again in the future when the
criteria will have been met.

Customize Your Chat Window with the Deployment APIs

Customize the dimensions of your customer-facing chat windows. This doesn’t apply for mobile-based browsers.

Note: This isn’t applicable for mobile browsers, where chats open to the full page.

setChatWindowHeight
Use the setChatWindowHeight method to customize the height of your chat window.
setChatWindowWidth
Use the setChatWindowWidth method to customize the width of your chat window.

setChatWindowHeight
Use the setChatWindowHeight method to customize the height of your chat window.

9
Customize Deployments with the Deployment APIs setChatWindowWidth

Usage
Sets the height in pixels of the chat window that appears to customers. Available in API versions 28.0 and later.

Syntax
void setChatWindowHeight(Number height)

Parameters
Name Type Description Available Versions
height Number The height in pixels of your custom chat Available in API versions 28.0 and later.
window.

setChatWindowWidth
Use the setChatWindowWidth method to customize the width of your chat window.

Usage
Sets the width in pixels of the chat window that appears to customers. Available in API versions 28.0 and later.

Syntax
void setChatWindowWidth(Number width)

Parameters
Name Type Description Available Versions
width Number The width in pixels of your custom chat Available in API versions 28.0 and later.
window.

Customize Chat Buttons with the Deployment APIs

Customize your chat buttons and set how chats start for your customers.

10
Customize Deployments with the Deployment APIs showWhenOnline

Use the following deployment methods to customize your chat buttons and starting chats. You can add any of these methods as
additional scripts within the code that’s automatically generated when you create a deployment.

showWhenOnline
Use the showWhenOnline method to specify what customers see when a particular button is online.
showWhenOffline
Use the showWhenOffline method to specify what customers see when a particular button is offline.
addButtonEventHandler
Use the addButtonEventHandler method to define a chat button’s behavior when certain events occur. Available in API
versions 28.0 and later.
startChat
Use the startChat method to request a chat from a button in a new window.
startChatWithWindow
Use the startChatWithWindow method to request a chat from a button using the name of a window.
Corresponding Calls for Chat Buttons
Make sure your chats start correctly by aligning your calls when using buttons, direct-to-agent, and agent with fallback-to-button.

showWhenOnline
Use the showWhenOnline method to specify what customers see when a particular button is online.

Usage
Displays a particular element when the specified button, agent, or agent-with-fallback-button is online. Available in API versions 28.0
and later.

Syntax
For a button, userId is optional: void showWhenOnline(String buttonId, Object element, (optional)
String userId)
For an agent, use userId instead of buttonId: void showWhenOnline(String userId, Object element)
For an agent with fallback-to-button, use both IDs (the element shows when either the agent or button is online): void
showWhenOnline(String buttonId, Object element, String userId)

Note: Any time you use both a buttonId and a userId, buttonId must appear first.

Parameters
Name Type Description Available Versions
buttonId String The ID of the chat button for which to display Available in API versions 28.0 and later.
the specified element object when agents
that are associated with the button are
available to chat.

11
Customize Deployments with the Deployment APIs showWhenOffline

Name Type Description Available Versions

element Object The element to be displayed when the Available in API versions 28.0 and later.
specified button is online.

userId String The ID of the agent to associate with the Available in API versions 29.0 and later.
button. The element object is displayed
when that agent is available.

If you specify a button ID but not a user ID in your parameters, the element is displayed only if the button is online.
If you specify a user ID but not a button ID, the element is displayed only if the agent is online. For example, the following syntax tracks
an agent’s online status and sets the button to online when that agent is available and offline if unavailable.
[Link]('005xx000001Sv1m',
[Link]('liveagent_button_toAgent_online'));

If you specify a button ID and an agent ID, the element is displayed if either the button or the agent is online. For example, the following
syntax tracks the status of an agent and a button and displays the element if at least one skilled agent is available.
[Link]('573xx0000000006',
[Link]('liveagent_button_online_573xx0000000006_USER1'), '005xx000001Sv1m');

showWhenOffline
Use the showWhenOffline method to specify what customers see when a particular button is offline.

Usage
Displays a particular element when the specified button, agent, or agent-with-fallback-button is offline. Available in API versions 28.0
and later.

Syntax
For a button, userId is optional: void showWhenOffline(String buttonId, Object element, (optional)
String userId)
For an agent, use userId instead of buttonId: void showWhenOffline(String userId, Object element)
For an agent with fallback-to-button, use both IDs (the element shows when either the agent or button is offline): void
showWhenOffline(String buttonId, Object element, String userId)

Note: Any time you use both a buttonId and a userId, buttonId must appear first.

12
Customize Deployments with the Deployment APIs addButtonEventHandler

Name Type Description Available Versions

element Object The element to display when the specified Available in API versions 28.0 and later.
button is offline.

userId String The ID of the agent to associate with the Available in API versions 29.0 and later.
button. The element object is displayed
when that agent is unavailable.

If you specify a button ID but not a user ID in your parameters, the element displays only if the button is offline.
If you specify a user ID but not a button ID, the element displays only if the agent is offline. For example, the following syntax tracks an
agent’s online status and sets the button to offline when that agent is unavailable.
[Link]('005xx000001Sv1m',
[Link]('liveagent_button_toAgent_offline'));

If you specify a button ID and an agent ID, the element displays if neither the button or the agent is available. For example, the following
syntax tracks the status of an agent and a button and displays the element if neither one is available.
[Link]('573xx0000000006',
[Link]('liveagent_button_offline_573xx0000000006_USER1'),
'005xx000001Sv1m');

addButtonEventHandler
Use the addButtonEventHandler method to define a chat button’s behavior when certain events occur. Available in API versions
28.0 and later.

Usage
Defines the behavior for a chat button when the following events occur:
• An agent is available to chat.
• No agents are available to chat.
The event “no agents are available to chat” occurs whenever a chat can’t reach an agent using the configured chat button. The event
occurs when:
• No agents are online.
• No agents assigned to the skills associated with the button are online.
• Online agents have the status Away.
• Online agents are at capacity (set with Chat Configurations, or Presence Configurations with Omni-Channel).
• Online agents are using Omni-Channel and are only available for other service channels.

Syntax
void addButtonEventHandler(String buttonId, Function callback)

13
Customize Deployments with the Deployment APIs startChat

Parameters
Name Type Description Available Versions
buttonId String The ID of the chat button for which to define Available in API versions 28.0 and later.
the behavior when certain events occur.

callback function The function to call when a particular event Available in API versions 28.0 and later.
occurs. You must specify the button’s behavior
for each of the required event types on page
14.

Event Types
Incorporate the following event types into your callback function to customize the behavior of your button when certain events
occur. You must specify the button’s behavior for each of the following event types.

Function Event Type Syntax Description

callback BUTTON_AVAILABLE liveagent.BUTTON_EVENT.BUTTON_AVAILABLE Specifies the
behavior of the
button when the
criteria are met for
customers to be
able to chat with
an agent, such as
when an agent
with the correct
skills is available to
chat.

BUTTON_UNAVAILABLE liveagent.BUTTON_EVENT.BUTTON_UNAVAILABLE Specifies the

behavior of the
button when no
agents are
available to chat.

startChat
Use the startChat method to request a chat from a button in a new window.

Usage
Requests a chat from the provided button in a new window.
Optionally, you can route chats from a specific button directly to the agent with the userId you specify. If the agent is unavailable,
you can route the chat to additional agents by specifying whether to fallback to the button’s routing rules (true) or not (false).

14
Customize Deployments with the Deployment APIs startChatWithWindow

Syntax
void startChat(String buttonId, (optional) String userId, (optional) Boolean fallback)

Parameters
Name Type Description Available Versions
buttonId String The ID of the chat button for which to request Available in API versions 28.0 and later.
a chat in a new window.

(Optional) userId String The Salesforce user ID of the agent to whom Available in API versions 29.0 and later.
to directly route chats from the button.

(Optional) Boolean Specifies whether to fall back to the button’s Available in API versions 29.0 and later.
fallback routing rules (true) or not (false) if the
agent with the specified sfdcUserId is
unavailable.

startChatWithWindow
Use the startChatWithWindow method to request a chat from a button using the name of a window.

Usage
Requests a chat from the provided button using the provided window name. Available in API versions 28.0 and later.

Syntax
void startChatWithWindow(String buttonId, String windowName, (optional) String userId,
(optional) Boolean fallback)

Parameters
Name Type Description Available Versions
buttonId String The ID of the chat button for which to request Available in API versions 28.0 and later.
a chat in a new window.

windowName String The name of the window. Available in API versions 28.0 and later.

(Optional) userId String The Salesforce user ID of the agent to whom Available in API versions 29.0 and later.
to directly route chats from the button.

15
Customize Deployments with the Deployment APIs Corresponding Calls for Chat Buttons

Corresponding Calls for Chat Buttons

Make sure your chats start correctly by aligning your calls when using buttons, direct-to-agent, and agent with fallback-to-button.
Keep in mind that the syntax for startChat also applies to startChatWithWindow, and the syntax for showWhenOnline
also applies to showWhenOffline.
Use the following corresponding calls when you’re creating chats with a button, direct-to-agent, and agent with fallback-to-button:

Scenario Call to startChat (or Call to showWhenOnline Call to

startChatWithWindow) (or showWhenOffline) addButtonEventHandler
Button startChat(String showWhenOnline(String addButtonEventHandler(
buttonId) buttonId, Object String buttonId,
element, (optional) Function callback)
String userId)

Agent (no fallback) startChat(String showWhenOnline(String addButtonEventHandler(

buttonId, String userId, Object String userId,
userId, false) element) Function callback)

Agent (fallback to button) startChat(String showWhenOnline(String Use multiple handlers.

buttonId, String buttonId, Object
userId, true) element, String
userId)

Find and Create Records Automatically with the Deployment APIs

Use the Deployment API to search for or create Salesforce records—like a case, contact, account, or lead—automatically when an agent
begins a chat with a customer.

addCustomDetail
Use the addCustomDetail method to add custom details for each chat visitor.
findOrCreate
Use the findOrCreate method to find existing records or create records based on certain criteria.
setName
Use the setName method to set the visitor name displayed in the Chat console or the Salesforce console.
Search for Knowledge Articles with the Deployment APIs
Use the Deployment API to search for Knowledge articles based on the information that a customer provides in a pre-chat form.
Find and Create Records Deployment API Code Sample
Test and preview how automatically creating records can work with your Chat deployments using this code sample.

16
Customize Deployments with the Deployment APIs addCustomDetail

addCustomDetail
Use the addCustomDetail method to add custom details for each chat visitor.

Usage
Adds a new custom detail for the chat visitor. The Custom Detail is displayed to agents in the footer widget and in the Chat Details page
in the Salesforce Console while the chat is active. Available in API versions 28.0 and later.

Syntax
addCustomDetail(String label, String value, (optional) Boolean displayToAgent)

Parameters
Name Type Description Available Versions
label String The label for the custom detail—for Available in API versions 28.0 and later.
example, "Name".

value String The value of the custom detail—for Available in API versions 28.0 and later.
example, "John Doe".

(Optional) Boolean Specifies whether to display the custom Available in API versions 29.0 and later.
displayToAgent details that customers provide in a pre-chat
form to the agent (true) or not (false).

findOrCreate
Use the findOrCreate method to find existing records or create records based on certain criteria.

Usage
Finds or creates a record of the specified type when a chat is routed by Omni-Channel or when an agent accepts a chat request that is
routed by Live Agent routing. For chats routed by Omni-Channel, the findOrCreate code triggers even if the chat visitor cancels
the chat before the agent accepts. For chats routed by Live Agent routing, the code triggers only when an agent accepts the chat request.

Note: The findOrCreate method begins the API call that finds existing records or create records when an agent begins a
chat with a customer. Use this method before calling any of the other findOrCreate submethods for finding or creating
records with the Deployment API.
Available in API versions 29.0 and later.

Limitations
For security reasons, this API is disabled by default on new orgs. You can enable this feature from the Chat Settings page in Setup. This
page also allows you to create an allowlist for allowed objects.

Note: If this feature is enabled and no objects are selected in the allowlist, all valid objects are allowed.

17
Customize Deployments with the Deployment APIs findOrCreate

Implement the findOrCreate call in an agent session and not a bot session. If findOrCreate matches multiple records, the
agent can choose which record to attach but the bot doesn't have a way of doing that.
Other limitations:
• For find, we don’t allow finding profiles or permission sets.

• For create, we don’t allow creating profiles or permission sets.

Syntax
[Link](String EntityName)

Parameters
Name Type Description Available Versions
EntityName String The type of record to search for or create when Available in API versions 29.0 and later.
an agent accepts a chat with a customer—for
example, a contact record.

[Link]
Use the [Link] method to search for or create records that contain specific customer details.
[Link]
Use the [Link] method to save the record you find or create to the chat transcript associated
with the chat.
[Link]
Use the [Link] method to automatically open the record you create in a subtab in the Salesforce
console.
[Link]
Use the [Link] method to link the record you found or created to another record type.

[Link]
Use the [Link] method to search for or create records that contain specific customer details.

Usage
Searches for or creates records that contain customer data specified by the addCustomDetail Deployment API method. This
method maps the value of the custom details to the fields on the specified record in the Salesforce console.
You can call the [Link] method as many times as necessary to find the appropriate records. Call the method once
for every field and its corresponding custom detail value you want to search for.
Implement the [Link] call in an agent session and not a bot session. If [Link] matches multiple
records, the agent can choose which record to attach but the bot doesn't have a way of doing that.

Note: To find the API name of a field for a standard object, see our API documentation. For non-standard objects, look at the field
detail for the object under Setup.

18
Customize Deployments with the Deployment APIs findOrCreate

Available in API versions 29.0 and later.

Syntax
[Link](Object EntityName).map(String FieldName, String DetailName,
Boolean doFind, Boolean isExactMatch, Boolean doCreate)

Parameters

Name Type Description Available Versions

FieldName String The API name of the field in the record Available in API versions 29.0 and later.
EntityNameto which to map the
corresponding custom detail DetailName.

DetailName String The value of the custom detail to map to the Available in API versions 29.0 and later.
corresponding field FieldName.

doFind Boolean Specifies whether to search for a record that Available in API versions 29.0 and later.
contains the custom detail DetailName in
the field FieldName (true) or not
(false).

isExactMatch Boolean Specifies whether to search for a record that Available in API versions 29.0 and later.
contains the exact value of the custom detail
DetailName you specified in the field
FieldName (true) or not (false).

doCreate Boolean Specifies whether to create a new record with Available in API versions 29.0 and later.
the custom detail DetailName in the field
FieldName if one isn’t found (true) or not
(false).

[Link]
Use the [Link] method to save the record you find or create to the chat transcript associated
with the chat.

Usage
Saves the record that you found or created using the findOrCreate and [Link] Deployment API methods to
the chat transcript associated with the chat.
Available in API versions 29.0 and later.

Syntax
[Link](String EntityName).saveToTranscript(String TranscriptFieldName)

19
Customize Deployments with the Deployment APIs findOrCreate

Parameters

Name Type Description Available Versions

TranscriptFieldName String The name of the field on the chat transcript Available in API versions 29.0 and later.
record to which to save the ID of the record
you found or created.

[Link]
Use the [Link] method to automatically open the record you create in a subtab in the Salesforce
console.

Usage
Opens the record you created using the findOrCreate and [Link] Deployment API methods automatically in
a subtab in the to the Salesforce console.
Available in API versions 29.0 and later.

Syntax
[Link](String EntityName).showOnCreate()

[Link]
Use the [Link] method to link the record you found or created to another record type.

Usage
Links the record that you found or created using the findOrCreate and [Link] Deployment API methods to
another record of a different record type that you created using a separate findOrCreate API call. For example, you can link a case
record you found within your organization to a contact record you create.

Note: You can only link records if the parent record is created with a findOrCreate API call. You can’t link a child record to
a record you found using the [Link] method.
Available in API versions 29.0 and later.

Syntax
[Link](String EntityName).linkToEntity(String EntityName, String
FieldName)

Parameters

Name Type Description Available Versions

EntityName String The type of record to which to link the child Available in API versions 29.0 and later.
record you found or created.

20
Customize Deployments with the Deployment APIs setName

Name Type Description Available Versions

FieldName String The name of the API field in the record Available in API versions 29.0 and later.
EntityName to which to save the ID of the
child record you found or created.

Note: To find the API name of a field for a standard object, see our API documentation. For non-standard objects, look at the field
detail for the object under Setup.

setName
Use the setName method to set the visitor name displayed in the Chat console or the Salesforce console.

Usage
Sets the visitor name displayed in the Salesforce console. The name will show in the chat’s primary tab, the agent’s chat log with the
chat transcript, and in the Live Agent Supervisor panel. Available in API versions 28.0 and later.

Syntax
setName(String name)

Parameters
Name Type Description Available Versions
name String The visitor name that appears in the Chat Available in API versions 28.0 and later.
console or the Salesforce console.

Search for Knowledge Articles with the Deployment APIs

Use the Deployment API to search for Knowledge articles based on the information that a customer provides in a pre-chat form.

[Link]
Use the knowledgeSearch method to automatically search for Knowledge articles based on criteria in a pre-chat form.

Usage
Retrieves a custom detail value from a pre-chat form when a customer requests a chat with an agent. After an agent accepts the chat
request, this value is used as a search keyword to find articles in the Knowledge One widget. The doKnowledgeSearch() method
conducts a search by using the value parameter in the addCustomDetail method. Available in API version 31.0 and later.

21
Customize Deployments with the Deployment APIs Find and Create Records Deployment API Code Sample

Syntax
[Link](String label, String value, (optional) Boolean
displayToAgent).doKnowledgeSearch()

Find and Create Records Deployment API Code Sample

Test and preview how automatically creating records can work with your Chat deployments using this code sample.
The following code searches for and creates records when an agent begins a chat with a customer using the following methods:
• addCustomDetail
• findOrCreate
• [Link]
• [Link]
• [Link]
• [Link]
<script type='text/javascript'>
/* Creates a custom detail called First Name and sets the value to "Jane" */
[Link]("First Name", "Jane");

/* Creates a custom detail called Last Name and sets the value to "Doe" */
[Link]("Last Name", "Doe");

/* Creates a custom detail called Phone Number and sets the value to "555-1212" */
[Link]("Phone Number", "415-555-1212");

/* Creates a custom detail called Case Subject and sets the value to "Best snowboard for
a beginner" and will perform a knowledge search when the chat is accepted for the agent
*/

[Link]("Case Subject", "Best snowboard for a

beginner").doKnowledgeSearch();

/* Creates a custom detail called Case Status and sets the value to "New" */
[Link]("Case Status", "New");

/* This does a non-exact search on cases by the value of the "Case Subject" custom detail.

If no results are found, it will create a case and set the case's subject and status
The case that's found or created will be associated to the chat and the case will open
in
the Console for the agent when the chat is accepted */
[Link]("Case").map("Subject","Case
Subject",true,false,true).map("Status","Case
Status",false,false,true).saveToTranscript("CaseId").showOnCreate();

/* This searches for a contact whose first and last name exactly match the values in the
custom details for First and Last Name
If no results are found, it will create a new contact and set it's first name, last name,
and phone number to the values in the custom details */
[Link]("Contact").map("FirstName","First

22
Customize Deployments with the Deployment APIs Customize Automated Chat Invitations with the Deployment
APIs

Name",true,true,true).map("LastName","Last Name",true,true,true).map("Phone","Phone
Number",false,false,true);

/* The contact that's found or created will be saved or associated to the chat transcript.
The contact will be opened for the agent in the Console and the case is linked to the
contact record */
[Link]("Contact").saveToTranscript("ContactId").showOnCreate().linkToEntity("Case","ContactId");
</script>

Customize Automated Chat Invitations with the Deployment APIs

Customize automated chat invitations that appear to customers on your website.

setCustomVariable
Use the setCustomVariable method to create customized criteria in your sending rules that must be met in order for your
automated invitation to be sent to customers.
rejectChat
Use the rejectChat method to reject and retract an invitation that’s been sent to a customer.
addButtonEventHandler
Use the addButtonEventHandler method to define an automated invitation’s behavior when certain events occur.
Automated Chat Invitation Code Sample
Test and preview how automated chat invitations can work on your website using this code sample.

setCustomVariable
Use the setCustomVariable method to create customized criteria in your sending rules that must be met in order for your
automated invitation to be sent to customers.

Usage
Creates customized criteria in your sending rules that must be met in order for your automated invitation to be sent to customers.
Specifies the comparison values for custom variables used in criteria for your sending rules. Available in API versions 28.0 and later.

Syntax
void setCustomVariable(String variableName, Object value)

23
Customize Deployments with the Deployment APIs rejectChat

Parameters
Name Type Description Available Versions
variableName String The name of the customized criteria for your Available in API versions 28.0 and later.
custom sending rule.

value Object The comparison value for your custom sending Available in API versions 28.0 and later.
rule.

rejectChat
Use the rejectChat method to reject and retract an invitation that’s been sent to a customer.

Usage
Rejects an invitation and causes it to be retracted.
Available in API versions 28.0 and later.

Syntax
void rejectChat(String buttonId)

Parameters
Name Type Description Available Versions
buttonId String The ID of the chat button for which to reject Available in API versions 28.0 and later.
chats.

addButtonEventHandler
Use the addButtonEventHandler method to define an automated invitation’s behavior when certain events occur.

Usage
Defines the behavior for an invitation when the following events occur:
• The criteria are met for the invitation to appear on-screen.
• The criteria are not met for the invitation to appear on-screen.
• A customer accepts an invitation to chat.
• A customer rejects an invitation to chat.
The event “the criteria are not met for the invitation to appear on the screen” occurs when a chat can’t reach an agent using the configured
chat button or automated invitation. The event occurs when:
• No agents are online.
• No agents assigned to the skills associated with the button are online.

24
Customize Deployments with the Deployment APIs addButtonEventHandler

• Online agents have the status Away.

• Online agents are at capacity (set with Chat Configurations, or Presence Configurations with Omni-Channel).
• Online agents are using Omni-Channel and are only available for other service channels.
Available in API versions 28.0 and later.

Syntax
void addButtonEventHandler(String buttonId, Function callback)

Parameters
Name Type Description Available Versions
buttonId String The ID of the chat button associated with the Available in API versions 28.0 and later.
automated invitation for which to define the
behavior when certain events occur.

callback function The function to call when a particular event Available in API versions 28.0 and later.
occurs. You must specify the invitation’s
behavior for each of the required event types
on page 25.

Event Types
Incorporate the following event types into your callback function to customize the behavior of your invitation when certain events
occur. You must specify the invitation’s behavior for each of the following event types.

Function Event Type Syntax Description

callback BUTTON_AVAILABLE liveagent.BUTTON_EVENT.BUTTON_AVAILABLE Specifies the
behavior of the
automated
invitation when the
criteria are met for
the invitation to
appear on-screen.

BUTTON_UNAVAILABLE liveagent.BUTTON_EVENT.BUTTON_UNAVAILABLE Specifies the

behavior of the
automated
invitation when the
criteria are not met
for the invitation to
appear on-screen.

BUTTON_ACCEPTED liveagent.BUTTON_EVENT.BUTTON_ACCEPTED Specifies the

behavior of the
automated
invitation when a

25
Customize Deployments with the Deployment APIs Automated Chat Invitation Code Sample

Function Event Type Syntax Description

customer accepts
the invitation. This
event type is only
available for
automated chat
invitations.

BUTTON_REJECTED liveagent.BUTTON_EVENT.BUTTON_REJECTED Specifies the

behavior of the
automated
invitation when a
customer rejects
the invitation. This
event type is only
available for
automated chat
invitations.

Note: You might receive multiple events of the same type.

Automated Chat Invitation Code Sample

Test and preview how automated chat invitations can work on your website using this code sample.
The following code is for an automated chat invitation that uses the addButtonEventHandler() method to display a customized
invitation on a website. This invitation allows customers to start a chat with an agent when an agent with the correct skills is available
to chat.
<apex:page>

<div id="liveagent_invite_button_573D01234567890" style="display: none; position: fixed;
border: 2px solid darkblue; border-radius: 5px; background-color: lightblue; height: 100px;
width: 200px;">

<div style="cursor: pointer; padding: 5px; right: 0px; position: absolute; color: darkred;
font-weight: bold;" onclick="[Link]('573D01234567890')">X</div>

<div style="cursor: pointer; top: 42px; left: 65px; position: absolute;font-weight: bold;
font-size: 16px;" onclick="[Link]('573D01234567890')">Start Chat</div>
</div>

26
Customize Deployments with the Deployment APIs Automated Chat Invitation Code Sample

src='[Link]

// When the chat invitation is online (i.e. at least one available, skilled agent),
display it at position top 200px and left 300px if (e ==
liveagent.BUTTON_EVENT.BUTTON_AVAILABLE) {
[Link]('liveagent_invite_button_573D01234567890').[Link] = '';
[Link]('liveagent_invite_button_573D01234567890').[Link] = '300px';

[Link]('liveagent_invite_button_573D01234567890').[Link] = '200px';

// When the chat invitation is offline, don't display it

if (e == liveagent.BUTTON_EVENT.BUTTON_UNAVAILABLE) {
[Link]('liveagent_invite_button_573D01234567890').[Link] = 'none';

// When the chat invitation is accepted, stop displaying it if (e ==

liveagent.BUTTON_EVENT.BUTTON_ACCEPTED) {
[Link]('liveagent_invite_button_573D01234567890').[Link] = 'none';

// When the chat invitation is rejected, stop displaying it if (e ==

liveagent.BUTTON_EVENT.BUTTON_REJECTED) {
[Link]('liveagent_invite_button_573D01234567890').[Link] = 'none';

}
}

// Registers the function buttonCallback() above as the callback for the chat invitation
whose id is 573D01234567890 [Link]('573D01234567890',
buttonCallback);

// Let's say there is data available in JavaScript that you want to use in a custom sending
rule.
var shoppingCartValue = 123.45;
// To pass this data so it can be used in Sending Rules in Salesforce setup, call
setCustomVariable.
[Link]('shoppingCartValue', shoppingCartValue);

// Chat deployment code that initializes chat for the deployment whose id is 572D01234567890
and org is 00DD01234567890
[Link]('[Link] '572D01234567890',
'00DD01234567890');

// Enable Chat advanced logging to be available through the Browser's Developer Console

27
Customize Deployments with the Deployment APIs Deployment API Code Sample

[Link]();
</script>

</apex:page>

This code lets you pass data that’s available in JavaScript so it can be used in your invitation’s sending rules in Setup. This is an example
of how your settings might look:

Deployment API Code Sample

Test and preview how the Deployment API can help you customize your deployments.

Chat Window
This code sample creates a chat window that uses the following Deployment API methods:
• startChat
• showWhenOnline
• showWhenOffline
• addCustomDetail
• setName
• map
• setChatWindowWidth
• setChatWindowHeight
• doKnowledgeSearch

Warning: Details added via the Deployment API are associated with the Visitor. When a chat is launched, the Chasitor is associated
with the initial visitor. A subsequent request is a new Chasitor associated with the same visitor. To create details associated with
only one Chasitor, the Prechat API must be used instead.
<apex:page showHeader="false">
<style> body { margin: 25px 0 0 25px; } </style>

<h1>Welcome to Support</h1>

28
Customize Deployments with the Deployment APIs Deployment API Code Sample

<br />
Thank you for your interest.
<br /><br />

<a id="liveagent_button_online_573B0000000033Y" href="javascript://Chat" style="display:
none;" onclick="[Link]('573B0000000033Y')">Chat Now</a>
<div id="liveagent_button_offline_573B0000000033Y" style="display: none;">Chat is currently
unavailable</div>
<script type="text/javascript">
if (!window._laq) { window._laq = []; }
window._laq.push(function(){
[Link]('573B0000000033Y',
[Link]('liveagent_button_online_573B0000000033Y'));
[Link]('573B0000000033Y',
[Link]('liveagent_button_offline_573B0000000033Y'));
});</script>

<script type='text/javascript'
src='[Link]

/* Creates a custom detail called First Name and sets the value to Jane */
[Link]('First Name', 'Jane');

/* Creates a custom detail called Last Name and sets the value to Doe */
[Link]('Last Name', 'Doe');

/* Creates a custom detail called Phone Number and sets the value to 415-555-1212 */
[Link]('Phone Number', '415-555-1212');

/* An auto-query that searches Contacts whose Email field exactly matches 'jane@[Link]'.
If no result is found, it will create a Contact record with the email, first name, last
name, and phone number fields set to the custom detail values. */
[Link]('Contact').map('Email','Contact
E-mail',true,true,true).map('FirstName','First Name',false,false,true).map('LastName','Last
Name',false,false,true).map('Phone','Phone Number',false,false,true);

/* The contact that's found or created will be saved or associated to the chat transcript.
The contact will be opened for the agent in the Console and the case is linked to the
contact record */
[Link]('Contact').saveToTranscript('ContactId').showOnCreate().linkToEntity('Case','ContactId');

/* Creates a custom detail called Case Subject and sets the value to 'Refund policy for
products' and will perform a knowledge search when the chat is accepted for the agent */
[Link]('Case Subject','Refund policy for products').doKnowledgeSearch();

29
Customize Deployments with the Deployment APIs Deployment API Code Sample

/* Creates a custom detail called Case Status and sets the value to 'New' */
[Link]('Case Status','New');

/* This does a non-exact search on cases by the value of the 'Case Subject' custom detail
If no results are found, it will create a case and set the case's subject and status.
The case that's found or created will be associated to the chat and the case will open in
the Console for the agent when the chat is accepted */
[Link]('Case').map('Subject','Case
Subject',true,false,true).map('Status','Case
Status',false,false,true).saveToTranscript('CaseId').showOnCreate();

/* Saves the custom detail to a custom field on LiveChatTranscript at the end of a chat.
Assumes a custom field called Company__c was added to the Live Chat Transcript object */
[Link]('Company', 'Acme').saveToTranscript('Company__c');

/* For internal or technical details that don't concern the agent, set showToAgent to false
to hide them from the display. */
[Link]('VisitorHash', 'c6f440178d478e4326a1', false);

/* Sets the display name of the visitor in the agent console when engaged in a chat */
[Link]('Jane Doe');

/* Sets the width of the chat window to 500px */

[Link](500);

/* Sets the height of the chat window to 500px */

[Link](500);

[Link]('[Link] '572B000000003KL', '00DB00000000Rr8');
</script>
</apex:page>

This code results in the following view for agents using the Console.

30
Customize Deployments with the Deployment APIs Deployment API Code Sample

The name of the customer (Jane Doe for this example) appears in the Console from setName (1). When you call
[Link], the search automatically appears in the Knowledge widget (2).
When the agent receives a chat, the set Custom Details appear in a hover window.

31
Customize Deployments with the Deployment APIs Deployment API Code Sample

Optional Cookies
You can use your consent manager to provide users the ability to opt in or opt out of optional cookies. If they choose to opt in you can
pass true to the fourth parameter in [Link]() to enable tracking optional cookies. Otherwise, if they choose to opt
out, pass false. Omitting the fourth parameter is the same as passing true.

Note: The ability to provide opt-out from optional cookies is supported in version 52.0 and later of the Deployment API.

/* Enable optional cookies*/

[Link]('[Link] '572B000000003KL', '00DB00000000Rr8',
true);
[Link]('[Link] '572B000000003KL', '00DB00000000Rr8');

/* Disable optional cookies */

[Link]('[Link] '572B000000003KL', '00DB00000000Rr8',
false);

If the user opts out, you can also call [Link](). This deletes and stops tracking the optional
cookies. This is the same as passing false to [Link]() except that it takes higher order of precedence than
[Link]() with the value true. For example, if you call [Link]() first and
then pass true to [Link](), optional cookies are still disabled. Unlike [Link](),
[Link]() can also be called anytime after the page is loaded.

/* Disable optional cookies.*/

[Link]()

If the user opts back in to optional cookies after opting out, pass true to [Link]() on the next page load.
<apex:page showHeader="false">
<style> body { margin: 25px 0 0 25px; } </style>

...

/* To enable tracking optional cookies, pass `true` to the fourth parameter. To disable
them, pass `false` to the fourth parameter or call [Link]().*/
[Link]('[Link] '572B000000003KL',
'00DB00000000Rr8',true);
</script>
</apex:page>

32
CHAPTER 5 Use Pre-Chat to Gather Visitor Information
and Set Context for the Agent

Use pre-chat forms in to collect information from visitors and customize their pre-chat experience.

Find and Create Records Automatically with the Pre-Chat APIs

Use the Pre-Chat API to search for or create customer records automatically when a customer completes a pre-chat form.
Access Chat Details with the Pre-Chat APIs
Use the Pre-Chat API to access custom details from the Deployment API and incorporate them into pre-chat.

Find and Create Records Automatically with the Pre-Chat APIs

Use the Pre-Chat API to search for or create customer records automatically when a customer completes a pre-chat form.

[Link]
Use the [Link] method to search for or create records that contain specific customer details.
[Link]
Use the [Link] method to find or create a record and save it to the chat transcript associated
with the chat.
[Link]
Use the [Link] method to find or create a record and automatically open it in a subtab in the
Salesforce console.
[Link]
Use the [Link] method to link the record you found or created to another record type.

33
Use Pre-Chat to Gather Visitor Information and Set Context [Link]
for the Agent

[Link]
Use the [Link] method to specify which pre-chat details will be displayed to agents for incoming
chats in the widget and in the Details tab when they receive a chat request.
Find and Create Records Pre-Chat API Code Sample
Test and preview how to automatically create records when a customer completes a pre-chat form using this code sample.

[Link]
Use the [Link] method to search for or create records that contain specific customer details.

Usage
Searches for or creates records that contain the customer data that’s specified in the pre-chat form that the customer completes. This
method maps the value of the custom details to the fields on the specified record in the Salesforce console.
You can call the [Link] method as many times as necessary to find the appropriate records. You can list multiple
fields and their corresponding details to map the detail values to the appropriate fields within the record.
Available in API versions 29.0 and later.

Syntax
<input type= "hidden" name= "[Link]: String entityName"
value= "String fieldName, String detailName;" />

Parameters
Name Type Description Available Versions
entityName String The type of record to search for or create when Available in API versions 29.0 and later.
an agent accepts a chat with a customer, for
example, a contact record

fieldName String The name of the field in the record Available in API versions 29.0 and later.
EntityName to which to map the
corresponding custom detail value

detailName String The value of the custom detail to map to the Available in API versions 29.0 and later.
corresponding field fieldName

[Link]
Use the [Link] method to specify which fields to search against existing customer records when a
customer completes a pre-chat form.
[Link]
Use the [Link] method to specify whether a field value must exactly match the field value
in an existing record when you conduct a search with the [Link] method.

34
Use Pre-Chat to Gather Visitor Information and Set Context [Link]
for the Agent

[Link]
Use the [Link] method to specify which fields in [Link] method to use to create
a new record if an existing record isn’t found.

[Link]
Use the [Link] method to specify which fields to search against existing customer records when a customer
completes a pre-chat form.

Usage
Specifies which fields in your [Link] method to use to search for an existing record. You can search for one or more
fields within records, but note that when multiple fields are specified, the logic relationship is AND. This means that all specified fields
must match an existing record for it to be found.
When using custom fields, follow these guidelines:
• Checkboxes have valid values true and false when trying to search or create related to custom fields.
• Dates use the format YYYY-MM-DD.
• Numbers in the Currency field don’t have a currency sign.
• Numbers in the Percentage field don’t have a percentage sign.
Available in API versions 29.0 and later.

Syntax
<input type= "hidden" name= "[Link]: String
entityName" value= "String fieldName, Boolean find;" />

Parameters

Name Type Description Available Versions

entityName String The type of record to search for or create when Available in API versions 29.0 and later.
an agent accepts a chat with a customer—for
example, a contact record.

fieldName String The name of the API field to search for in Available in API versions 29.0 and later.
existing records.

Note: To find the API name of a field

for a standard object, see our API
documentation. For non-standard
objects, look at the field detail for the
object under Setup.

35
Use Pre-Chat to Gather Visitor Information and Set Context [Link]
for the Agent

Name Type Description Available Versions

find Boolean Specifies whether to search for existing records Available in API versions 29.0 and later.
that contain the field fieldName (true)
or not (false).

Note: You can specify only the fields

for which find equals true. The
method doesn’t search for records
containing fields for which find
equals false.

[Link]
Use the [Link] method to specify whether a field value must exactly match the field value in an
existing record when you conduct a search with the [Link] method.

Usage
Specifies which fields in your [Link] method require an exact field value match when you search for existing records.
You can specify this for one or more fields within records.
Available in API versions 29.0 and later.

Syntax
<input type= "hidden" name= "[Link]: String
entityName" value= "String fieldName, Boolean exactMatch;" />

Parameters

Name Type Description Available Versions

entityName String The type of record to search for or create when Available in API versions 29.0 and later.
an agent accepts a chat with a customer—for
example, a contact record.

fieldName String The API name of the field to search for in Available in API versions 29.0 and later.
existing records.

Note: To find the API name of a field

for a standard object, see our API
documentation. For non-standard
objects, look at the field detail for the
object under Setup.

36
Use Pre-Chat to Gather Visitor Information and Set Context [Link]
for the Agent

Name Type Description Available Versions

find Boolean Specifies whether to search for existing records Available in API versions 29.0 and later.
that contain an exact match to the field
fieldName (true) or not (false).

Note: You only need to specify fields

for which exactMatch equals
true. The method will not search for
records containing fields for which
exactMatch equals false.

[Link]
Use the [Link] method to specify which fields in [Link] method to use to create a
new record if an existing record isn’t found.

Usage
Specifies which fields in your [Link] method to use to create a new record if an existing record isn’t found. You can
specify one or more fields for creating new records.
Available in API versions 29.0 and later.

Syntax
<input type= "hidden" name= "[Link]: String
entityName" value= "String fieldName, Boolean create;" />

Parameters

Name Type Description Available Versions

entityName String The type of record to create when an agent Available in API versions 29.0 and later.
accepts a chat with a customer and an existing
record isn’t found—for example, a contact
record.

fieldName String The API name of the field to include in new Available in API versions 29.0 and later.
records.

Note: The findOrCreate method

begins the API call that finds existing
records or create new records when an
agent begins a chat with a customer.
You must use this method before
calling any of the other
findOrCreate sub-methods for
finding or creating records with the
Deployment API.

37
Use Pre-Chat to Gather Visitor Information and Set Context [Link]
for the Agent

Name Type Description Available Versions

create Boolean Specifies whether to create a new record that Available in API versions 29.0 and later.
contains the field fieldName (true) or
not (false).

Note: You only need to specify fields

for which create equals true. The
method will not create records
containing fields for which create
equals false.

[Link]
Use the [Link] method to find or create a record and save it to the chat transcript associated
with the chat.

Usage
Saves the record that you found or created using the [Link] or [Link]
Pre-Chat API methods to the chat transcript associated with the chat when the chat ends.
Available in API versions 29.0 and later.

Syntax
<input type="hidden" name= "[Link]: String
entityName" value= "String transcriptFieldName" />

Parameters
Name Type Description Available Versions
entityName String The type of record to search for or create Available in API versions 29.0 and later.
when an agent accepts a chat with a
customer—for example, a contact record.

transcriptFieldName String The API name of the field on the chat Available in API versions 29.0 and later.
transcript record to which to save the ID of
the record you found or created.

Note: To find the API name of a field for a standard object, see our API documentation. For non-standard objects, look at the field
detail for the object under Setup.

38
Use Pre-Chat to Gather Visitor Information and Set Context [Link]
for the Agent

[Link]
Use the [Link] method to find or create a record and automatically open it in a subtab in the Salesforce
console.

Usage
Opens the record you created using the [Link] and [Link] Pre-Chat API
methods automatically in a subtab in the to the Salesforce console.
Available in API versions 29.0 and later.

Syntax
<input type= "hidden" name= "[Link]: String
entityName" value= "Boolean show" />

show Boolean Specifies whether to display the record you Available in API versions 29.0 and later.
created in a subtab in the Salesforce console
(true) or not (false).

[Link]
Use the [Link] method to link the record you found or created to another record type.

Usage
Links the record you’ve found or created using the [Link] and [Link]
methods to another record of a different record type that you created using a separate [Link] API call. For example,
you can link a case record you found within your organization to a contact record you create.
The [Link] method links the found or created record to one record. If you try to link a found or created
record to multiple records, the found or created record is linked only to the first record.
The [Link] method can’t be used to populate fields on records that you create by using the
findOrCreate API call. Instead, use the [Link] method to update field values on records.

39
Use Pre-Chat to Gather Visitor Information and Set Context [Link]
for the Agent

Syntax
<input type= "hidden" name= "[Link]: String
entityName" value= "String parentEntityName, String fieldName" />

Parameters
Name Type Description Available Versions
entityName String The type of record which is linked to the parent Available in API versions 29.0 and later.
record you found or created.

parentEntityName String The type of parent record to link to the child Available in API versions 29.0 and later.
record you found or created.

fieldName String The name of the field in the record Available in API versions 29.0 and later.
parentEntityName where the ID of the
child record you found or created is saved.

[Link]
Use the [Link] method to specify which pre-chat details will be displayed to agents for incoming
chats in the widget and in the Details tab when they receive a chat request.

Usage
Specifies which pre-chat details to display to an agent in the Details tab in Salesforce console when the agent receives a chat request.
Typically, this method is only used to hide particular custom details from the agent but setting its value to false.
Available in API versions 29.0 and later.

Syntax
<input type= "hidden" name= "[Link]: String
detailName" value= "Boolean display" />

Parameters
Name Type Description Available Versions
detailName String The name of the detail to display to an agent Available in API versions 29.0 and later.
when they receive a chat request.

display Boolean Specifies whether to display the custom detail Available in API versions 29.0 and later.
to an agent in the chat notifications and Details
tab (true) or not (false).

Note: You only need to specify details

for which display equals false.
The method will not display details for

40
Use Pre-Chat to Gather Visitor Information and Set Context Find and Create Records Pre-Chat API Code Sample
for the Agent

Name Type Description Available Versions

which display equals false. If

you don’t specify the value of the
display parameter, the default value
is set to true.

Find and Create Records Pre-Chat API Code Sample

Test and preview how to automatically create records when a customer completes a pre-chat form using this code sample.
The following code searches for and creates records when a customer completes a pre-chat form using the following methods:
• [Link]
• [Link]
• [Link]
• [Link]
• [Link]
• [Link]
• [Link]
<form method="post" action="#">
<label>First Name: </label> <input type='text' name='[Link]:ContactFirstName'
/><br />
<label>Last Name: </label> <input type='text' name='[Link]:ContactLastName'
/><br />
<label>Subject: </label> <input type='text' name='[Link]:CaseSubject' /><br />
<input type="hidden" name="[Link]:CaseStatus" value="New" /><br />
<input type="hidden" name="[Link]:Contact"
value="FirstName,ContactFirstName;LastName,ContactLastName" />
<input type="hidden" name="[Link]:Contact"
value="FirstName,true;LastName,true" />
<input type="hidden" name="[Link]:Contact"
value="FirstName,true;LastName,true" />
<input type="hidden" name="[Link]:Contact"
value="FirstName,true;LastName,true" />
<input type="hidden" name="[Link]:Contact"
value="ContactId" />
<input type="hidden" name="[Link]:Contact" value="true"
/>
<input type="hidden" name="[Link]:Contact"
value="Case,ContactId" />
<input type="hidden" name="[Link]:Case"
value="Subject,CaseSubject;Status,CaseStatus" />
<input type="hidden" name="[Link]:Case"
value="Subject,true;Status,true" />
<input type="submit" value="Submit" />
</form>

41
Use Pre-Chat to Gather Visitor Information and Set Context Access Chat Details with the Pre-Chat APIs
for the Agent

Access Chat Details with the Pre-Chat APIs

Use the Pre-Chat API to access custom details from the Deployment API and incorporate them into pre-chat.

preChatInit
Use the preChatInit method to access the deployment information that has been passed into the chat through the
addCustomDetail Deployment API method.

Usage
Extracts chat deployment information, including Custom Details, for use with pre-chat. When you use preChatInit, include the
[Link] file in the same Apex page and with the same path as the [Link] file.
Available in API versions 29.0 and later.

Syntax
[Link](String chatUrl, function detailCallback, (optional) String
chatFormName)

Parameters
Name Type Description Available Versions
chatUrl String The URL of the chat to retrieve custom Available in API versions 29.0 and later.
details from.

detailCallback String Name of the JavaScript function to call Available in API versions 29.0 and later.
upon completion of the method.

(Optional) chatFormName String The name of the HTML form tag for the Available in API versions 29.0 and later.
pre-chat form to which to incorporate the
custom details.

42
Use Pre-Chat to Gather Visitor Information and Set Context preChatInit
for the Agent

Responses
Name Type Description Available Versions
details Object An object containing the deployment Available in API versions 29.0 and later.
information included in the pre-chat form
using the preChatInit method.

detailCallback
The detailCallback method specifies the behavior that occurs after the preChatInit method returns the details object.

Syntax Parameters Description Available Versions

function details Specifies the actions to occur after the Available in API versions 29.0 and later.
myCallBack(details) custom details are retrieved using the
{ // Customer preChatInit method.
specific code }

43
CHAPTER 6 Implement a Custom Chat Window Using
Visualforce

Chat windows are what visitors use to exchange messages with support agents. Each of your Chat deployments includes a chat window.
You can create a customized chat window by using Visualforce, and you can add styling and functionality with HTML, CSS, and JavaScript.

Important: The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then.
During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid
service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the
chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement
in Help.
Einstein Bots doesn’t support menus and quick replies in custom Chat windows. To learn more about Einstein Bots Chat channel
specifications, see Deploy Your Bot to Channels.
Avoid linking to Salesforce CSS stylesheets when you customize your chat window. They aren’t versioned and can change without notice.
Instead, we recommend that you use Visualforce components that mimic Salesforce styles instead of directly referencing the stylesheets.
That way, you’re always in control of how your chat window looks. See Using Styles from Salesforce Stylesheets to lean how to disable
our stylesheets.
For more information on using Visualforce, see the Visualforce Developer Guide.

Chat Visualforce Components

Use Visualforce components to customize the appearance and behavior of chat windows.
Chat Visualforce Components Code Sample
Use this code sample to test and preview how Visualforce components can help you customize your chat windows.

Chat Visualforce Components

Use Visualforce components to customize the appearance and behavior of chat windows.

Component Name Description

liveAgent:clientChat The main parent element for any chat window. This element is necessary to do any
additional customization of Chat. This component can only be used once in a Chat
deployment.

44
Implement a Custom Chat Window Using Visualforce Chat Visualforce Components

Component Name Description

liveAgent:clientChatAlertMessage The area in a chat window that displays system alert messages (such as "You have
been disconnected").

liveAgent:clientChatMessages The area in a chat window that displays system status messages, such as "Chat session
has been disconnected." Must be used within liveAgent:clientChat. Each
chat window can have only 1 message area.

liveAgent:clientChatStatusMessage The area in a chat window that displays system status messages (such as "You are
being reconnected").

liveAgent:clientChatQueuePosition A text label indicating a visitor's position in a queue for a chat session that’s initiated
by a button that uses push routing. (This component has no effect on buttons that
use pull routing.) Must be used within liveAgent:clientChat. For more
information on this component, see Using
liveAgent:clientChatQueuePosition.

liveAgent:clientChatCancelButton The button within a chat window when the chat is in a waiting state that allows the
visitor to cancel the chat. Must be used within liveAgent:clientChat.

liveAgent:clientChatSaveButton The button in a chat window that a visitor clicks to save the chat transcript as a local
file. Must be used within liveAgent:clientChat. Each chat window can
have multiple save buttons.

liveAgent:clientChatEndButton The button within a chat window that a visitor clicks to end a chat session. Must be
used within liveAgent:clientChat.

liveAgent:clientChatLog The area in a chat window that displays the chat conversation to a visitor. Must be
used within liveAgent:clientChat. Each chat window can have only 1 chat
log.

liveAgent:clientChatInput The text box in a chat window where a visitor types messages to a support agent.
Must be used within liveAgent:clientChat. Each chat window can have
only 1 input box.

liveAgent:clientChatSendButton The button in a chat window that a visitor clicks to send a chat message to an agent.
Must be used within liveAgent:clientChat. Each chat window can have
multiple send buttons.

liveAgent:clientChatLogAlertMessage The area in a chat window that displays the idle time-out alert (customer warning)
to a visitor.

liveAgent:clientChatFileTransfer The file upload area in a chat window where a visitor can send a file to an agent. Must
be used within liveAgent:clientChat.

For more information about each of these components, see the Visualforce Component Guide.

Using liveAgent:clientChatQueuePosition
The liveAgent:clientChatQueuePosition component shows where in the chat queue a visitor is. In order for a chat to
enter the queue:

45
Implement a Custom Chat Window Using Visualforce Chat Visualforce Components Code Sample

• The button from which the chat was requested must have queuing enabled.
• All online agents (with the relevant skills, if applicable) must be at capacity, causing a queue to form.
• The chat must be in the queue and not yet assigned to an agent.
If all three of these conditions aren’t met, liveAgent:clientChatQueuePosition doesn't display a value.

Chat Visualforce Components Code Sample

Use this code sample to test and preview how Visualforce components can help you customize your chat windows.

Important: The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then.
During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid
service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the
chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement
in Help.
The following code sample shows a chat window that uses the following components:
• liveAgent:clientChat
• liveAgent:clientChatMessages
• liveAgent:clientChatEndButton
• liveAgent:clientChatLog
• liveAgent:clientChatInput
<apex:page showHeader="false">
<style>
#[Link] {
// The CSS class that is applied when the chat request is waiting to be accepted
// See "Waiting State" screenshot below
}
#liveAgentClientChat {
// The CSS class that is applied when the chat is currently engaged
// See "Engaged State" screenshot below
}
#[Link] {
// The CSS class that is applied when the chat has ended
// See "Ended State" screenshot below
}
body { overflow: hidden; width: 100%; height: 100%; padding: 0; margin: 0 }
#waitingMessage { height: 100%; width: 100%; vertical-align: middle; text-align: center;
display: none; }
#[Link] #waitingMessage { display: table; }
#liveAgentSaveButton, #liveAgentEndButton { z-index: 2; }
.liveAgentChatInput {
height: 25px;
border-width: 1px;
border-style: solid;
border-color: #000;
padding: 2px 0 2px 4px;
background: #fff;
display: block;
width: 99%;

46
Implement a Custom Chat Window Using Visualforce Chat Visualforce Components Code Sample

}
.liveAgentSendButton {
display: block;
width: 60px;
height: 31px;
padding: 0 0 3px;
position: absolute;
top: 0;
right: -67px;
}
#liveAgentChatLog {
width: auto;
height: auto;
top: 0px;
position: absolute;
overflow-y: auto;
left: 0;
right: 0;
bottom: 0;
}
</style>
<div style="top: 0; left: 0; right: 0; bottom: 0; position: absolute;">
<liveAgent:clientChat>
<liveAgent:clientChatSaveButton />
<liveAgent:clientChatEndButton />
<div style="top: 25px; left: 5px; right: 5px; bottom: 5px; position: absolute; z-index:
0;">
<liveAgent:clientChatAlertMessage />
<liveAgent:clientChatStatusMessage />
<table id="waitingMessage" cellpadding="0" cellspacing="0">
<tr>
<td>Please wait while you are connected to an available agent.</td>
</tr>
</table>
<div style="top: 0; right: 0; bottom: 41px; left: 0; padding: 0; position: absolute;
word-wrap: break-word; z-index: 0;">
<liveAgent:clientChatLog />
</div>
<div style="position: absolute; height: auto; right: 0; bottom: 0; left: 0; margin-right:
67px;">
<liveagent:clientChatInput /><liveAgent:clientChatSendButton />
</div>
</div>
</liveAgent:clientChat>
</div>
</apex:page>

For an active chat, this code results in the following chat window states:

47
Implement a Custom Chat Window Using Visualforce Chat Visualforce Components Code Sample

Chat Waiting

Chat in Progress

48
Implement a Custom Chat Window Using Visualforce Chat Visualforce Components Code Sample

Chat Ended

49
CHAPTER 7 Use Post-Chat to Wrap Up the Chat
Interaction with Your Customer

Post-chat pages let you share information with customers at the end of a chat session. For example, you can direct your customers to
another Web page after they complete a chat with an agent, or forward them to a survey about their chat experience.

Post-Chat Code Sample

Test and preview how post-chat pages work for your agents and customers using this code sample.

Post-Chat Code Sample

Test and preview how post-chat pages work for your agents and customers using this code sample.

Note: If the post-chat page is hosted on a site that requires an active session, long-running chats can lead to session timeout. If
the customer is on the post-chat page and is redirected to a login page, the post-chat context variables are lost.

Possible Variables Description

requestTime The timestamp when the system received the chat request.

startTime The timestamp when the agent accepted the chat.

deploymentId The ID of the deployment.

buttonId The Id of the button that originated the chat.

chatKey The unique chat key.

lastVisitedPage The last visited page value sent to the agent.

originalReferrer The first page the customer visited containing the deployment
code.

latitude Geo location latitude of the chat visitor.

50
Use Post-Chat to Wrap Up the Chat Interaction with Your Post-Chat Code Sample
Customer

Possible Variables Description

longitude Geo location longitude of the chat visitor.

city Geo location city of the chat visitor.

region Geo location region of the chat visitor.

country Geo location country of the chat visitor.

organization Salesforce organization ID that hosted the chat.

disconnectedBy Reason for ending the chat. Possible values:

• agent - the agent terminated the chat
• client - the chat visitor terminated the chat
• error - the system encountered an error that disconnected
the chat
• clientIdleTimeout - the chat visitor didn’t answer
within the allotted time (must have Idle Timeout configured)
• agentsUnavailable - there are no agents available to
receive the chat or there is no room in the queue

windowLanguage Language of the window as configured in the chat button.

chatDetails A JSON representation of the chat data.

transcript A plain text copy of the transcript.

attachedRecords A list of IDs attached to the chat session in JSON array format.

error Description of any errors that occurred during the chat.

This code sample creates a post-chat page that includes basic information about the chat.
<apex:page showHeader='false'>
<div id='details'>

<h1>Post Chat Page</h1>
<p>

Request Time: <apex:outputText id='c_rt'
value='{!$[Link]}' /><br/>
Start Time: <apex:outputText id='c_st'
value='{!$[Link]}' /><br/>
Deployment Id: <apex:outputText
value='{!$[Link]}' /><br/>
Button Id: <apex:outputText value='{!$[Link]}'
/><br/>
Chat Key: <apex:outputText value='{!$[Link]}'
/><br />
Last Visited Page: <apex:outputText
value='{!$[Link]}' /><br/>

51
Use Post-Chat to Wrap Up the Chat Interaction with Your Post-Chat Code Sample
Customer

Original Referrer: <apex:outputText

value='{!$[Link]}' /><br/>

Latitude: <apex:outputText value='{!$[Link]}'
/><br/>
Longitude: <apex:outputText value='{!$[Link]}'
/><br/>
City: <apex:outputText value='{!$[Link]}' /><br/>
Region: <apex:outputText value='{!$[Link]}' /><br/>

Country: <apex:outputText value='{!$[Link]}'

/><br/>

Organization: <apex:outputText
value='{!$[Link]}' /><br/>
Disconnected By: <apex:outputText
value='{!$[Link]}' /><br/>
Window Language: <apex:outputText
value='{!$[Link]}' /><br/>
Chat Details: <apex:outputText
value='{!$[Link]}' /><br />
Transcript: <apex:outputText value='{!$[Link]}'
/><br/>
Attached Records : <apex:outputText
value='{!$[Link]}' /><br />
Error: <apex:outputText value='{!$[Link]}' /><br
/>
</p>
</div>
<hr/>

<div id='abandoned' style='display: none;'>
We are sorry you decided to leave the chat. Feel free to initiate a new session.

</div>

<script type='text/javascript'>
var requestTime = '{!$[Link]}';
var startTime = '{!$[Link]}';
// when startTime doesn't have a value, it means the chat never started
if (!startTime) {
[Link]('details').[Link] = 'none';
[Link]('abandoned').[Link] = 'block';
}
</script>

</apex:page>

This code results in the following post-chat page for the agent:

52
Use Post-Chat to Wrap Up the Chat Interaction with Your Post-Chat Code Sample
Customer

This message shows if the chat is abandoned:

53
CHAPTER 8 Set Up Direct-to-Agent Chat Routing with
the Deployment APIs

You can route chats that originate from a specific button or invite to a specific agent by editing a few parameters in the Chat Deployment
API. You can set chats to fallback to another button or queue if the specified agent isn’t available.

Direct-to-Agent Routing with the Deployment APIs

You can set up direct-to-agent routing that lets you to route chats from a specific button to a single agent.
Fallback Routing in Pre-Chat Forms
Set fallback routing rules in pre-chat forms in case the agent specified for direct-to-agent routing isn’t available when a chat is
received.

Direct-to-Agent Routing with the Deployment APIs

You can set up direct-to-agent routing that lets you to route chats from a specific button to a single agent.

Direct-to-Agent Routing Code Sample

Implement direct-to-agent routing using the Deployment API.

Direct-to-Agent Routing Code Sample

Implement direct-to-agent routing using the Deployment API.

54
Set Up Direct-to-Agent Chat Routing with the Deployment Direct-to-Agent Routing Code Sample
APIs

The following code sample shows you how to set up direct-to-agent so your agents can send visitors a “Chat with Me” link.
<apex:page standardController="User" showHeader="false">
<h1>Direct-to-Agent Chat with {![Link]}</h1>

<div id="dta_online" style="display: none;">

<a href="javascript://Chat" onclick="[Link]('573D01234567890',
'{!left([Link],15)}')">Chat with {![Link]}!</a>

</div>

<div id="button_online" style="display: none;">Sorry, {![Link]} is not available.
If you’d like, you can
<a href="javascript://Chat" onclick="[Link]('573D01234567890')">start
a chat with another agent</a>.
</div>

<div id="button_offline" style="display: none;">Sorry, all agents (including
{![Link]}) appear to be unavailable.</div>

</div>

<script type='text/javascript'
src='[Link]

[Link]('{!left([Link],15)}', [Link]('dta_offline'));

/* The following calls pass the button ID as the first argument and show whether
any agents are available to handle chats from the button. */
[Link]('573D01234567890', [Link]('button_online'));

[Link]('573D01234567890', [Link]('button_offline'));

/* The live agent pool and these IDs are specific to your org, so replace these with

55
Set Up Direct-to-Agent Chat Routing with the Deployment Fallback Routing in Pre-Chat Forms
APIs

your own. */
[Link]('[Link] '572D01234567890',
'00DD01234567890');
</script>
</apex:page>

When you use this code sample with your org and call it ChatWithMe, agents can create a link that sends a chat request directly to them.
[Link]
You can make it even easier for agents to send a “chat with me” link by creating a Quick Text message that any agent can use:
[Link]
The User ID spot in the link is automatically filled with the User ID of any agent who uses the Quick Text.

Fallback Routing in Pre-Chat Forms

Set fallback routing rules in pre-chat forms in case the agent specified for direct-to-agent routing isn’t available when a chat is received.

Important: The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then.
During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid
service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the
chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement
in Help.
What if you set up direct-to-agent routing, but the agent you specified to receive the chats isn’t available? If the agent is offline, those
chats might be lost.
Luckily, if your organization uses pre-chat forms to gather customer information, you can set up fallback routing options for a button
that uses direct-to-agent routing.
This code sample demonstrates how to route chats using another button’s default routing rules if the agent assigned to that button
isn’t available. Let’s take a look at this section of code:
<h1>Pre-chat Form</h1>
<form method='post' id='prechatForm'>
Name: <input type='text' name='[Link]' id='prechat_field' /><br />

Email Address: <input type='text' name='[Link]:Email' /><br />

Department: <select name="[Link]">

<option value="573D01234567890">Route through button 573D01234567890</option>
<option value="005D01234567890">Route to agent 005D01234567890</option>
<option value="005D01234567890_573D01234567890">Route to agent 005D01234567890

with Fallback to button 573D01234567890</option>

In this section, we specify that chats originating from the button should be routed to an agent with agent ID 005xx000001Sv1m. If that
agent isn’t available, incoming chats are routed based on the default routing rules for the button with button ID 573xx0000000001.

Fallback Routing Code Sample

Implement fallback routing rules in pre-chat forms so visitors can chat with another agent with the specified agent isn’t available.

56
Set Up Direct-to-Agent Chat Routing with the Deployment Fallback Routing Code Sample
APIs

Fallback Routing Code Sample

Implement fallback routing rules in pre-chat forms so visitors can chat with another agent with the specified agent isn’t available.

Important: The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then.
During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid
service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the
chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement
in Help.
This sample creates a pre-chat form with fallback routing rules enabled. This form:
• Requests a visitor’s name and email address.
• Displays that information in the chat log and in the chat request window.
• Displays either a new or existing Contact record with the customer’s information in a new tab in the Salesforce console. The customer’s
name and email address are used to find an existing record. If no existing record is found, a new record is created and populated
with the customer’s information.
• Displays a drop-down list that lets visitors choose a different Chat button through which to route their chat request.
• Routes chats directly to a specific agent, or, if that agent is unavailable, routes those chats based on the button’s default routing
rules.
<apex:page showHeader="false">

<script type="text/javascript">

(function() {
function handlePageLoad() {
var endpointMatcher = new RegExp("[\\?\\&]endpoint=([^&#]*)");
var domainMatcher = new
RegExp("^(https?:\\/\\/(.+?\\.)?(salesforce|salesforceliveagent)\\.com(\\/[A-Za-z0-9\\-\\._~:\\/\\?#\[\\]@!$&'\$\$\*\\+,;\\=]*)?)");

var endpointAttr = [Link]([Link])[1];

// if the endpoint domain is valid
if ([Link](decodeURIComponent(endpointAttr))) {
[Link]('prechatForm').setAttribute('action',
decodeURIComponent([Link]("javascript:", "")));
} else {
// invalid endpoint domain, set the action to empty
[Link]("invalid domain: " + endpointAttr);
[Link]('prechatForm').setAttribute('action', "");
}
}
if ([Link]) {
[Link]('load', handlePageLoad, false);
} else {
[Link]('onload', handlePageLoad, false);
}
})();
</script>

57
Set Up Direct-to-Agent Chat Routing with the Deployment Fallback Routing Code Sample
APIs

<form method='post' id='prechatForm'>

Name: <input type='text' name='[Link]' id='prechat_field' /><br />

Email Address: <input type='text' name='[Link]:Email' /><br />

with Fallback to button 573D01234567890</option>

</select><br />
<input type='submit' value='Request Chat' id='prechat_submit'/>
</form>

</apex:page>

Live Agent Chat Customization Guide
No ratings yet
Live Agent Chat Customization Guide
60 pages
Live Agent Developer Guide
No ratings yet
Live Agent Developer Guide
54 pages
Chat Administrator
No ratings yet
Chat Administrator
34 pages
Chat Rest
No ratings yet
Chat Rest
65 pages
Setting Up Embedded Chat in Salesforce
No ratings yet
Setting Up Embedded Chat in Salesforce
42 pages
Learn Sales Force Basics
No ratings yet
Learn Sales Force Basics
31 pages
Laravel Package Development - Tinashe Musonza - 2023 - Anna's Archive
No ratings yet
Laravel Package Development - Tinashe Musonza - 2023 - Anna's Archive
172 pages
Rocket.Chat Developer Guide Overview
No ratings yet
Rocket.Chat Developer Guide Overview
4 pages
R Package for Telegram Bot Development
100% (1)
R Package for Telegram Bot Development
56 pages
Zammad User Management Guide
100% (1)
Zammad User Management Guide
260 pages
Chat Support Agents
No ratings yet
Chat Support Agents
26 pages
Streaming API
No ratings yet
Streaming API
82 pages
Django Private Chat Documentation 0.3.0
No ratings yet
Django Private Chat Documentation 0.3.0
55 pages
Chat Application Development for Developers
No ratings yet
Chat Application Development for Developers
103 pages
Chat Support Supervisors
No ratings yet
Chat Support Supervisors
6 pages
Enabling Profile-Based Chatter Access
100% (1)
Enabling Profile-Based Chatter Access
21 pages
Build A Chat System With Firebase
No ratings yet
Build A Chat System With Firebase
183 pages
TMF683 Party Interaction Userguide
No ratings yet
TMF683 Party Interaction Userguide
73 pages
SFDX Dev
No ratings yet
SFDX Dev
112 pages
Jasmin SMS Gateway Documentation 0.10.13
No ratings yet
Jasmin SMS Gateway Documentation 0.10.13
125 pages
Zammad Admin Documentation
No ratings yet
Zammad Admin Documentation
211 pages
Elgg
No ratings yet
Elgg
265 pages
Pyro Gram
No ratings yet
Pyro Gram
505 pages
Salesforce Field Names Reference
No ratings yet
Salesforce Field Names Reference
118 pages
Salesforce Winter '17 Field Reference Guide
No ratings yet
Salesforce Winter '17 Field Reference Guide
119 pages
Salesforce Field Names Reference
No ratings yet
Salesforce Field Names Reference
118 pages
Salesforce Packaging Guide
No ratings yet
Salesforce Packaging Guide
257 pages
Ejabberd User Guide
100% (2)
Ejabberd User Guide
102 pages
Build A Chat System With Firebase
No ratings yet
Build A Chat System With Firebase
178 pages
Metadata A Pi Developer Guide
No ratings yet
Metadata A Pi Developer Guide
2,581 pages
Twilio API for WhatsApp Integration Guide
100% (1)
Twilio API for WhatsApp Integration Guide
6 pages
Ejabberd 2.0.0 Installation and Operation Guide: February 21, 2008
No ratings yet
Ejabberd 2.0.0 Installation and Operation Guide: February 21, 2008
98 pages
Jasmin SMS Gateway Documentation 0.10.11s
No ratings yet
Jasmin SMS Gateway Documentation 0.10.11s
117 pages
Read The Docs Documentation: Release 1.0
No ratings yet
Read The Docs Documentation: Release 1.0
182 pages
Jasmin SMS Gateway Documentation 0.10.11s
No ratings yet
Jasmin SMS Gateway Documentation 0.10.11s
117 pages
Collaborate With Everyone: Salesforce, Spring '16
No ratings yet
Collaborate With Everyone: Salesforce, Spring '16
200 pages
Develop Web Client Extensions Guide
No ratings yet
Develop Web Client Extensions Guide
284 pages
Firebase by Ta
No ratings yet
Firebase by Ta
60 pages
OpenScape Contact Center V10 R2 Guide
No ratings yet
OpenScape Contact Center V10 R2 Guide
50 pages
Firebase Admin SDK For PHP
No ratings yet
Firebase Admin SDK For PHP
60 pages
Firebase Admin SDK For PHP
No ratings yet
Firebase Admin SDK For PHP
62 pages
Elgg Documentation: Release Master
No ratings yet
Elgg Documentation: Release Master
322 pages
OpenScape Contact Center Enterprise V11 R1 OpenMedia Connectors Deployment Guide Administrator Documentation Issue 5
No ratings yet
OpenScape Contact Center Enterprise V11 R1 OpenMedia Connectors Deployment Guide Administrator Documentation Issue 5
53 pages
Salesforce Collaborate With Everyone 1-26-2025
No ratings yet
Salesforce Collaborate With Everyone 1-26-2025
426 pages
Salesforce Packaging Guide
No ratings yet
Salesforce Packaging Guide
377 pages
Rejoining WhatsApp Groups Explained
No ratings yet
Rejoining WhatsApp Groups Explained
504 pages
Telethon API Documentation Overview
No ratings yet
Telethon API Documentation Overview
290 pages
Api Cti
No ratings yet
Api Cti
119 pages
WCFM Live Chat Module Setup Guide
No ratings yet
WCFM Live Chat Module Setup Guide
21 pages
Open CTI Developer Guide Overview
No ratings yet
Open CTI Developer Guide Overview
119 pages
Chatter Administrator's Workbook: Version 2: Winter '13
No ratings yet
Chatter Administrator's Workbook: Version 2: Winter '13
29 pages
Java Chat Server Tutorial
No ratings yet
Java Chat Server Tutorial
5 pages
Real-Time Chat App with Firebase
No ratings yet
Real-Time Chat App with Firebase
18 pages
PJSUA2 API Documentation Overview
No ratings yet
PJSUA2 API Documentation Overview
271 pages
OpenScape Contact Center Enterprise V11 OpenMedia Connectors Deployment Guide Administrator Documentation Issue 3
No ratings yet
OpenScape Contact Center Enterprise V11 OpenMedia Connectors Deployment Guide Administrator Documentation Issue 3
61 pages
The WhatsApp Business Platform With Twilio - Twilio
No ratings yet
The WhatsApp Business Platform With Twilio - Twilio
1 page
CloudAPIGuide BusinessFlows
No ratings yet
CloudAPIGuide BusinessFlows
172 pages
CustomWidgetDevGuide en
No ratings yet
CustomWidgetDevGuide en
78 pages
API Open Cti
No ratings yet
API Open Cti
111 pages
Case Feed Dev Guide
No ratings yet
Case Feed Dev Guide
44 pages
Sos Administrators
No ratings yet
Sos Administrators
12 pages
Salesforce Certified Marketing Cloud Developer Exam - ForceDigest - 2023 - Anna's Archive
No ratings yet
Salesforce Certified Marketing Cloud Developer Exam - ForceDigest - 2023 - Anna's Archive
136 pages
Salesforce Certified Advanced Administrator Exam - ForceDigest - 2023 - Anna's Archive
No ratings yet
Salesforce Certified Advanced Administrator Exam - ForceDigest - 2023 - Anna's Archive
133 pages
Program and Case Management 8-18-2025
No ratings yet
Program and Case Management 8-18-2025
94 pages
Salesforce Certified Integration Architect Exam - ForceDigest - 2023 - Anna's Archive
No ratings yet
Salesforce Certified Integration Architect Exam - ForceDigest - 2023 - Anna's Archive
120 pages
Cartoon History of The United States (Cartoon History of The - Larry Gonick HarperCollins Publishers - 1st HarperPerennial Ed - , New York, N - Y, New
No ratings yet
Cartoon History of The United States (Cartoon History of The - Larry Gonick HarperCollins Publishers - 1st HarperPerennial Ed - , New York, N - Y, New
404 pages
A FFT
No ratings yet
A FFT
17 pages
The CARTOON GUIDE To The COMPUTER - Larry Gonick, Mark Wheelis - 1st HarperPerennial Ed, New York, 1991
100% (1)
The CARTOON GUIDE To The COMPUTER - Larry Gonick, Mark Wheelis - 1st HarperPerennial Ed, New York, 1991
260 pages
C Automata Dynprog
No ratings yet
C Automata Dynprog
7 pages
Wireless LAN Controller Configuration Guide
No ratings yet
Wireless LAN Controller Configuration Guide
56 pages
Introduction to Computer Forensics
No ratings yet
Introduction to Computer Forensics
16 pages
CSE B.Tech Curriculum 2023 Overview
No ratings yet
CSE B.Tech Curriculum 2023 Overview
256 pages
Setting Up RAID 0 with mdadm in Linux
No ratings yet
Setting Up RAID 0 with mdadm in Linux
13 pages
Web Technology Exam Paper 2023
No ratings yet
Web Technology Exam Paper 2023
3 pages
Kiran
No ratings yet
Kiran
4 pages
Virtual Lab Setup for Ethical Hacking
No ratings yet
Virtual Lab Setup for Ethical Hacking
12 pages
Apple's iPad: Market Transformation Insights
No ratings yet
Apple's iPad: Market Transformation Insights
8 pages
Full Text of Tara by Mahesh Dattani
0% (1)
Full Text of Tara by Mahesh Dattani
18 pages
CSC248 Java Sorting and Searching Test
No ratings yet
CSC248 Java Sorting and Searching Test
4 pages
Chords and Lyrics for "Almost" by Tamia
No ratings yet
Chords and Lyrics for "Almost" by Tamia
1 page
Deploying ASP.NET Core with Docker
No ratings yet
Deploying ASP.NET Core with Docker
2 pages
Memory Test System Training Overview
No ratings yet
Memory Test System Training Overview
141 pages
BA49182 Datasheet Overview
No ratings yet
BA49182 Datasheet Overview
3 pages
Cloud-Based Smart Water Meter System
No ratings yet
Cloud-Based Smart Water Meter System
3 pages
App Resizing and Surface Management Logs
No ratings yet
App Resizing and Surface Management Logs
17 pages
Matlab Residue Command Explained
No ratings yet
Matlab Residue Command Explained
6 pages
Online Building Plan Approval Process
No ratings yet
Online Building Plan Approval Process
6 pages
Nature and Purposes of Online Platforms
50% (2)
Nature and Purposes of Online Platforms
26 pages
Dairy Firm Transportation Cost Analysis
No ratings yet
Dairy Firm Transportation Cost Analysis
11 pages
Place Value and Rounding Exercises
No ratings yet
Place Value and Rounding Exercises
4 pages
Umbrella Module Error Report
No ratings yet
Umbrella Module Error Report
4 pages
UAV Thermal Imaging for Survivor Detection
No ratings yet
UAV Thermal Imaging for Survivor Detection
11 pages
ORACLE 10g Installation Guide - Update - v1.2
No ratings yet
ORACLE 10g Installation Guide - Update - v1.2
23 pages
Enhancing E-Learning with Data Analytics
No ratings yet
Enhancing E-Learning with Data Analytics
4 pages
Software Lab DA-4: UML Diagrams Overview
No ratings yet
Software Lab DA-4: UML Diagrams Overview
17 pages
Synology RS4021xs+ RackStation Overview
No ratings yet
Synology RS4021xs+ RackStation Overview
16 pages
AI and Evolutionary Algorithms in Smart Grids
No ratings yet
AI and Evolutionary Algorithms in Smart Grids
8 pages
Control Structures in Programming Basics
No ratings yet
Control Structures in Programming Basics
26 pages
150+ Excel Keyboard Shortcuts Guide
No ratings yet
150+ Excel Keyboard Shortcuts Guide
17 pages