Salesforce.com Admin and Developer Blog: How to create cases and contacts from LiveAgent Pre-chat API

The many different configuration options available and base out-of-the-box functionality make Salesforce Live Agent especially appealing for a web chat product. The Pre-Chat API in the Pre-Chat form is the focus of this article.

Collecting information from chat customers prior to them being connected to an agent is a common use case of web based chats. Providing that information to the agents before they interact with the chat customer will increase the agents’ productivity since they won’t have to take time to manually ask those questions. Live Agent has an optional Pre-Chat form that can be provided for the chat customer to fill out prior to the start of the chat. The methods available are documented as the Pre-Chat API in the Live Agent Developer’s Guide. The Pre-Chat API can be used to search for or create records automatically when a chat customer submits the Pre-Chat form. The Pre-Chat API is an API that is very powerful and interesting. The “code” that you write is actually just HTML input elements that conform to the API. Before you can use a Pre-Chat form there is some configuration set up that must be done. For a detailed look at all of the different options available for Live Agent see the Salesforce.com Help Page: Setting Up Live Agent.

Configuration Set Up

The Pre-Chat form can be placed in a Visualforce page and accessed via a Force.com Site or you can place it in a non Salesforce website. Before the Pre-Chat form can be used you must specify its location in the Chat Button customization. There is a field called Pre-Chat form URL that allows you to specify the URL for the page that has your Pre-Chat form on it. That’s the field you should use to specify a non Salesforce URL. There is another field called Pre-Chat form Page that is a Lookup to a Visualforce page that has your Pre-Chat form in it, which you would use if you were hosting the Pre-Chat form on a Force.com Site. If you are deploying to your non Salesforce website then you can just leave that blank.

In the Deployment configuration you need to make sure that you add the domain where you deploy Live Agent to the Permitted Domains field. Note that you must also check the Allow Access to Pre-Chat API checkbox.

Pre-Chat Form Code

The Live Agent Developer’s Guide has a very basic Pre-Chat form code sample from which to start. I’ve created a Pre-Chat form that is much more complex to explore the different features available. The code below is a Pre-Chat form that I created that collects input, searches for a Contact, creates one if not found, creates a Case, links the Contact to the Case, and the Case and Contact to the Live Chat Transcript record. Below is the Pre-Chat form screen, followed by the code and a detailed explanation.

<!DOCTYPE
 html>
<html>
<head>
<script type="text/javascript">
(function() { 
  function handlePageLoad() {
    var endpointMatcher = new 
RegExp("[\\?\\&]endpoint=([^&#]*)");
    document.getElementById('prechatForm').setAttribute('action',
    
decodeURIComponent(endpointMatcher.exec(document.location.search)[1]));
  } 
  if (window.addEventListener) {
    window.addEventListener('load', handlePageLoad, false);
  } else { 
    window.attachEvent('onload', handlePageLoad, false);
  }
})(); 
</script>
</head>
<body>
<form method="post" id="prechatForm">

<!-- Detail inputs -->
First Name: <input type="text" 
name="liveagent.prechat:contactFirstName" /><br />
Last Name: <input type="text" 
name="liveagent.prechat:contactLastName" /><br />
Email: <input type="text" name="liveagent.prechat:contactEmail" 
/><br />

Subject: <input type="text" name="liveagent.prechat:caseSubject" 
/><br />

<!-- Map the detail inputs to the Contact fields --> 
<input type="hidden" 
name="liveagent.prechat.findorcreate.map:Contact" 
value="FirstName,contactFirstName;LastName,contactLastName;Email,contactEmail;"
 />

<!-- Try to find the Contact by email (exact match) -->
<input type="hidden" 
name="liveagent.prechat.findorcreate.map.doFind:Contact" 
value="Email,true;" />
<input type="hidden" 
name="liveagent.prechat.findorcreate.map.isExactMatch:Contact" 
value="Email,true;" />

<!-- If the Contact is not found, then create one with the following 
fields set -->
<input type="hidden" 
name="liveagent.prechat.findorcreate.map.doCreate:Contact" 
value="FirstName,true;LastName,true;Email,true;" />

<!-- Save the Contact on the Live Chat Transcript's Contact Loookup 
-->
<input type="hidden" 
name="liveagent.prechat.findorcreate.saveToTranscript:Contact" 
value="Contact" />

