Salesforce Communities & the Live Agent Deployment API
Integrating Live Agent with Salesforce is exceptionally easy once you’ve purchased the licenses and followed the basic setup instructions. Peter Knolle wrote a blog post earlier this year that outlined some of the basics around setup, as well as the usage of the Pre-Chat API that Live Agent offers. However, while working with the Deployment API, I found myself in a pickle trying to figure out why my attempts to customize part of the Service Agent’s experience weren’t working.
Live Agent for Salesforce has two separate APIs, documented in the Live Agent Developer’s Guide: Pre-Chat & Deployment. Pre-Chat allows you to set up a form that a user might fill out prior to connecting with an agent to chat, and then leverage that information to surface content to the Agent or to resolve who the Agent is speaking to. The Deployment API does not rely on a form for the user to fill out; instead, it lets you use Javascript to populate the same content behind the scenes. This is particularly useful when you have enabled Live Agent on an authenticated website where you already know who is making the chat request.
To leverage Live Agent in an authenticated Salesforce Community, there are two main features that I think are required to implement for your Agents.
- Setting the name of the user initiating the chat. This will show in both the screen pop to your agent, as well as in the Chat Transcript.
- Popping open the Community User’s related Contact record, in order to view their metadata, case history, etc.
After pasting the generated Live Agent code into your Visualforce page (which we’ll use as an example), you have the ability to leverage a couple of methods off the liveagent javascript object (which are documented in the Deployment API). The easiest one to use is the setName() method, which will accomplish the first item mentioned above. This is particularly important because otherwise your Agents will be presented with the IP Address of the user, along with the very generic label of Visitor in the chat window. With Visualforce & merge fields, this is simply an exercise of dumping the User’s name into the method as a parameter:
liveagent.setName( '{!$User.FirstName} {!$User.LastName}' ); Where I had some issues was with the second. I found that there were a few examples of how to use the Deployment API for the findOrCreate() method, but there was not much in terms of instructions. The gist of what this method is doing is that you can provide some query criteria for a particular object type, and it will either find a matching record or create a new one (if necessary). Since we are querying for authenticated Users in the system (that have associated Contact records), there is no need to leverage the creation aspect of the method, as we should always be able to find the record by the ContactId field on the User.
Unfortunately, what I didn’t realize was that when using the map() method is looking for a label corresponding to the value, rather than the value itself for the DetailName. What you need to do is define a custom detail, and then reference that in your map.
liveagent.addCustomDetail('<strong>Contact ID</strong>', '{!$User.ContactId}', false);
liveagent.findOrCreate('Contact').map('Id', '<strong>Contact ID</strong>', true, true, false).saveToTranscript('contactId').showOnCreate();
Looking back on the aforementioned documentation after discovering this (both on the Deployment API as well as the Pre-Chat API), it made a lot more sense. I was so focused on assuming the actual value would be the parameter that I misread what the parameter’s description actually said: “The value of the custom detail to map to the corresponding field FieldName”. Hopefully anyone else running into the same issue will find this enlightening, as the debugging tools for Live Agent’s Deployment API was not very helpful for me.