# 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.

:::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](https://help.salesforce.com/s/articleView?id=service.miaw_intro_landing.htm\&type=5) before that date. Messaging offers many of the [chat features](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm\&type=5) that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement in [Help](https://help.salesforce.com/s/articleView?id=001790618\&type=1).
:::

## Overview

Before reading these instructions, review [Show Pre-Chat Fields to User](/docs/service/service-sdk-android/guide/android-chat-prechat-fields.md) 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`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntity.html) for each Salesforce object (for example, `Case` or `Contact`) and add a [`ChatEntityField`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntityField.html) for each field association within that Salesforce object (for example, `Subject` or `LastName`). After you've built your [`ChatEntity`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntity.html) objects, pass them to your [`ChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/ChatConfiguration.html) builder using the [`chatEntities`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/ChatConfiguration.Builder.html#chatEntities\(java.util.List%3Ccom.salesforce.android.chat.core.model.ChatEntity%3E\)) 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`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/ui/model/PreChatTextInputField.html) instead of [`ChatUserData`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatUserData.html) to allow user input.

In Java:

```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:

```java
// 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`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatUserData.html) objects, create a [`ChatEntity`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntity.html) for each Salesforce object that you want to associate these values with. The [`ChatEntity`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntity.html) object contains a for each field association. When you build this [`ChatEntityField`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntityField.html) object, pass in a reference to the associated object.

In this example, we create two [`ChatEntityField`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntityField.html) objects and one using those two objects.

In Java:

```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:

```java
// 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`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntityField.html) 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`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntity.html) 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`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntity.html) and [`ChatEntityField`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntityField.html). Also refer to [Chat REST API Data Types](https://developer.salesforce.com/docs/atlas.en-us.live_agent_rest.meta/live_agent_rest/live_agent_rest_data_types.htm) for the `Entity` and `EntityFieldsMaps` data types, which define the underlying functionality of these SDK objects.

After you've built your [`ChatEntity`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/model/ChatEntity.html) objects, pass them to your [`ChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/ChatConfiguration.html) builder using the [`chatEntities`](https://forcedotcom.github.io/ServiceSDK-Android/releases/chat/4.3.1/api/reference/com/salesforce/android/chat/core/ChatConfiguration.Builder.html#chatEntities\(java.util.List%3Ccom.salesforce.android.chat.core.model.ChatEntity%3E\)) method.

In Java:

```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:

```java
// 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:

```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:

```java
// 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()
```