<!-- Show the Contact when it is found or created -->
<input type="hidden" 
name="liveagent.prechat.findorcreate.showOnCreate:Contact" value="true" 
/>

<!-- Create a Case every time -->
<input type="hidden" name="liveagent.prechat:caseOrigin" value="Chat"
 />
<input type="hidden" name="liveagent.prechat.findorcreate.map:Case" 
value="Origin,caseOrigin;Subject,caseSubject;" />
<input type="hidden" 
name="liveagent.prechat.findorcreate.map.doCreate:Case" 
value="Origin,true;Subject,true;" />
<input type="hidden" 
name="liveagent.prechat.findorcreate.saveToTranscript:Case" value="Case"
 />
<input type="hidden" 
name="liveagent.prechat.findorcreate.showOnCreate:Case" value="true" 
/>

<!-- Link the Contact to the Case -->
<input type= "hidden" 
name="liveagent.prechat.findorcreate.linkToEntity:Contact" 
value="Case,ContactId" />

<input type="submit" value="Request Chat" id="prechat_submit" />

</form>
</body>
</html>

<!DOCTYPE html>

<html>

<head>

(function() {

function handlePageLoad() {

var endpointMatcher = new RegExp("[\\?\\&]endpoint=([^&#]*)");

document.getElementById('prechatForm').setAttribute('action',

decodeURIComponent(endpointMatcher.exec(document.location.search)[1]));

}

if (window.addEventListener) {

window.addEventListener('load', handlePageLoad, false);

} else {

window.attachEvent('onload', handlePageLoad, false);

}

})();

</script>

</head>

<body>

First Name: <input type="text" name="liveagent.prechat:contactFirstName" /><br />

Last Name: <input type="text" name="liveagent.prechat:contactLastName" /><br />

Email: <input type="text" name="liveagent.prechat:contactEmail" /><br />

Subject: <input type="text" name="liveagent.prechat:caseSubject" /><br />

</form>

</body>

</html>

The Live Agent HTML page code is available in this Gist.
The JavaScript takes the endpoint URL parameter passed from the deployment page and makes it the action for the form, so that the form is submitted to the proper place. There is nothing that needed to be changed from what was provided in the Developer’s Guide.
You can specify custom details on the live agent chat. These will be displayed in the Details of the Chat for the agent and the hover pop that is displayed when the agent mouses over the accept chat button. The format is name="liveagent.prechat:<detailName> and you can specify whatever values you want. When you are reading the Pre-Chat API documentation and you see reference to detailName, that’s referring to the value you specify after the colon in liveagent.prechat:<detailName>. These values will appear on the hover of request and on the Visitor Details screen.

The custom details values are not automatically saved on The Live Chat Transcript record. To do that you need to actually create a corresponding custom field on the Live Chat Transcript and use the save input, e.g., <input type="hidden" name="liveagent.prechat.save:yourCustomDetail" value="Your_Custom_Field__c" />. Note that you can use hidden inputs for the custom details. The custom details in the code from above is:

<input type="text" name="liveagent.prechat:contactFirstName" />
<input type="text" name="liveagent.prechat:contactLastName" />
<input type="text" name="liveagent.prechat:contactEmail" />
<input type="text" name="liveagent.prechat:caseSubject" />
<input type="hidden" name="liveagent.prechat:caseOrigin" value="Chat" />

Once you have the details set up, you can specify how they should get mapped into Salesforce. You create one Map per Object. In each map you specify the Object’s field name, custom detail name and you separate each pair with a semi-colon. In the code sample, the Contact and the Case are mapped:

<input type="hidden" 
       name="liveagent.prechat.findorcreate.map:Contact" 
       value="FirstName,contactFirstName;LastName,contactLastName;Email,contactEmail;" />
<input type="hidden" 
       name="liveagent.prechat.findorcreate.map:Case" 
       value="Origin,caseOrigin;Subject,caseSubject;" />

<input type="hidden"

name="liveagent.prechat.findorcreate.map:Contact"

value="FirstName,contactFirstName;LastName,contactLastName;Email,contactEmail;" />

<input type="hidden"

name="liveagent.prechat.findorcreate.map:Case"

value="Origin,caseOrigin;Subject,caseSubject;" />

