Loading

Salesforce Live Agent: Pass Custom Values from Start Chat Button to Pre-Chat Form Using liveagent.addCustomDetail()

Publiceringsdatum: Jun 2, 2026
Beskrivning

In Salesforce Live Agent (referred to as Salesforce Chat in Lightning Experience), you may need to pass data from the web page hosting the Start Chat button to the pre-chat form that opens when a visitor starts a chat session. For example, if a customer is browsing a specific product page, you may want to pre-populate the pre-chat form with the product name, customer account number, or other context.

Note: Live Agent settings are only available in Salesforce Classic. If you are using Lightning Experience, switch back to Salesforce Classic to access Live Agent settings.


Using browser cookies is not a reliable method for passing values between the chat button page and the pre-chat form when these are hosted on different domains (for example, a custom company domain and a Force.com domain). Browsers prevent one domain from accessing cookies set by another domain for security reasons. The liveagent.addCustomDetail() JavaScript API provides a reliable cross-domain alternative.

NOTE: Live Agent settings are only available in Classic. If you're using Lightning, you'll need to switch back to Salesforce Classic to access the settings.

Lösning

Step 1: Add Custom Details on the Page Hosting the Start Chat Button

On the web page where the Start Chat button and Live Agent deployment code are embedded, call liveagent.addCustomDetail('labelName', 'value') in JavaScript before the chat session is initiated. Replace 'labelName' with a unique string identifier for the detail (for example, 'productName') and 'value' with the data you want to pass (for example, a product name or customer ID).


This method attaches the custom detail to the chat session. The value is also stored in the chat transcript for later reference.

Step 2: Access Custom Details in the Pre-Chat Form

On the pre-chat form page, include the Live Agent prechat JavaScript library. Then call liveagent.details.preChatInit('chatURL', 'callbackFunctionName'), where 'chatURL' is the same chat URL used in your Live Agent deployment code (for example, `'<REDACTED>).
When the pre-chat form loads, Salesforce calls your callback function and passes a details object. This object contains a customDetails array. Iterate over the array to find items by their label string and retrieve their associated values.


Important: liveagent.details.preChatInit() is processed asynchronously. Do not submit the pre-chat form or perform any action that depends on the custom details before the callback function has completed and received its response. Submitting the form before the preChatInit response arrives results in the custom detail values not being passed to the chat session.

Visitor Name Behavior

When passing a Visitor Name to a pre-chat form, note that there are multiple methods for setting the visitor's name. If you use the setName() method in the deployment code on the Start Chat button page AND also set the Visitor Name in the pre-chat form, the pre-chat form value overrides the deployment code value. Set the Visitor Name in only one location — either in the deployment code or in the pre-chat form — to ensure the value is applied as intended.


Resources

Knowledge-artikelnummer

000387654

 
Laddar
Salesforce Help | Article