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.

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.

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.

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.

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

Customize Deployments with the Deployment APIs enableLogging

Messages for Logged Events

Message

System initialized. Waiting for the DOM to be ready.

No available event model. Exiting.

Triggered

When liveagent.init() is called, usually at page load

During liveagent.init(), if there is an error

Meaning

Live Agent endpoint URL, org ID and deployment ID have been set, now waiting for DOM to be ready before continuing.

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 online

The button is available for a chat request to be made.

Setting state for button {Button ID} to offline When the state of a button has changed to offline

The button is not available for a chat request to be made.

Requesting new session During the first ping to the server

Reusing existing 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.

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

Pinging server to keep presence

Disconnecting from Live Agent

When a ping to the server is made

When an error occurs

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.

Indicates the visitor is still connected to and pinging the Live Agent server, meaning no errors or disconnects have occurred.

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).

Customize Deployments with the Deployment APIs enableLogging

Message

Received updated LiveAgent server url:

{URL}! Consider updating this site's deployment code.

Server Warning: {Message}

Server sent an anonymous warning

Server Error: {Message}

Server responded with an error

Group Start: Invite {Button ID} Rule

Evaluation

Filter Logic: {Filter Logic}

Evaluating StandardInviteRule

Evaluating TimerInviteRule

Evaluating CustomInviteRule

Triggered

When an org has moved to a new core instance

A non-fatal exception occurred

A fatal exception occurred

Rule evaluation has been triggered

When a standard rule is being evaluated

Meaning

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.

A warning condition was encountered, but processing can continue. The message provides further details.

A warning condition was encountered, but processing can continue. No message was provided.

An error condition was encountered, and processing cannot be continued. The message provides further details.

An error condition was encountered, and processing cannot be continued. No message was provided.

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.

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.

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.

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).

When a custom rule is being evaluated "Custom Variable" rules allow variable names to be specified which will be compared against upon evaluating these

Customize Deployments with the Deployment APIs enableLogging

Message 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

Evaluate: {From Value} == {To Value}

Not Equals - Evaluate: {From Value} != {To

Value}

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.

When a rule with an "equals" comparator is being evaluated

A rule is being evaluated by comparing that the two values match exactly.

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

{To Value} == 0

When a rule with a "starts with" comparator is being evaluated.

A rule is being evaluated by comparing that 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

A rule is being evaluated by comparing that the first value contains the second value.

Does Not Contain - Evaluate: {From Value} indexOf {To Value} == -1

When a rule with a "does not contain" comparator is being evaluated

A rule is being evaluated by comparing that the first value does not contain the second value.

Less Than - Evaluate: {From Value} < {To

Value}

When a rule with a "less than" comparator is being evaluated

Greater Than - Evaluate: {From Value} > {To

Value}

When a rule with a "greater than" comparator is being evaluated

A rule is being evaluated by comparing that the first value is less than the second value.

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}

When a rule with a "less or equal" comparator is being evaluated

Greater or Equal - Evaluate: {From Value} >=

{To Value}

Evaluating Atom Node: {Rule ID}

When a rule with a "greater or equal" comparator is being evaluated

When a rule is being evaluated

A rule is being evaluated by comparing that the first value is less than or equal to the second value.

A rule is being evaluated by comparing that the first value is greater than or equal to the second value.

Indicates that an actual rule is being evaluated.

Group Start: Evaluating And Node

Group Start: Evaluating Or Node

When two rules are being evaluated with an "AND" clause

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 both be "true."

When multiple rules are used, this indicates when the criteria of a pair of rules must be

"true" for one of them.

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

Message

Group Start: Evaluating Not Node

Setting invite delay to: {Invite Delay}

Triggered Meaning

When two rules are being evaluated with a

"NOT" clause

This indicates to check for the opposite of what the criteria evaluates to.

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

height

Type

Number

Description

The height in pixels of your custom chat window.

Available Versions

Available in API versions 28.0 and later.

setChatWindowWidth

Use the setChatWindowWidth

method to customize the width of your chat window.

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

width

Type

Number

Description

The width in pixels of your custom chat window.

Available Versions

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.

showWhenOnline

Use the showWhenOnline

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

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

buttonId element userId

Type

String

Object

String

Description Available Versions

The ID of the chat button for which to display the specified element

object when agents that are associated with the button are available to chat.

Available in API versions 28.0 and later.

The element to be displayed when the specified button is online.

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.

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

buttonId element userId

Type

String

