LiveAgent Chat with External ID

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=""></script>
<script type="text/javascript">
  // What do I do with this variable?
  var externalId = ...;

  if (!window._laq) { window._laq = []; }
    liveagent.showWhenOnline('XXXXXXXXXXXXXXX', document.getElementById('liveagent_button_online'));
    liveagent.showWhenOffline('XXXXXXXXXXXXXXX', document.getElementById('liveagent_button_offline'));
<script type="text/javascript">

<div><a id="liveagent_button_online" href="javascript://Chat" rel="nofollow noreferrer noopener" 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.


Thank you for visiting the Q&A section on Magenaut. Please note that all the answers may not help you solve the issue immediately. So please treat them as advisements. If you found the post helpful (or not), leave a comment & I’ll get back to you as soon as possible.

Method 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 "<a href="" class="__cf_email__" data-cfemail="2a404542446a4b49474f04494547">[email protected]</a>"
  liveagent.addCustomDetail('Contact E-mail', '<a href="" class="__cf_email__" data-cfemail="563c393e381637353b337835393b">[email protected]</a>');
  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('', '572D0000000002R',

All methods was sourced from or, is licensed under cc by-sa 2.5, cc by-sa 3.0 and cc by-sa 4.0

0 0 votes
Article Rating
Notify of

Inline Feedbacks
View all comments
Would love your thoughts, please comment.x