Once you have the fields mapped you can specify that you want to search for an existing record using the doFind input. If you only want to find exact matches you can use the isExactMatch input. If more than one match is found Salesforce will dispaly a search results list. In the code sample, the Contact’s email is used to search:

<input type="hidden" name="liveagent.prechat.findorcreate.map.doFind:Contact" value="Email,true;" />
<input type="hidden" name="liveagent.prechat.findorcreate.map.isExactMatch:Contact" value="Email,true;" />

1 2	<input type="hidden" name="liveagent.prechat.findorcreate.map.doFind:Contact" value="Email,true;" /> <input type="hidden" name="liveagent.prechat.findorcreate.map.isExactMatch:Contact" value="Email,true;" />

If nothing is found in the search, Salesforce will not automatically create a new record. To do that you must use the doCreate input. If you use both the doFind and the doCreate, Salesforce will attempt to find and if it doesn’t it will create. If it does find it will not create. In the code sample, a Case is always created and a Contact is only created if the doFind doesn’t find one. The doCreate lets you specify which fields you want included on the new record. For instance, you might want to use a field in the doFind that you wouldn’t want on a newly created record. The code from above is:

<input type="hidden" 
       name="liveagent.prechat.findorcreate.map.doCreate:Case" 
       value="Origin,true;Subject,true;" />
<input type="hidden" 
       name="liveagent.prechat.findorcreate.map.doCreate:Contact" 
       value="FirstName,true;LastName,true;Email,true;" />

<input type="hidden"

name="liveagent.prechat.findorcreate.map.doCreate:Case"

value="Origin,true;Subject,true;" />

<input type="hidden"

name="liveagent.prechat.findorcreate.map.doCreate:Contact"

value="FirstName,true;LastName,true;Email,true;" />

You do not have to use the doFind. You could just use the doCreate if you don’t want to search. Likewise, you don’t have to use the doCreate, you could just use the doFind.
You can specify which records should be displayed in the console when found or created with the showOnCreate input. The code from above shows both the Contact and the Case:

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

1 2	<input type="hidden" name="liveagent.prechat.findorcreate.showOnCreate:Contact" value="true" /> <input type="hidden" name="liveagent.prechat.findorcreate.showOnCreate:Case" value="true" />

The Live Chat Transcript Object has Lookup fields to both Case and Contact. Use the saveToTranscript method to have those Lookups set to the found or created records. The code from above is:

<input type="hidden" name="liveagent.prechat.findorcreate.saveToTranscript:Contact" value="Contact" />
<input type="hidden" name="liveagent.prechat.findorcreate.saveToTranscript:Case" value="Case" />

1 2	<input type="hidden" name="liveagent.prechat.findorcreate.saveToTranscript:Contact" value="Contact" /> <input type="hidden" name="liveagent.prechat.findorcreate.saveToTranscript:Case" value="Case" />

Lastly, of course, you want to link the Contact and the Case. The Pre-Chat API has a linkToEntity input that does just that. What’s really cool about this is that it links the Case to a found Contact or a newly created one. The code from above is:

<input type= "hidden" name="liveagent.prechat.findorcreate.linkToEntity:Contact" value="Case,ContactId" />

1	<input type= "hidden" name="liveagent.prechat.findorcreate.linkToEntity:Contact" value="Case,ContactId" />

You need to be careful about how you specify the fields that need to be created. They are case sensitive as @PepeFloyd noted on the SFSE (upvote it!).

Custom Fields

In the above example all of the fields are standard fields on standard objects. If you need to map a custom field, you need to use the API name of the custom field. For example, if you have a custom text field on the Case called Service Tag that has an API name of Service_Tag__c you would map it using Service_Tag__c. The above mapping for the Case would change to the following.

<input type="text" name="liveagent.prechat:caseServiceTag" />

<input type="hidden"
       name="liveagent.prechat.findorcreate.map:Case" 
       value="Origin,caseOrigin;Subject,caseSubject;Service_Tag__c,caseServiceTag;" />

<input type="hidden" 
       name="liveagent.prechat.findorcreate.map.doCreate:Case" 
       value="Origin,true;Subject,true;Service_Tag__c,true;" />

<input type="hidden"

name="liveagent.prechat.findorcreate.map:Case"

