Important
The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then. During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement in Help.
Overview
Before reading these instructions, review Show Pre-Chat Fields to User to understand how to create pre-chat fields.
Pre-chat fields are always sent to the agent at the start of the session. But if you want to fill in fields of a particular record, instantiate a ChatEntity for each Salesforce object (for example, Case or Contact) and add a ChatEntityField for each field association within that Salesforce object (for example, Subject or LastName). After you've built your ChatEntity objects, pass them to your ChatConfiguration builder using the chatEntities method.
Note
Case creation does not currently work for Omni-Channel routing without a setup change to your org. To resolve this problem, raise a ticket with Salesforce to ensure that Omni-Channel is enabled to create a Case in your org.
Basic Flow
This sample shows how to create the first and last name to a contact record in your org. This example doesn't involve user input, but you can use PreChatTextInputField instead of ChatUserData to allow user input.
In Java:
// Create chat user data that doesn't require user interaction ChatUserData firstNameData = new ChatUserData("FirstName", "Jane", true); ChatUserData lastNameData = new ChatUserData("LastName", "Doe", true);
In Kotlin:
// Create chat user data that doesn't require user interacti val firstNameData = ChatUserData("FirstName", "Jane", true) val lastNameData = ChatUserData("LastName", "Doe", true)
The first argument is the field label that is displayed to the agent in the transcript. The second argument is the value. The third argument is whether this value is displayed to the agent.
After you create your ChatUserData objects, create a ChatEntity for each Salesforce object that you want to associate these values with. The ChatEntity object contains a for each field association. When you build this ChatEntityField object, pass in a reference to the associated object.
In this example, we create two ChatEntityField objects and one using those two objects.
In Java:
// Build chat entity fields ChatEntityField firstNameField = new ChatEntityField.Builder().doFind(true) .isExactMatch(true) .doCreate(true) .build("FirstName", firstNameData); ChatEntityField lastNameField = new ChatEntityField.Builder().doFind(true) .isExactMatch(true) .doCreate(true) .build("LastName", lastNameData); // Build a chat entity object from those fields // (to map user data to fields in a Salesforce record) ChatEntity contactEntity = new ChatEntity.Builder() .showOnCreate(true) .addChatEntityField(firstNameField) .addChatEntityField(lastNameField) .build("Contact");
In Kotlin:
// Build chat entity fields
val firstNameField = ChatEntityField.Builder().doFind(true)
.isExactMatch(true)
.doCreate(true)
.build("FirstName", firstNameData)
val lastNameField = ChatEntityField.Builder().doFind(true)
.isExactMatch(true)
.doCreate(true)
.build("LastName", lastNameData)
// Build a chat entity object from those fields
// (to map user data to fields in a Salesforce record)
val contactEntity = ChatEntity.Builder()
.showOnCreate(true)
.addChatEntityField(firstNameField)
.addChatEntityField(lastNameField)
.build("Contact")
When creating the ChatEntityField object, you can specify whether to search for that field (doFind), whether the match must be exact (isExactMatch), and whether to create a new record if not found (doCreate). When creating the ChatEntity object, along with the name of the Salesforce object and the list of fields, you can specify whether the contact should pop up for the agent upon creation (showOnCreate). See the reference documentation for ChatEntity and ChatEntityField. Also refer to Chat REST API Data Types for the Entity and EntityFieldsMaps data types, which define the underlying functionality of these SDK objects.
After you've built your ChatEntity objects, pass them to your ChatConfiguration builder using the chatEntities method.
In Java:
// Create the chat configuration builder final ChatConfiguration.Builder chatConfigurationBuilder = new ChatConfiguration.Builder(ORG_ID, BUTTON_ID, DEPLOYMENT_ID, LIVE_AGENT_POD); // Add user data and entities chatConfigurationBuilder .chatUserData(firstNameData, lastNameData) .chatEntities(contactEntity); // Build the chat configuration object ChatConfiguration chatConfiguration = chatConfigurationBuilder.build();
In Kotlin:
// Create the chat configuration builder
val chatConfigurationBuilder = ChatConfiguration.Builder(ORG_ID, BUTTON_ID,
DEPLOYMENT_ID, LIVE_AGENT_POD)
// Add user data and entities
chatConfigurationBuilder
.chatUserData(firstNameData, lastNameData)
.chatEntities(contactEntity)
// Build the chat configuration object
val chatConfiguration = chatConfigurationBuilder.build()
Example
This code sample adds FirstName, LastName, Email to a Contact record and a Subject field to a Case record.
In Java:
// Create some hidden fields with specific values ChatUserData firstNameData = new ChatUserData( "FirstName", "Jane", true); ChatUserData lastNameData = new ChatUserData( "LastName", "Doe", true); ChatUserData emailData = new ChatUserData( "Email", "jane.doe@salesforce.com", true); ChatUserData subjectData = new ChatUserData( "Subject", "Chat Session", true); // Map Subject to a field in a Case record ChatEntity caseEntity = new ChatEntity.Builder() .showOnCreate(true) .linkToTranscriptField("Case") .addChatEntityField( new ChatEntityField.Builder() .doFind(true) .isExactMatch(true) .doCreate(true) .build("Subject", subjectData)) .build("Case"); // Map FirstName, LastName, and Email to fields in a Contact record ChatEntity contactEntity = new ChatEntity.Builder() .showOnCreate(true) .linkToTranscriptField("Contact") .linkToAnotherSalesforceObject(caseEntity, "ContactId") .addChatEntityField( new ChatEntityField.Builder() .doFind(true) .isExactMatch(true) .doCreate(true) .build("FirstName", firstNameData)) .addChatEntityField( new ChatEntityField.Builder() .doFind(true) .isExactMatch(true) .doCreate(true) .build("LastName", lastNameData)) .addChatEntityField( new ChatEntityField.Builder() .doFind(true) .isExactMatch(true) .doCreate(true) .build("Email", emailData)) .build("Contact"); // Create the chat configuration builder final ChatConfiguration.Builder chatConfigurationBuilder = new ChatConfiguration.Builder(ORG_ID, BUTTON_ID, DEPLOYMENT_ID, LIVE_AGENT_POD); // Add user data and entities chatConfigurationBuilder .chatUserData(firstNameData, lastNameData, emailData, subjectData) .chatEntities(caseEntity, contactEntity); // Build the chat configuration object ChatConfiguration chatConfiguration = chatConfigurationBuilder.build();
In Kotlin:
// Create chat user data that doesn't require user interaction
val firstNameData = ChatUserData(
"FirstName", "Jane", true)
val lastNameData = ChatUserData(
"LastName", "Doe", true)
val emailData = ChatUserData(
"Email", "jane.doe@salesforce.com", true)
val subjectData = ChatUserData(
"Subject", "Chat Session", true)
// Map Subject to a field in a Case record
val caseEntity = ChatEntity.Builder()
.showOnCreate(true)
.linkToTranscriptField("Case")
.addChatEntityField(
ChatEntityField.Builder()
.doFind(true)
.isExactMatch(true)
.doCreate(true)
.build("Subject", subjectData))
.build("Case")
// Map FirstName, LastName, and Email to fields in a Contact record
val contactEntity = ChatEntity.Builder()
.showOnCreate(true)
.linkToTranscriptField("Contact")
.linkToAnotherSalesforceObject(caseEntity, "ContactId")
.addChatEntityField(
ChatEntityField.Builder()
.doFind(true)
.isExactMatch(true)
.doCreate(true)
.build("FirstName", firstNameData))
.addChatEntityField(
ChatEntityField.Builder()
.doFind(true)
.isExactMatch(true)
.doCreate(true)
.build("LastName", lastNameData))
.addChatEntityField(
ChatEntityField.Builder()
.doFind(true)
.isExactMatch(true)
.doCreate(true)
.build("Email", emailData))
.build("Contact")
// Create the chat configuration builder
val chatConfigurationBuilder = ChatConfiguration.Builder(ORG_ID, BUTTON_ID,
DEPLOYMENT_ID, LIVE_AGENT_POD)
// Add user data and entities
chatConfigurationBuilder
.chatUserData(firstNameData, lastNameData, emailData, subjectData)
.chatEntities(caseEntity, contactEntity)
// Build the chat configuration object
val chatConfiguration = chatConfigurationBuilder.build()