Object

String

Description Available Versions

The ID of the chat button for which to display the specified element

object when no agents are available to chat.

Available in API versions 28.0 and later.

The element to display when the specified button is offline.

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.

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

buttonId callback

Type

String function

Description

The ID of the chat button for which to define the behavior when certain events occur.

Available Versions

Available in API versions 28.0 and later.

The function to call when a particular event occurs. You must specify the button’s behavior

for each of the required event types on page

13.

Available in API versions 28.0 and later.

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

callback

Event Type

BUTTON_AVAILABLE

Syntax Description

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.

Customize Deployments with the Deployment APIs

Function Event Type

BUTTON_UNAVAILABLE

Syntax Description

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

buttonId

(Optional) userId

(Optional) fallback

Type

String

Boolean

Description Available Versions

The ID of the chat button for which to request a chat in a new window.

Available in API versions 28.0 and later.

The Salesforce.com user ID of the agent to whom to directly route chats from the button.

Available in API versions 29.0 and later.

Specifies whether to fall back to the button’s routing rules ( true

) or not ( false

) if the agent with the specified sfdcUserId

is unavailable.

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.

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

buttonId windowName

(Optional) userId

(Optional) fallback

Type

String

Boolean

Description Available Versions

The ID of the chat button for which to request a chat in a new window.

Available in API versions 28.0 and later.

The name of the window.

Available in API versions 28.0 and later.

TheSalesforce user ID of the agent to whom to directly route chats from the button.

Available in API versions 29.0 and later.

Specifies whether to fall back to the button’s routing rules ( true

) or not ( false

) if the agent with the specified sfdcUserId

is unavailable.

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

Button

Agent (no fallback)

Agent (fallback to button)

Call to startChat (or startChatWithWindow)

startChat(

String

buttonId) startChat(

String

buttonId,

String

userId, false) startChat(

String

buttonId,

String

userId, true)

Call to showWhenOnline

(or showWhenOffline)

Call to addButtonEventHandler

showWhenOnline(

String

buttonId,

Object

element, (optional)

String userId) addButtonEventHandler(

String buttonId,

Function callback) showWhenOnline(

String

userId,

Object

element) addButtonEventHandler(

String userId,

Function callback) showWhenOnline(

String

buttonId,

Object

element,

String

userId)

Use multiple handlers.

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

label value

(Optional) displayToAgent

Type

String

Boolean

Description

The label for the custom detail—for example,

"Name"

Available Versions

Available in API versions 28.0 and later.

The value of the custom detail—for example,

"John Doe"

Available in API versions 28.0 and later.

Specifies whether to display the custom details that customers provide in a pre-chat form to the agent ( true

) or not ( false

Available in API versions 29.0 and later.

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

EntityName

Type

String

Description Available Versions

The type of record to search for or create when an agent accepts a chat with a customer—for example, a contact record.

Available in API versions 29.0 and later.

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.

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

FieldName

DetailName doFind isExactMatch doCreate

Type

String

Boolean

Description Available Versions

The API name of the field in the record

EntityName to which to map the corresponding custom detail

DetailName

Available in API versions 29.0 and later.

The value of the custom detail to map to the corresponding field

FieldName

Available in API versions 29.0 and later.

Specifies whether to search for a record that contains the custom detail

DetailName

in the field

FieldName

( true

) or not

( false

Available in API versions 29.0 and later.

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

Available in API versions 29.0 and later.

Specifies whether to create a new record with 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.

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)

Customize Deployments with the Deployment APIs

Parameters

Name Type

TranscriptFieldName

String

Description Available Versions

The name of the field on the chat transcript record to which to save the ID of the record you found or created.

Available in API versions 29.0 and later.

findOrCreate

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

EntityName

Type

String

Description

The type of record to which to link the child record you found or created.

Available Versions

Available in API versions 29.0 and later.

Customize Deployments with the Deployment APIs

Name

FieldName

Type

String

Description Available Versions

The name of the API field in the record

EntityName

to which to save the ID of the child record you found or created.

Available in API versions 29.0 and later.

setName

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

name

Type

String

Description Available Versions

The visitor name that appears in the Live Agent console or the Salesforce console.

Available in API versions 28.0 and later.

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.

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

/* Creates a custom detail called First Name and sets the value to "Jane" */ liveagent.addCustomDetail("First Name", "Jane");

/* Creates a custom detail called Last Name and sets the value to "Doe" */ liveagent.addCustomDetail("Last Name", "Doe");

/* Creates a custom detail called Phone Number and sets the value to "555-1212" */ liveagent.addCustomDetail("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

*/ liveagent.addCustomDetail("Case Subject", "Best snowboard for a beginner").doKnowledgeSearch();

/* Creates a custom detail called Case Status and sets the value to "New" */ liveagent.addCustomDetail("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 */ liveagent.findOrCreate("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 */ liveagent.findOrCreate("Contact").map("FirstName","First

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 */ liveagent.findOrCreate("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.

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

variableName

Type

String

Description

The name of the customized criteria for your custom sending rule.

Available Versions

Available in API versions 28.0 and later.

Customize Deployments with the Deployment APIs

Name

value

Type

Object

Description Available Versions

The comparison value for your custom sending rule.

Available in API versions 28.0 and later.

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

buttonId

Type

String

Description

The ID of the chat button for which to reject chats.

Available Versions

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.

Customize Deployments with the Deployment APIs addButtonEventHandler

Available in API versions 28.0 and later.

Syntax

void addButtonEventHandler(String buttonId, Function callback)

Parameters

Name

buttonId callback

Type

String function

Description Available Versions

The ID of the chat button associated with the automated invitation for which to define the behavior when certain events occur.

Available in API versions 28.0 and later.

The function to call when a particular event occurs. You must specify the invitation’s

behavior for each of the required event types

on page 24.

Available in API versions 28.0 and later.

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

callback

Event Type

BUTTON_AVAILABLE

BUTTON_UNAVAILABLE

BUTTON_ACCEPTED

Syntax Description

liveagent.BUTTON_EVENT.BUTTON_AVAILABLE

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

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.

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

Customize Deployments with the Deployment APIs

Function Event Type

BUTTON_REJECTED

Automated Chat Invitation Code Sample

Syntax Description

automated chat invitations.

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>

<!-- This section creates the div with the UI for chat invitation whose id is 573D01234567890

-->

<!-- For this usage, the "Animation" type of this invitation should be set to "Custom", otherwise two invitations will appear (the Salesforce-provided one and this custom one).

-->

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

</div>

<!-- Creates the callback function used for the Live Agent chat invitation to present it

Customize Deployments with the Deployment APIs Automated Chat Invitation Code Sample or not based on availability and the customer's interaction with it --> function buttonCallback(e) {

if (e == liveagent.BUTTON_EVENT.BUTTON_AVAILABLE) { document.getElementById('liveagent_invite_button_573D01234567890').style.display = ''; document.getElementById('liveagent_invite_button_573D01234567890').style.left = '300px'; document.getElementById('liveagent_invite_button_573D01234567890').style.top = '200px';

}

if (e == liveagent.BUTTON_EVENT.BUTTON_UNAVAILABLE) { document.getElementById('liveagent_invite_button_573D01234567890').style.display = 'none';

}

if (e == liveagent.BUTTON_EVENT.BUTTON_ACCEPTED) { document.getElementById('liveagent_invite_button_573D01234567890').style.display = 'none';

}

if (e == liveagent.BUTTON_EVENT.BUTTON_REJECTED) { document.getElementById('liveagent_invite_button_573D01234567890').style.display = 'none';

}

liveagent.addButtonEventHandler('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.

liveagent.setCustomVariable('shoppingCartValue', shoppingCartValue);

<!-- Live Agent deployment code that initializes chat for the deployment whose id is

572D01234567890 and org is 00DD01234567890 --> liveagent.init('https://d.la1s1.salesforceliveagent.com/chat', '572D01234567890',

'00DD01234567890');

<!-- Enable Live Agent advanced logging to be available through the Browser's Developer

Console --> liveagent.enableLogging();

</script>

</apex:page>

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

<apex:page showHeader="false">

<h1>Welcome to Support</h1>

<br />

Thank you for your interest.

<div id="liveagent_button_offline_573B0000000033Y" style="display: none;">Live Chat is currently unavailable</div>

});</script>

Customize Deployments with the Deployment APIs Deployment API Code Sample

/* Adds a custom detail called Contact Email and sets it value to [email protected] */ liveagent.addCustomDetail('Contact E-mail', '[email protected]');

/* Creates a custom detail called First Name and sets the value to Jane */ liveagent.addCustomDetail('First Name', 'Jane');

/* Creates a custom detail called Last Name and sets the value to Doe */ liveagent.addCustomDetail('Last Name', 'Doe');

/* Creates a custom detail called Phone Number and sets the value to 415-555-1212 */ liveagent.addCustomDetail('Phone Number', '415-555-1212');

/* An auto-query that searches Contacts whose Email field exactly matches '[email protected]'.

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. */ liveagent.findOrCreate('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 */ liveagent.findOrCreate('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 */ liveagent.addCustomDetail('Case Subject','Refund policy for products').doKnowledgeSearch();

/* Creates a custom detail called Case Status and sets the value to 'New' */ liveagent.addCustomDetail('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 */ liveagent.findOrCreate('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 */ liveagent.addCustomDetail('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. */ liveagent.addCustomDetail('VisitorHash', 'c6f440178d478e4326a1', false);

Customize Deployments with the Deployment APIs Deployment API Code Sample

/* Sets the display name of the visitor in the agent console when engaged in a chat */ liveagent.setName('Jane Doe');

/* Sets the width of the chat window to 500px */ liveagent.setChatWindowWidth(500);

/* Sets the height of the chat window to 500px */ liveagent.setChatWindowHeight(500);

liveagent.init('https://d.la.gus.salesforce.com/chat', '572B000000003KL', '00DB00000000Rr8');

</script>

</apex:page>

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.

Customize Deployments with the Deployment APIs Deployment API Code Sample

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.

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

entityName

Type

String fieldName detailName

String

Description

The name of the field in the record

EntityName

to which to map the corresponding custom detail value

Available Versions

The type of record to search for or create when an agent accepts a chat with a customer, for example, a contact record

Available in API versions 29.0 and later.

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.

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

<input type= "hidden" name= "liveagent.prechat.findorcreate.map.doFind:

String

entityName" value= " String fieldName, Boolean find;" />

Parameters

Name

entityName fieldName find

Type

String

Boolean

Description

The name of the API field to search for in existing records.

Available Versions

The type of record to search for or create when an agent accepts a chat with a customer—for example, a contact record.

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.

Specifies whether to search for existing records that contain the field fieldName

( true

) or not ( false

Available in API versions 29.0 and later.

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.

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

<input type= "hidden" name= "liveagent.prechat.findorcreate.map.isExactMatch:

String

entityName" value= "

String fieldName, Boolean exactMatch;" />

Parameters

Name

entityName fieldName find

Type

String

Boolean

Description Available Versions

The type of record to search for or create when an agent accepts a chat with a customer—for example, a contact record.

Available in API versions 29.0 and later.

The API name of the field to search for in 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.

Specifies whether to search for existing records that contain an exact match to the field fieldName

( true

) or not ( false

Available in API versions 29.0 and later.

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.

Use Pre-Chat to Gather Visitor Information and Set Context for the Agent findOrCreate.saveToTranscript

Syntax

<input type= "hidden" name= "liveagent.prechat.findorcreate.map.doCreate:

String

entityName" value= " String fieldName, Boolean create;" />

Parameters

Name

entityName fieldName create

Type

String

Boolean

Description Available Versions

The type of record to create when an agent accepts a chat with a customer and an existing record isn’t found—for example, a contact record.

Available in API versions 29.0 and later.

The API name of the field to include in new 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.

Specifies whether to create a new record that contains the field fieldName

( true

) or not ( false

Available in API versions 29.0 and later.

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.

Use Pre-Chat to Gather Visitor Information and Set Context for the Agent findOrCreate.showOnCreate

Syntax

<input type="hidden" name= "liveagent.prechat.findorcreate.saveToTranscript:

String

entityName" value= " String transcriptFieldName" />

Parameters

Name

entityName

Type

String transcriptFieldName

String

Description Available Versions

The type of record to search for or create when an agent accepts a chat with a customer—for example, a contact record.

Available in API versions 29.0 and later.

The API name of the field on the chat transcript record to which to save the ID of the record you found or created.

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.

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

<input type= "hidden" name= "liveagent.prechat.findorcreate.showOnCreate:

String

entityName" value= " Boolean show" />

Parameters

Name

entityName show

Type

String

Boolean

Description Available Versions

The type of record to search for or create when an agent accepts a chat with a customer—for example, a contact record.

Available in API versions 29.0 and later.

Specifies whether to display the record you created in a subtab in the Salesforce console

( true

) or not ( false

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

<input type= "hidden" name= "liveagent.prechat.findorcreate.linkToEntity:

String

entityName" value= " String parentEntityName, String fieldName" />

Parameters

Name

entityName

Type

String parentEntityName

String fieldName

String

Description Available Versions

The type of record which is linked to the parent record you found or created.

Available in API versions 29.0 and later.

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 parentEntityName

where the ID of the child record you found or created is saved.

Available in API versions 29.0 and later.

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.

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

Find and Create Records Pre-Chat API Code Sample

Syntax

<input type= "hidden" name= "liveagent.prechat.findorcreate.displayToAgent:

String

detailName" value= " Boolean display" />

Parameters

Name

detailName display

Type

String

Boolean

Description

The name of the detail to display to an agent when they receive a chat request.

Available Versions

Available in API versions 29.0 and later.

Specifies whether to display the custom detail to an agent in the chat notifications and Details tab ( true

) or not ( false

Available in API versions 29.0 and later.

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

<label>First Name: </label> <input type='text' name='liveagent.prechat:ContactFirstName'

/><br />

<label>Last Name: </label> <input type='text' name='liveagent.prechat:ContactLastName'

/><br />

<label>Subject: </label> <input type='text' name='liveagent.prechat:CaseSubject' /><br />

<input type="hidden" name="liveagent.prechat.findorcreate.map.isExactMatch:Contact"

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

Access Chat Details with the Pre-Chat APIs value="FirstName,true;LastName,true" />

<input type="hidden" name="liveagent.prechat.findorcreate.showOnCreate:Contact" value="true"

</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.

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

chatUrl

Type

String

Description

The URL of the chat to retrieve custom details from.

Available Versions

Available in API versions 29.0 and later.

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

Name

detailCallback

(Optional) chatFormName

Type

String

Description

Name of the JavaScript function to call upon completion of the method.

Pre-Chat Form Code Sample

Available Versions

Available in API versions 29.0 and later.

The name of the HTML form tag for the pre-chat form to which to incorporate the custom details.

Available in API versions 29.0 and later.

Responses

Name

details

Type

Object

Description

An object containing the deployment information included in the pre-chat form using the preChatInit

method.

Available Versions

Available in API versions 29.0 and later.

detailCallback

The detailCallback

method specifies the behavior that occurs after the preChatInit

method returns the details

object.

Syntax Parameters Description

function myCallBack(details)

{ // Customer specific code }

details

Specifies the actions to occur after the custom details are retrieved using the preChatInit

method.

Available Versions

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.

<apex:page showHeader="false">

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

Pre-Chat Form Code Sample

(function() { function handlePageLoad() { var endpointMatcher = new RegExp("[\\?\\&]endpoint=([^&#]*)"); document.getElementById('prechatForm').setAttribute('action', decodeURIComponent(endpointMatcher.exec(document.location.search)[1].replace("javascript:",

"")));

} if (window.addEventListener) { window.addEventListener('load', handlePageLoad, false);

} else { window.attachEvent('onload', handlePageLoad, false);

}})();

</script>

<h1>Live Agent Pre-Chat Form</h1>

<!-- Form that gathers information from the chat visitor and sets the values to Live Agent

Custom Details used later in the example -->

First name: <input type='text' name='liveagent.prechat:ContactFirstName' id='firstName'

/><br />

Last name: <input type='text' name='liveagent.prechat:ContactLastName' id='lastName'

/><br />

Email: <input type='text' name='liveagent.prechat:ContactEmail' id='email' /><br />

Phone: <input type='text' name='liveagent.prechat:ContactPhone' id='phone' /><br />

Issue: <input type='text' name='liveagent.prechat:CaseSubject' id='subject' /><br />

<!-- This example will set the Case Record Type to a specific value for the record type configured on the org. Lookup the case record type's id on your org and set it here

-->

<input type="hidden" name="liveagent.prechat:CaseRecordType" value="012D00123456789"

<input type="hidden" name="liveagent.prechat.findorcreate.map:Contact" value="FirstName,ContactFirstName;LastName,ContactLastName;Email,ContactEmail;Phone,ContactPhone"

<input type="hidden" name="liveagent.prechat.findorcreate.map:Case" value="Subject,CaseSubject;Status,CaseStatus;Origin,CaseOrigin;RecordTypeId,CaseRecordType"

<!-- doFind, doCreate and isExactMatch example for a Contact:

Find a contact whose Email exactly matches the value provided by the customer in the form

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

Pre-Chat Form Code Sample

If there's no match, then create a Contact record and set it's First Name, Last Name,

Email, and Phone to the values provided by the customer -->

<input type="hidden" name="liveagent.prechat.findorcreate.showOnCreate:Contact" value="true"

<input type="hidden" name="liveagent.prechat.findorcreate.showOnCreate:Case" value="true"

<!-- searchKnowledge: Searches knowledge article based on the text, this assumes that

Knowledge is setup -->

}

</script>

Use Pre-Chat to Gather Visitor Information and Set Context for the Agent p {font-weight: bolder }

</style>

</form>

</apex:page>

This code results in a pre-chat form that looks like this:

Pre-Chat Form Code Sample

CHAPTER 6 Implement a Custom Chat Window Using

Visualforce

Chat windows are what visitors use to exchange messages with support agents. Each of your Live Agent 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.

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 Developers’ Guide

Live Agent Visualforce Components

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

Live Agent Visualforce Components Code Sample

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

Live Agent Visualforce Components

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

Live Agent includes the following customizable Visualforce components. These components are placed on your Visualforce form to make certain functionality available and to customize the appearance of the chat window.

Chat windows have various states to inform chat visitors of their chat’s progress. The following components let you customize how the chat window looks and behaves in these states to best help your visitors.

Component Name

liveAgent:clientChat

Description

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

liveAgent:clientChatAlertMessage

The area in a Live Agent chat window that displays system alert messages (such as

"You have been disconnected").

liveAgent:clientChatMessages

The area in a Live Agent 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 Live Agent 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

Implement a Custom Chat Window Using Visualforce Live Agent Visualforce Components Code Sample

Component Name Description

liveAgent:clientChatCancelButton

The button within a Live Agent 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 Live Agent 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 liveAgent:clientChatLog liveAgent:clientChatInput

The button within a Live Agent chat window that a visitor clicks to end a chat session.

Must be used within liveAgent:clientChat

The area in a Live Agent 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.

The text box in a Live Agent 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 Live Agent 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 Live Agent chat window that displays the idle time-out alert (customer warning) to a visitor.

liveAgent:clientChatFileTransfer

The file upload area in a Live Agent 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:

•

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.

Live Agent Visualforce Components Code Sample

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

The following code sample shows a chat window that uses the following components:

•

liveAgent:clientChat

•

liveAgent:clientChatMessages

Implement a Custom Chat Window Using Visualforce Live Agent Visualforce Components Code Sample

•

liveAgent:clientChatEndButton

•

liveAgent:clientChatLog

•

liveAgent:clientChatInput

<apex:page showHeader="false">

<style>

#liveAgentClientChat.liveAgentStateWaiting {

// 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

}

#liveAgentClientChat.liveAgentStateEnded {

// 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; }

#liveAgentClientChat.liveAgentStateWaiting #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%;

}

.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>

Implement a Custom Chat Window Using Visualforce Live Agent Visualforce Components Code Sample

<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 />

<tr>

<td>Please wait while you are connected to an available agent.</td>

</tr>

</table>

<liveAgent:clientChatLog />

</div>

<div style="position: absolute; height: auto; right: 0; bottom: 0; left: 0; margin-right:

67px;">

<liveagent:clientChatInput /><liveAgent:clientChatSendButton />

</div>

</liveAgent:clientChat>

</div>

</apex:page>

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

Chat Waiting

Implement a Custom Chat Window Using Visualforce

Chat in Progress

Live Agent Visualforce Components Code Sample

Chat Ended

CHAPTER 7 Use Post-Chat to Wrap Up the Chat

Interaction with Your Customer

Post-chat pages let 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.

You can create a Visualforce page to host your post-chat page, or you can develop a page on your own and add the URL to your chat button configuration. The information in this guide focuses on using Visualforce.

Post-Chat Code Sample

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

Post-Chat Code Sample

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

You can customize your post-chat page by including the variables you want to be displayed.

Possible Variables

requestTime startTime deploymentId buttonId chatKey lastVisitedPage originalReferrer latitude longitude city region country organization disconnectedBy

Description

The timestamp when the system received the chat request.

The timestamp when the agent accepted the chat.

The ID of the deployment.

The Id of the button that originated the chat.

The unique chat key.

The last visited page value sent to the agent.

The first page the customer visited containing the deployment code.

Geo location latitude of the chat visitor.

Geo location longitude of the chat visitor.

Geo location city of the chat visitor..

Geo location region of the chat visitor.

Geo location country of the chat visitor.

Salesforce organization ID that hosted the chat.

Reason for ending the chat. Possible values:

•

agent

- the agent terminated the chat

•

client

- the chat visitor terminted the chat

Use Post-Chat to Wrap Up the Chat Interaction with Your

Customer

Possible Variables

Post-Chat Code Sample windowLanguage chatDetails transcript attachedRecords error

Description

•

error

- the system encountered an error that disconnected the chat

•

clientIdleTimeout

- the chat visitor didn’t answer within the alloted time (must have Idle Timeout configured)

•

agentsUnavailable

- there are no agents available to receive the chat or there is no room in the queue

Language of the window as configured in the chat button.

A JSON representation of the chat data.

A plain text copy of the transcript.

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

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'>

<p>

Request Time: <apex:outputText id='c_rt' value='{!$CurrentPage.parameters.requestTime}' /><br/>

Start Time: <apex:outputText id='c_st' value='{!$CurrentPage.parameters.startTime}' /><br/>

Deployment Id: <apex:outputText value='{!$CurrentPage.parameters.deploymentId}' /><br/>

Button Id: <apex:outputText value='{!$CurrentPage.parameters.buttonId}'

/><br/>

Chat Key: <apex:outputText value='{!$CurrentPage.parameters.chatKey}'

/><br />

Last Visited Page: <apex:outputText value='{!$CurrentPage.parameters.lastVisitedPage}' /><br/>

Original Referrer: <apex:outputText value='{!$CurrentPage.parameters.originalReferrer}' /><br/>

<!-- When the GeoLocation is not available this will appear as Unknown

-->

Latitude: <apex:outputText value='{!$CurrentPage.parameters.latitude}'

/><br/>

Longitude: <apex:outputText value='{!$CurrentPage.parameters.longitude}'

/><br/>

City: <apex:outputText value='{!$CurrentPage.parameters.city}' /><br/>

Region: <apex:outputText value='{!$CurrentPage.parameters.region}' /><br/>

Country: <apex:outputText value='{!$CurrentPage.parameters.country}'

/><br/>

Use Post-Chat to Wrap Up the Chat Interaction with Your

Customer

Post-Chat Code Sample

Organization: <apex:outputText value='{!$CurrentPage.parameters.organization}' /><br/>

Disconnected By: <apex:outputText value='{!$CurrentPage.parameters.disconnectedBy}' /><br/>

Window Language: <apex:outputText value='{!$CurrentPage.parameters.windowLanguage}' /><br/>

Chat Details: <apex:outputText value='{!$CurrentPage.parameters.chatDetails}' /><br />

Transcript: <apex:outputText value='{!$CurrentPage.parameters.transcript}'

/><br/>

Attached Records : <apex:outputText value='{!$CurrentPage.parameters.attachedRecords}' /><br />

Error: <apex:outputText value='{!$CurrentPage.parameters.error}' /><br

</div>

</p>

<hr/>

We are sorry you decided to leave the chat. Feel free to initiate a new session.

</div>

// when startTime doesn't have a value, it means the chat never started if (!startTime) { document.getElementById('details').style.display = 'none'; document.getElementById('abandoned').style.display = 'block';

}

</script>

</apex:page>

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

Use Post-Chat to Wrap Up the Chat Interaction with Your

Customer

Post-Chat Code Sample

This message shows if the chat is abandoned:

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 Live Agent

Deployment API. You can set chats to fallback to another button or queue if the specified agent isn’t available.

Direct-to-agent routing lets your agents provide visitors with a way to contact them directly. This is useful when a visitor’s issue requires a follow-up conversation, because the agent can provide a direct-to-agent link that ensures the visitor won’t have to start over with a new agent.

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.

Use the following Deployment API methods to set up direct-to-agent routing with fallback routing enabled in case the agent isn’t available for chat.

•

•

•

•

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.

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 {!user.name}</h1>

Set Up Direct-to-Agent Chat Routing with the Deployment

APIs

Direct-to-Agent Routing Code Sample

<a href="javascript://Chat" onclick="liveagent.startChat('573D01234567890',

'{!left(user.id,15)}')">Chat with {!user.name}!</a>

</div>

<!-- button_online is displayed if any agents are available to chat for the button.

-->

<div id="button_online" style="display: none;">Sorry, {!user.name} is not available.

If you’d like, you can

<a href="javascript://Chat" onclick="liveagent.startChat('573D01234567890')">start a chat with another agent</a>.

</div>

<!-- button_offline is displayed if no agents are available to chat for the button.

-->

<div id="button_offline" style="display: none;">Sorry, all agents (including

{!user.name}) appear to be unavailable.</div>

</div>

/* The following calls pass the user ID as the first argument and show whether the agent is online.*/ liveagent.showWhenOnline('{!left(user.id,15)}', document.getElementById('dta_online')); liveagent.showWhenOffline('{!left(user.id,15)}', document.getElementById('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. */ liveagent.showWhenOnline('573D01234567890', document.getElementById('button_online')); liveagent.showWhenOffline('573D01234567890', document.getElementById('button_offline'));

/* This domain and the IDs are specific to your org, so replace these with your own.

*/ liveagent.init('https://d.la1s1.salesforceliveagent.com/chat', '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.

http://your.website/ChatWithMe?id=005D01234567890

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: http://your.website/ChatWithMe?id={!User_ID}

Set Up Direct-to-Agent Chat Routing with the Deployment

APIs

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.

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:

Name: <input type='text' name='liveagent.prechat.name' id='prechat_field' /><br />

Email Address: <input type='text' name='liveagent.prechat:Email' /><br />

Department: <select name="liveagent.prechat.buttons">

<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.

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.

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 Live Agent 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">

Set Up Direct-to-Agent Chat Routing with the Deployment

APIs

Fallback Routing Code Sample

} if (window.addEventListener) { window.addEventListener('load', handlePageLoad, false);

} else { window.attachEvent('onload', handlePageLoad, false);

}})();

</script>

Name: <input type='text' name='liveagent.prechat.name' id='prechat_field' /><br />

Email Address: <input type='text' name='liveagent.prechat:Email' /><br />

Department: <select name="liveagent.prechat.buttons">

<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>

</select><br />

</form>

</apex:page>

Reklama

Live Agent Developer's Guide

Version 40.0, Summer ’17

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

CHAPTER 2 Prerequisites

CHAPTER 3 API Versions

Deployment API Versions

Pre-Chat Information API Versions

CHAPTER 4 Customize Deployments with the

Deployment APIs

Create Deployments

Log Deployment Activity with the Deployment APIs

enableLogging

Customize Your Chat Window with the Deployment APIs

setChatWindowHeight

setChatWindowWidth

Customize Chat Buttons with the Deployment APIs

showWhenOnline

showWhenOffline

addButtonEventHandler

startChat

startChatWithWindow

Corresponding Calls for Chat Buttons

Find and Create Records Automatically with the Deployment APIs

addCustomDetail

findOrCreate

findOrCreate.map

findOrCreate.saveToTranscript

findOrCreate.showOnCreate

findOrCreate.linkToEntity

setName

Search for Knowledge Articles with the Deployment APIs

addCustomDetail.doKnowledgeSearch

Find and Create Records Deployment API Code Sample

Customize Automated Chat Invitations with the Deployment APIs

setCustomVariable

rejectChat

addButtonEventHandler

Automated Chat Invitation Code Sample

Deployment API Code Sample

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

Find and Create Records Automatically with the Pre-Chat APIs

findOrCreate.map

findOrCreate.map.doFind

findOrCreate.map.isExactMatch

findOrCreate.map.doCreate

findOrCreate.saveToTranscript

findOrCreate.showOnCreate

findOrCreate.linkToEntity

findOrCreate.displayToAgent

Find and Create Records Pre-Chat API Code Sample

Access Chat Details with the Pre-Chat APIs

preChatInit

detailCallback

Pre-Chat Form Code Sample

CHAPTER 6 Implement a Custom Chat Window Using

Visualforce

Live Agent Visualforce Components

Using

liveAgent:clientChatQueuePosition

Live Agent Visualforce Components Code Sample

CHAPTER 7 Use Post-Chat to Wrap Up the Chat

Interaction with Your Customer

Post-Chat Code Sample

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

Direct-to-Agent Routing with the Deployment APIs

Direct-to-Agent Routing Code Sample

Fallback Routing in Pre-Chat Forms

Fallback Routing Code Sample

Susiję

Salesforce Live Agent Developer's Guide

Live Agent User Guide - Salesforce Winter '16

CodingBest Chat4Support Manual: AI Chat & PDF Access

Salesforce Console Integration Toolkit Developer Guide Spring '17

Salesforce Console Integration Toolkit Developer Guide - Winter '17

Salesforce Omni-Channel Admin Manual | AI Chat

Salesforce Snap-Ins Chat User Guide

D2L Chat User Guide: AI Chat & PDF Access