Create or Update Salesforce Records from a Chat Session

When a chat session begins, you can create or find records within your org and pass this information to the agent. Using this technique, your agent can immediately have all the context they need for an effective chat session.

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.

Important

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.

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.

Note

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:

1// Create chat user data that doesn't require user interaction
2ChatUserData firstNameData = new ChatUserData("FirstName", "Jane", true);
3ChatUserData lastNameData = new ChatUserData("LastName", "Doe", true);

In Kotlin:

1// Create chat user data that doesn't require user interacti
2val firstNameData = ChatUserData("FirstName", "Jane", true)
3val 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:

1// Build chat entity fields
2ChatEntityField firstNameField =
3  new ChatEntityField.Builder().doFind(true)
4                               .isExactMatch(true)
5                               .doCreate(true)
6                               .build("FirstName", firstNameData);
7ChatEntityField lastNameField =
8  new ChatEntityField.Builder().doFind(true)
9                               .isExactMatch(true)
10                               .doCreate(true)
11                               .build("LastName", lastNameData);
12
13// Build a chat entity object from those fields
14// (to map user data to fields in a Salesforce record)
15ChatEntity contactEntity = new ChatEntity.Builder()
16  .showOnCreate(true)
17  .addChatEntityField(firstNameField)
18  .addChatEntityField(lastNameField)
19  .build("Contact");

In Kotlin:

1// Build chat entity fields
2val firstNameField = ChatEntityField.Builder().doFind(true)
3                                              .isExactMatch(true)
4                                              .doCreate(true)
5                                              .build("FirstName", firstNameData)
6val lastNameField = ChatEntityField.Builder().doFind(true)
7                                             .isExactMatch(true)
8                                             .doCreate(true)
9                                             .build("LastName", lastNameData)
10
11// Build a chat entity object from those fields
12// (to map user data to fields in a Salesforce record)
13val contactEntity = ChatEntity.Builder()
14    .showOnCreate(true)
15    .addChatEntityField(firstNameField)
16    .addChatEntityField(lastNameField)
17    .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:

1// Create the chat configuration builder
2final ChatConfiguration.Builder chatConfigurationBuilder =
3  new ChatConfiguration.Builder(ORG_ID, BUTTON_ID,
4                                DEPLOYMENT_ID, LIVE_AGENT_POD);
5
6// Add user data and entities
7chatConfigurationBuilder
8  .chatUserData(firstNameData, lastNameData)
9  .chatEntities(contactEntity);
10
11// Build the chat configuration object
12ChatConfiguration chatConfiguration = chatConfigurationBuilder.build();

In Kotlin:

1// Create the chat configuration builder
2val chatConfigurationBuilder = ChatConfiguration.Builder(ORG_ID, BUTTON_ID,
3    DEPLOYMENT_ID, LIVE_AGENT_POD)
4
5// Add user data and entities
6chatConfigurationBuilder
7    .chatUserData(firstNameData, lastNameData)
8    .chatEntities(contactEntity)
9
10// Build the chat configuration object
11val 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:

1// Create some hidden fields with specific values
2ChatUserData firstNameData = new ChatUserData(
3  "FirstName", "Jane", true);
4ChatUserData lastNameData = new ChatUserData(
5  "LastName", "Doe", true);
6ChatUserData emailData = new ChatUserData(
7  "Email", "jane.doe@salesforce.com", true);
8ChatUserData subjectData = new ChatUserData(
9  "Subject", "Chat Session", true);
10
11// Map Subject to a field in a Case record
12ChatEntity caseEntity = new ChatEntity.Builder()
13  .showOnCreate(true)
14  .linkToTranscriptField("Case")
15  .addChatEntityField(
16    new ChatEntityField.Builder()
17          .doFind(true)
18          .isExactMatch(true)
19          .doCreate(true)
20          .build("Subject", subjectData))
21  .build("Case");
22
23// Map FirstName, LastName, and Email to fields in a Contact record
24ChatEntity contactEntity = new ChatEntity.Builder()
25  .showOnCreate(true)
26  .linkToTranscriptField("Contact")
27  .linkToAnotherSalesforceObject(caseEntity, "ContactId")
28  .addChatEntityField(
29    new ChatEntityField.Builder()
30          .doFind(true)
31          .isExactMatch(true)
32          .doCreate(true)
33          .build("FirstName", firstNameData))
34  .addChatEntityField(
35    new ChatEntityField.Builder()
36          .doFind(true)
37          .isExactMatch(true)
38          .doCreate(true)
39          .build("LastName", lastNameData))
40  .addChatEntityField(
41    new ChatEntityField.Builder()
42          .doFind(true)
43          .isExactMatch(true)
44          .doCreate(true)
45          .build("Email", emailData))
46  .build("Contact");
47
48// Create the chat configuration builder
49final ChatConfiguration.Builder chatConfigurationBuilder =
50  new ChatConfiguration.Builder(ORG_ID, BUTTON_ID,
51                                DEPLOYMENT_ID, LIVE_AGENT_POD);
52
53// Add user data and entities
54chatConfigurationBuilder
55  .chatUserData(firstNameData, lastNameData, emailData, subjectData)
56  .chatEntities(caseEntity, contactEntity);
57
58// Build the chat configuration object
59ChatConfiguration chatConfiguration = chatConfigurationBuilder.build();

In Kotlin:

1// Create chat user data that doesn't require user interaction
2val firstNameData = ChatUserData(
3    "FirstName", "Jane", true)
4val lastNameData = ChatUserData(
5    "LastName", "Doe", true)
6val emailData = ChatUserData(
7    "Email", "jane.doe@salesforce.com", true)
8val subjectData = ChatUserData(
9    "Subject", "Chat Session", true)
10
11// Map Subject to a field in a Case record
12val caseEntity = ChatEntity.Builder()
13    .showOnCreate(true)
14    .linkToTranscriptField("Case")
15    .addChatEntityField(
16        ChatEntityField.Builder()
17          .doFind(true)
18          .isExactMatch(true)
19          .doCreate(true)
20          .build("Subject", subjectData))
21    .build("Case")
22
23// Map FirstName, LastName, and Email to fields in a Contact record
24val contactEntity = ChatEntity.Builder()
25    .showOnCreate(true)
26    .linkToTranscriptField("Contact")
27    .linkToAnotherSalesforceObject(caseEntity, "ContactId")
28    .addChatEntityField(
29        ChatEntityField.Builder()
30          .doFind(true)
31          .isExactMatch(true)
32          .doCreate(true)
33          .build("FirstName", firstNameData))
34    .addChatEntityField(
35        ChatEntityField.Builder()
36          .doFind(true)
37          .isExactMatch(true)
38          .doCreate(true)
39          .build("LastName", lastNameData))
40    .addChatEntityField(
41        ChatEntityField.Builder()
42          .doFind(true)
43          .isExactMatch(true)
44          .doCreate(true)
45          .build("Email", emailData))
46    .build("Contact")
47
48// Create the chat configuration builder
49val chatConfigurationBuilder = ChatConfiguration.Builder(ORG_ID, BUTTON_ID,
50    DEPLOYMENT_ID, LIVE_AGENT_POD)
51
52// Add user data and entities
53chatConfigurationBuilder
54    .chatUserData(firstNameData, lastNameData, emailData, subjectData)
55    .chatEntities(caseEntity, contactEntity)
56
57// Build the chat configuration object
58val chatConfiguration = chatConfigurationBuilder.build()