value="Origin,caseOrigin;Subject,caseSubject;Service_Tag__c,caseServiceTag;" />

<input type="hidden"

name="liveagent.prechat.findorcreate.map.doCreate:Case"

value="Origin,true;Subject,true;Service_Tag__c,true;" />

Troubleshooting

During the course of development you may run into a few issues. I’ve noted some common ones that I’ve observed below.

Your chat is showing up as offline to the chat customer. It could be that you don’t have any agents online. You must have at least one user in the Service Console with their Live Agent status set to Online. The Live Agent deployment is smart enough to know when no agents are available.
Make sure that you added your domain to the permitted domains in the Deployment configuration. If it isn’t there chat customers will not be able to connect.
If you aren’t using an Online and Offline image, make sure that you’ve edited the Chat Button Code to add online and offline text inside the anchor/hyperlink tag. They default to an HTML comment.
Build your form incrementally, one field/function at a time. The form will not work if you have syntax errors. It’s much easier to pinpoint causes of failure when you build incrementally.
If you are attempting to create a record make sure that you have values for required fields set. If you don’t the record can’t be created.
Lastly, if you are still stuck, you can inspect the requests and responses with the Chrome Developer console. For example, I observed that if the domain hasn’t been permitted the response is “Domain is not whitelisted for this deployment”.

Live Agent also integrates nicely with Salesforce Knowledge!

8 comments:

UnknownJuly 30, 2015 at 2:18 AM
With cloud computing, you eliminate those headaches because you’re not managing hardware and software—that’s the responsibility of an experienced vendor like salesforce.com. The shared infrastructure means it works like a utility: You only pay for what you need, upgrades are automatic, and scaling up or down is easy. Thanks for sharing this.

Salesforce course in chennai
Salesforce developer training in chennai
UnknownSeptember 10, 2015 at 4:15 AM
I have read your blog, it was good to read & I am getting some useful info's through your blog keep sharing... Informatica is an ETL tools helps to transform your old business leads into new vision. Learn informatica training in Chennai from corporate professionals with very good experience in informatica tool.
Regards,
Informatica training center in Chennai|Informatica training in chennai
UnknownNovember 14, 2015 at 11:14 PM
Hi Rajkumar…. Thanks For sharing such a useful post, I hope it’s useful to many individuals for developing their skill to get strong career soon.
Regards,
ccna training in Chennai|ccna training institute in Chennai|ccna institutes in Chennai
UnknownNovember 30, 2015 at 10:19 PM
Data processing is the biggest challenge to veterans since last decade. With the invention of cloud solution the burden about data handling become zero percent(Cloud computing training in chennai). Thanks for providing such an useful content here. The information is explicit and clear(Best Institute for Cloud Computing in Chennai). Keep blogging like this.(Cloud computing course in Chennai)
UnknownDecember 17, 2015 at 1:09 AM
Cloud servers are the best in safe guarding one's information thorugh online. Without this dedicated methodology many companies would have not existed at all. The same though has been furnished above. Thanks for sharing this worth while content in here. Keep writing article like this.

Salesforce course in chennai | Salesforce course in chennai | Salesforce administrator training in chennai
UnknownDecember 22, 2015 at 12:47 AM
I am reading your post from the beginning, it was so interesting to read & I feel thanks to you for posting such a good blog, keep updates regularly.
Regards,
sas training center in Chennai|sas training in Chennai|sas course in Chennai
SALESFORCEJuly 14, 2017 at 4:45 AM
Nowadays, most of the businesses rely on cloud based CRM tool to power their business process. They want to access the business from anywhere and anytime. In such scenarios, salesforce CRM will ensure massive advantage to the business owners.
salesforce form builder
AnonymousDecember 21, 2019 at 1:03 PM
Million Oaks, CALIFORNIA: Sage, 1998. https://imgur.com/a/qg7N7Yq http://r8rmq54g9t.dip.jp https://imgur.com/a/zvZpV7Q https://imgur.com/a/wZtYltu http://ep5350tb8k.dip.jp https://imgur.com/a/hEFSOiR https://imgur.com/a/NpDbKCo

Wednesday, July 2, 2014

How to create cases and contacts from LiveAgent Pre-chat API

Configuration Set Up

Pre-Chat Form Code

Custom Fields

Troubleshooting

8 comments: