LiveAgent Chat with External ID

Question

I am integrating a third-party site with Salesforce LiveAgent to include passing in an external ID for a Contact record.

Following the instructions at this site I have a simple web page set up (omitting irrelevant portions, IDs and URLs sanitized):

<script type="text/javascript" src="https://XXXXXX.salesforceliveagent.com/content/g/js/31.0/deployment.js"></script>
<script type="text/javascript">
  // What do I do with this variable?
  var externalId = ...;

  if (!window._laq) { window._laq = []; }
  window._laq.push(function(){
    liveagent.showWhenOnline('XXXXXXXXXXXXXXX', document.getElementById('liveagent_button_online'));
    liveagent.showWhenOffline('XXXXXXXXXXXXXXX', document.getElementById('liveagent_button_offline'));
  });
</script>
<script type="text/javascript">
  liveagent.init('https://XXXXXX.salesforceliveagent.com/chat', 'XXXXXXXXXXXXXXX', 'XXXXXXXXXXXXXXX');
</script>

<div><a id="liveagent_button_online" href="javascript://Chat" style="display: none;"
    onclick="liveagent.startChat('XXXXXXXXXXXXXXX')">Chat is Online, click here to initiate a chat.</a></div>
<div id="liveagent_button_offline" style="display: none;">Chat is currently offline.</div>

This works: it brings up a chat window and it connects correctly. However, I need to pass the externalId variable into LiveAgent somewhere: this functionality is not covered by any documentation or tutorial that I can find.

How do I pass the external ID through the JavaScript API? If there is a way in Apex to have Salesforce automatically pull up the Contact based on a field name/value as a side effect that would be a nice bonus, but technically beyond the scope of this question.

Answer 1

If you are not using a pre-chat form, you need to use the Deployment API. See the example provided in the section called "Deployment API Code Sample" in the Live Agent Developer Guide, see the usage of the addCustomDetail method, you can use it to pass information to the chat or to search/create records based on custom information.

<script type='text/javascript'>
  // An auto query that searches contacts whose email field matches "john@acme.com"
  liveagent.addCustomDetail('Contact E-mail', 'john@acme.com');
  liveagent.findOrCreate('Contact').map('Email','Contact E-mail',true,false,false);  
  // A fast-fill to populate a contact’s name with "John Doe"
  liveagent.addCustomDetail('Contact Name', 'John Doe');
  liveagent.findOrCreate('Contact').map('FirstName','Contact Name',false,false,false);
  // Saves the custom detail to a custom field on LiveChatTranscript at the end of a chat
  liveagent.addCustomDetail('Company', 'Acme').saveToTranscript('Company__c');
  // Overrides the display name of the visitor in the agent console when engaged in a chat
  liveagent.setName('John Doe');

  liveagent.init('https://d.la1s1.salesforceliveagent.com/chat', '572D0000000002R',
'00DD0000000JXbY');
</script>