Live Agent Developer's Guide Dev
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 60
| Download | |
| Open PDF In Browser | View PDF |
Live Agent Developer's Guide
Version 39.0, Spring ’17
@salesforcedocs
Last updated: March 29, 2017
© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Customize Chat Buttons with the Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
showWhenOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
showWhenOffline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
addButtonEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
startChat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
startChatWithWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Corresponding Calls for Chat Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Find and Create Records Automatically with the Deployment APIs . . . . . . . . . . . . . . . . . . . . 16
addCustomDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
findOrCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
setName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Search for Knowledge Articles with the Deployment APIs . . . . . . . . . . . . . . . . . . . . . . . 20
Find and Create Records Deployment API Code Sample . . . . . . . . . . . . . . . . . . . . . . . 21
Customize Automated Chat Invitations with the Deployment APIs . . . . . . . . . . . . . . . . . . . . 22
setCustomVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
rejectChat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
addButtonEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Automated Chat Invitation Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Deployment API Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 5: Use Pre-Chat to Gather Visitor Information and Set Context for the
Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Find and Create Records Automatically with the Pre-Chat APIs . . . . . . . . . . . . . . . . . . . . . . . 31
findOrCreate.map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
findOrCreate.saveToTranscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
findOrCreate.showOnCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
findOrCreate.linkToEntity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Contents
findOrCreate.displayToAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Find and Create Records Pre-Chat API Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . 38
Access Chat Details with the Pre-Chat APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
preChatInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Pre-Chat Form Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Chapter 6: Implement a Custom Chat Window Using Visualforce . . . . . . . . . . . . . . . 44
Live Agent Visualforce Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Live Agent Visualforce Components Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Chapter 7: Use Post-Chat to Wrap Up the Chat Interaction with Your Customer . . . . . 49
Post-Chat Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Chapter 8: Set Up Direct-to-Agent Chat Routing with the Deployment APIs . . . . . . . . 53
Direct-to-Agent Routing with the Deployment APIs .
Direct-to-Agent Routing Code Sample . . . . .
Fallback Routing in Pre-Chat Forms . . . . . . . . . . .
Fallback Routing Code Sample . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
53
53
55
55
CHAPTER 1
About This Guide
Customize Live Agent to fit your company’s needs. This guide provides several examples to help you understand and create customized
chat windows, buttons, forms, and pages.
Live Agent lets service organizations connect with customers or website visitors in real time through a Web-based, text-only live chat.
You can customize Live Agent 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 Live Agent components through Salesforce settings. For more information, see “Customize
Your Live Agent Implementation” in the Salesforce help.
1
CHAPTER 2 Prerequisites
Before you customize Live Agent, make sure:
• Live Agent is enabled in your organization.
• Your administrator has granted you a Live Agent feature license. Although you can customize the product without a feature license,
having one will allow you to access and test your customizations.
• You’ve created a Force.com site and uploaded images as static resources for your chat buttons and windows. If you plan to customize
Live Agent without using a Force.com site, skip this step.
Note: When using a Force.com site for Live Agent 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.
SEE ALSO:
Creating and Editing Force.com Sites
2
CHAPTER 3 API Versions
Different methods and parameters are available in different versions of Live Agent’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:
https://hostname.salesforceliveagent.com/content/g/deployment.js
Winter ’14 supports version 29.0 of the Deployment API. The URL for API version 29.0 contains the version number:
https://hostname.salesforceliveagent.com/content/g/js/29.0/deployment.js
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:
https://hostname.salesforceliveagent.com/content/g/js/29.0/prechat.js
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 Live Agent Deployment API.
A deployment is a place on your company’s website that’s enabled for Live Agent. A deployment consists of a few lines of JavaScript
that you add to a Web page. Your organization can have a single Live Agent 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 Live Agent 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 Live Agent on your website. Each deployment includes a chat window, which visitors use to chat with
support agents.
You can customize your Live Agent 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.
4
Customize Deployments with the Deployment APIs
Log Deployment Activity with the Deployment APIs
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 Force.com 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 Live Agent. For best performance, paste the
code right before the closing body tag.
Example: For more information on creating a deployment, see “Create Live Agent Deployments.”
Log Deployment Activity with the Deployment APIs
Log the activity that occurs in a particular deployment.
Logging lets you store information about the activity that occurs within a customer’s Web browser as they chat with an agent through
a particular deployment. This is particularly helpful when you’re implementing automated invitations and you want to test or troubleshoot
your sending rules. You can add these methods as an additional script within the code that’s automatically generated when you create
a deployment.
Use the following deployment methods to enable logging on a particular deployment.
enableLogging
Use the enableLogging deployment method to enable logging on a particular deployment. Available in API versions 28.0 and
later.
enableLogging
Use the enableLogging deployment method to enable logging on a particular deployment. Available in API versions 28.0 and
later.
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
liveagent.enableLogging();
Parameters
None
5
Customize Deployments with the Deployment APIs
enableLogging
Messages for Logged Events
Message
Triggered
Meaning
System initialized. Waiting for the DOM to
be ready.
When liveagent.init() is called, usually at
page load
Live Agent endpoint URL, org ID and
deployment ID have been set, now waiting
for DOM to be ready before continuing.
No available event model. Exiting.
During liveagent.init(), 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.”
Ping rate set to {Rate}ms
As a response to the first ping
Indicates how frequently (in milliseconds)
the page will ping the Live Agent 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 Live Agent server, meaning no
errors or disconnects have occurred.
Disconnecting from Live Agent
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 Live Agent for this page
load (i.e., they will need to refresh).
6
Customize Deployments with the Deployment APIs
enableLogging
Message
Triggered
Meaning
Received updated LiveAgent server url:
{URL}! Consider updating this site's
deployment code.
When an org has moved to a new core
instance
The Live Agent instance specified in the
deployment code is no longer valid for this
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
Evaluation
Rule evaluation has been triggered
Evaluation of the filter logic for the given
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
evaulated.
Evaluating StandardInviteRule
When a standard rule is being evaluated
Standard rules are "Number of Page Views"
and "URL Match." They are part of the
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
7
"Custom Variable" rules allow variable
names to be specified which will be
compared against upon evaluating these
Customize Deployments with the Deployment APIs
Message
enableLogging
Triggered
Meaning
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
missing custom variable
When a custom rule is being evaluated
A "Custom Variable" rule was set up, but the
"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
Value}
When a rule with a "not equal to"
comparator is being evaluated
A rule is being evaluated by comparing that
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
{To Value} != -1
When a rule with a "contains" comparator
is being evaluated
Does Not Contain - Evaluate: {From Value} When a rule with a "does not contain"
indexOf {To Value} == -1
comparator is being evaluated
Less Than - Evaluate: {From Value} < {To
Value}
A rule is being evaluated by comparing that
the first value contains the second value.
A rule is being evaluated by comparing that
the first value does not contain the second
value.
When a rule with a "less than" comparator A rule is being evaluated by comparing that
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"
Value}
comparator is being evaluated
A rule is being evaluated by comparing that
the first value is greater than the second
value.
Less or Equal - Evaluate: {From Value} <=
{To Value}
A rule is being evaluated by comparing that
the first value is less than or equal to the
second value.
When a rule with a "less or equal"
comparator is being evaluated
Greater or Equal - Evaluate: {From Value} >= When a rule with a "greater or equal"
{To Value}
comparator is being evaluated
A rule is being evaluated by comparing that
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
an "AND" clause
When multiple rules are used, this indicates
when the criteria of a pair of rules must both
be "true."
Group Start: Evaluating Or Node
When two rules are being evaluated with
an "OR" clause
When multiple rules are used, this indicates
when the criteria of a pair of rules must be
"true" for one of them.
8
Customize Deployments with the Deployment APIs
Customize Your Chat Window with the Deployment APIs
Message
Triggered
Meaning
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
the criteria
If the criteria for a timer-based rule is not
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.
Use the following deployment methods to customize the height and width of the chat window. You can add either of these methods
as additional scripts within the code that’s automatically generated when you create a deployment.
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.
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
window.
Available in API versions 28.0 and later.
setChatWindowWidth
Use the setChatWindowWidth method to customize the width of your chat window.
9
Customize Deployments with the Deployment APIs
Customize Chat Buttons with the Deployment APIs
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
window.
Available in API versions 28.0 and later.
Customize Chat Buttons with the Deployment APIs
Customize your chat buttons and set how chats start for your customers.
Each chat button includes code that you place on your website to let customers start a chat. Live Agent automatically handles the
button's availability based on your agents’ availability and your org's settings. It also handles starting the chat request from the button.
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.
SEE ALSO:
Chat Routing Options
showWhenOnline
Use the showWhenOnline method to specify what customers see when a particular button is online.
10
Customize Deployments with the Deployment APIs
showWhenOffline
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.
element
Object
The element to be displayed when the
specified button is online.
Available in API versions 28.0 and later.
userId
String
The ID of the agent to associate with the
button. The element object is displayed
when that agent is available.
Available in API versions 29.0 and later.
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.
liveagent.showWhenOnline('005xx000001Sv1m',
document.getElementById('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.
liveagent.showWhenOnline('573xx0000000006',
document.getElementById('liveagent_button_online_573xx0000000006_USER1'), '005xx000001Sv1m');
showWhenOffline
Use the showWhenOffline method to specify what customers see when a particular button is offline.
11
Customize Deployments with the Deployment APIs
addButtonEventHandler
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.
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 no
agents are available to chat.
element
Object
The element to display when the specified
button is offline.
Available in API versions 28.0 and later.
userId
String
The ID of the agent to associate with the
button. The element object is displayed
when that agent is unavailable.
Available in API versions 29.0 and later.
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.
liveagent.showWhenOffline('005xx000001Sv1m',
document.getElementById('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.
liveagent.showWhenOffline('573xx0000000006',
document.getElementById('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.
12
Customize Deployments with the Deployment APIs
addButtonEventHandler
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 Live Agent 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)
Parameters
Name
Type
Description
Available Versions
buttonId
String
The ID of the chat button for which to define
the behavior when certain events occur.
Available in API versions 28.0 and later.
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
13.
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.
13
Customize Deployments with the Deployment APIs
Function
startChat
Event Type
Syntax
Description
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).
Syntax
void startChat(String buttonId, (optional) String userId, (optional) Boolean fallback)
Parameters
Name
Type
Description
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.com user ID of the agent to
Available in API versions 29.0 and later.
whom to directly route chats from the button.
(Optional)
Specifies whether to fall back to the button’s
routing rules (true) or not (false) if the
agent with the specified sfdcUserId is
unavailable.
fallback
Boolean
Available Versions
Available in API versions 29.0 and later.
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.
14
Customize Deployments with the Deployment APIs
Corresponding Calls for Chat Buttons
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
TheSalesforce user ID of the agent to whom to Available in API versions 29.0 and later.
directly route chats from the button.
(Optional)
Specifies whether to fall back to the button’s
routing rules (true) or not (false) if the
agent with the specified sfdcUserId is
unavailable.
Boolean
fallback
Available in API versions 29.0 and later.
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
startChatWithWindow)
Call to showWhenOnline
(or showWhenOffline)
Button
startChat(String
buttonId)
showWhenOnline(String addButtonEventHandler(
String buttonId,
buttonId, Object
element, (optional) Function callback)
String userId)
Agent (no fallback)
startChat(String
buttonId, String
userId, false)
showWhenOnline(String addButtonEventHandler(
String userId,
userId, Object
Function callback)
element)
Agent (fallback to button)
startChat(String
buttonId, String
userId, true)
showWhenOnline(String Use multiple handlers.
buttonId, Object
element, String
userId)
15
Call to
addButtonEventHandler
Customize Deployments with the Deployment APIs
Find and Create Records Automatically with the Deployment
APIs
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.
You can add any of these methods as additional scripts within the code that’s automatically generated when you create a deployment.
addCustomDetail
Use the addCustomDetail method to add custom details for each chat visitor.
findOrCreate
Use the findOrCreate method to find existing records or create new ones based on certain criteria.
setName
Use the setName method to set the visitor name displayed in the Live Agent 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 Live Agent deployments using this code sample.
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
example, "Name".
Available in API versions 28.0 and later.
value
String
The value of the custom detail—for
example, "John Doe".
Available in API versions 28.0 and later.
(Optional)
Boolean
Specifies whether to display the custom
Available in API versions 29.0 and later.
details that customers provide in a pre-chat
form to the agent (true) or not (false).
displayToAgent
16
Customize Deployments with the Deployment APIs
findOrCreate
findOrCreate
Use the findOrCreate method to find existing records or create new ones based on certain criteria.
Usage
Finds or creates a record of the specified type when an agent accepts a chat request.
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.
Available in API versions 29.0 and later.
Syntax
liveagent.findOrCreate(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.
findOrCreate.map
Use the findOrCreate.map method to search for or create records that contain specific customer details.
findOrCreate.saveToTranscript
Use the findOrCreate.saveToTranscript method to save the record you find or create to the chat transcript associated
with the chat.
findOrCreate.showOnCreate
Use the findOrCreate.showOnCreate method to automatically open the record you create in a subtab in the Salesforce
console.
findOrCreate.linkToEntity
Use the findOrCreate.linkToEntity method to link the record you found or created to another record type.
findOrCreate.map
Use the findOrCreate.map 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 findOrCreate.map 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.
17
Customize Deployments with the Deployment APIs
findOrCreate
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.
Available in API versions 29.0 and later.
Syntax
liveagent.findOrCreate(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
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
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).
Available in API versions 29.0 and later.
Available in API versions 29.0 and later.
findOrCreate.saveToTranscript
Use the findOrCreate.saveToTranscript 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 findOrCreate.map Deployment API methods to
the chat transcript associated with the chat.
Available in API versions 29.0 and later.
Syntax
liveagent.findOrCreate(String EntityName).saveToTranscript(String TranscriptFieldName)
18
Customize Deployments with the Deployment APIs
findOrCreate
Parameters
Name
Type
Description
TranscriptFieldName String
Available Versions
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.
findOrCreate.showOnCreate
Use the findOrCreate.showOnCreate 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 findOrCreate.map Deployment API methods automatically in
a subtab in the to the Salesforce console.
Available in API versions 29.0 and later.
Syntax
liveagent.findOrCreate(String EntityName).showOnCreate()
findOrCreate.linkToEntity
Use the findOrCreate.linkToEntity 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 findOrCreate.map 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 findOrCreate.linkToEntity method.
Available in API versions 29.0 and later.
Syntax
liveagent.findOrCreate(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
record you found or created.
Available in API versions 29.0 and later.
19
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 Live Agent 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 AgentSupervisor 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 Live Agent 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.
addCustomDetail.doKnowledgeSearch
Use the knowledgeSearch method to automatically search for Knowledge articles based on criteria in a pre-chat form.
addCustomDetail.doKnowledgeSearch
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.
20
Customize Deployments with the Deployment APIs
Find and Create Records Deployment API Code Sample
Syntax
liveagent.addCustomDetail(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 Live Agent 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
• findOrCreate.map
• findOrCreate.saveToTranscript
• findOrCreate.linkToEntity
• findOrCreate.showOnCreate
Customize Automated Chat Invitations with the Deployment APIs
Customize automated chat invitations that appear to customers on your website.
Use the following deployment methods to customize your automated chat invitations.
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)
Parameters
Name
Type
Description
Available Versions
variableName
String
The name of the customized criteria for your
custom sending rule.
Available in API versions 28.0 and later.
22
Customize Deployments with the Deployment APIs
rejectChat
Name
Type
Description
Available Versions
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
chats.
Available in API versions 28.0 and later.
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.
• Online agents have the status Away.
• Online agents are at capacity (set with Live Agent Configurations, or Presence Configurations with Omni-Channel).
• Online agents are using Omni-Channel and are only available for other service channels.
23
Customize Deployments with the Deployment APIs
addButtonEventHandler
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 24.
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
customer accepts
the invitation. This
event type is only
available for
24
Customize Deployments with the Deployment APIs
Function
Event Type
Automated Chat Invitation Code Sample
Syntax
Description
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.
26
Customize Deployments with the Deployment APIs
Deployment API Code Sample
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.
This code sample creates a chat window that uses the following Deployment API methods:
• startChat
• showWhenOnline
• showWhenOffline
• addCustomDetail
• setName
• map
• setChatWindowWidth
• setChatWindowHeight
• doKnowledgeSearch
Welcome to Support
Thank you for your interest.
Chat Now
27
Customize Deployments with the Deployment APIs
Deployment API Code Sample
This code results in the following view for agents using the Console.
The name of the customer (Jane Doe for this example) appears in the Console from setName (1). When you call
addCustomDetail.doKnowledgeSearch, the search automatically appears in the Knowledge widget (2).
When the agent receives a chat, the set Custom Details appear in a hover window.
29
Customize Deployments with the Deployment APIs
Deployment API Code Sample
30
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.
A pre-chat form can gather information, such as a customer's name, email address, and reason for contacting customer support. This
information can help direct chat requests more efficiently and reduce the time agents spend collecting the information themselves. You
can also use this information to customize the customer's experience while they chat with the agent, such as including their first name
in the chat window.
You can create a Visualforce page to host your pre-chat form, or you can develop the form on your own. The information in this guide
focuses on using Visualforce.
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.
Pre-Chat Form Code Sample
Test and preview how pre-chat forms can work for your agents and customers.
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.
findOrCreate.map
Use the findOrCreate.map method to search for or create records that contain specific customer details.
findOrCreate.saveToTranscript
Use the findOrCreate.saveToTranscript method to find or create a record and save it to the chat transcript associated
with the chat.
findOrCreate.showOnCreate
Use the findOrCreate.showOnCreate method to find or create a record and automatically open it in a subtab in the
Salesforce console.
findOrCreate.linkToEntity
Use the findOrCreate.linkToEntity method to link the record you found or created to another record type.
findOrCreate.displayToAgent
Use the findOrCreate.displayToAgent 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.
findOrCreate.map
Use the findOrCreate.map method to search for or create records that contain specific customer details.
31
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
findOrCreate.map
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 findOrCreate.map 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
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
EntityName to which to map the
corresponding custom detail value
Available in API versions 29.0 and later.
detailName
String
The value of the custom detail to map to the
corresponding field fieldName
Available in API versions 29.0 and later.
findOrCreate.map.doFind
Use the findOrCreate.map.doFind method to specify which fields to search against existing customer records when a
customer completes a pre-chat form.
findOrCreate.map.isExactMatch
Use the findOrCreate.map.isExactMatch method to specify whether a field value must exactly match the field value
in an existing record when you conduct a search with the findOrCreate.map method.
findOrCreate.map.doCreate
Use the findOrCreate.map.doCreate method to specify which fields in findOrCreate.map method to use to create
a new record if an existing record isn’t found.
findOrCreate.map.doFind
Use the findOrCreate.map.doFind method to specify which fields to search against existing customer records when a customer
completes a pre-chat form.
32
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
findOrCreate.map
Usage
Specifies which fields in your findOrCreate.map 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
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
existing records.
Available in API versions 29.0 and later.
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.
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.
findOrCreate.map.isExactMatch
Use the findOrCreate.map.isExactMatch method to specify whether a field value must exactly match the field value in an
existing record when you conduct a search with the findOrCreate.map method.
33
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
findOrCreate.map
Usage
Specifies which fields in your findOrCreate.map 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
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
existing records.
Available in API versions 29.0 and later.
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.
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.
findOrCreate.map.doCreate
Use the findOrCreate.map.doCreate method to specify which fields in findOrCreate.map method to use to create a
new record if an existing record isn’t found.
Usage
Specifies which fields in your findOrCreate.map 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.
34
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
findOrCreate.saveToTranscript
Syntax
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
records.
Available in API versions 29.0 and later.
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.
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.
findOrCreate.saveToTranscript
Use the findOrCreate.saveToTranscript 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 findOrCreate.map.doCreate or findOrCreate.map.doFind
Pre-Chat API methods to the chat transcript associated with the chat when the chat ends.
Available in API versions 29.0 and later.
35
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
findOrCreate.showOnCreate
Syntax
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.
findOrCreate.showOnCreate
Use the findOrCreate.showOnCreate 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 findOrCreate.map.doCreate and findOrCreate.map.doFind Pre-Chat API
methods automatically in a subtab in the to the Salesforce console.
Available in API versions 29.0 and later.
Syntax
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.
show
Boolean
Specifies whether to display the record you
created in a subtab in the Salesforce console
(true) or not (false).
36
Available in API versions 29.0 and later.
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
findOrCreate.linkToEntity
findOrCreate.linkToEntity
Use the findOrCreate.linkToEntity method to link the record you found or created to another record type.
Usage
Links the record you’ve found or created using the findOrCreate.map.doFind and findOrCreate.map.doCreate
methods to another record of a different record type that you created using a separate findOrCreate.map API call. For example,
you can link a case record you found within your organization to a contact record you create.
The findOrCreate.linkToEntity method can’t be used to populate fields on records that you create by using the
findOrCreate API call. Instead, use the findOrCreate.map method to update field values on records.
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 findOrCreate.linkToEntity method.
Available in API versions 29.0 and later.
Syntax
Parameters
Name
Type
Description
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
fieldName
String
Available Versions
The type of parent record to link to the child
record you found or created.
Available in API versions 29.0 and later.
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.
findOrCreate.displayToAgent
Use the findOrCreate.displayToAgent 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.
37
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
Find and Create Records Pre-Chat API Code Sample
Syntax
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
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:
• findOrCreate.map
• findOrCreate.map.doFind
• findOrCreate.map.isExactMatch
• findOrCreate.map.doCreate
• findOrCreate.saveToTranscript
• findOrCreate.showOnCreate
• findOrCreate.linkToEntity
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.
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
prechat.js file in the same Apex page and with the same path as the deployment.js file.
Available in API versions 29.0 and later.
Syntax
liveagent.details.preChatInit(String chatUrl, function detailCallback, (optional) String
chatFormName)
Parameters
Name
Type
Description
Available Versions
chatUrl
String
The URL of the chat to retrieve custom
details from.
Available in API versions 29.0 and later.
39
Use Pre-Chat to Gather Visitor Information and Set Context
for the Agent
Pre-Chat Form Code Sample
Name
Type
Description
Available Versions
detailCallback
String
Name of the JavaScript function to call
upon completion of the method.
Available in API versions 29.0 and later.
(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.
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
custom details are retrieved using the
myCallBack(details)
preChatInit method.
{ // Customer
specific code }
Available in API versions 29.0 and later.
Pre-Chat Form Code Sample
Test and preview how pre-chat forms can work for your agents and customers.
The following code is for a pre-chat form that:
• Gathers the visitor’s first and last name, email address, phone number, and issue, and sets the values to Custom Details.
• Searches for a contact whose email exactly matches the value provided by the customer in the form. If there's no match, it creates
a Contact record and maps the values provided by the customer to the record’s fields.
• Creates a Case record to attach to the chat, and maps the details found to the record’s fields.
• Sets the found or created Contact record as the contact for the Case.
• Associates the records Contact and Case to the Live Chat Transcript record and opens them for the agent in the Console.
• Searches knowledge article based on the text, assuming that Knowledge is set up.
• Displays the visitor’s first and last name for the agent in the Console.
Live Agent Pre-Chat Form
46
Implement a Custom Chat Window Using Visualforce
Live Agent Visualforce Components Code Sample
| Please wait while you are connected to an available agent. |
Post Chat Page
Request Time:
Start Time:
Deployment Id:
Button Id:
Chat Key:
Last Visited Page:
Original Referrer:
Latitude:
Longitude:
City:
Region:
Country:
50
Use Post-Chat to Wrap Up the Chat Interaction with Your
Customer
Post-Chat Code Sample
Organization:
Disconnected By:
Window Language:
Chat Details:
Transcript:
Attached Records :
Error: