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 an SCSPrechatEntity for each Salesforce object (for example, Case or Contact) and instantiate an SCSPrechatEntityField for each field association within that Salesforce object (for example, Subject or LastName).

Each pre-chat entity must map to a pre-chat object (SCSPrechatObject, SCSPrechatTextInputObject, or SCSPrechatPickerObject). The label string in this pre-chat object must be identical to the label used in your SCSPrechatEntityField object.

Use the config object's prechatFields property for the array of your pre-chat objects and the prechatEntities property for the array of your entity objects.

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 code shows how to pass the first and last name to a contact record in your org. This example doesn't involve user input, but you can use SCSPrechatTextInputObject instead of SCSPrechatObject to allow user input.

In Swift:

1// Create pre-chat fields
2let firstNameField = SCSPrechatObject(label: "First Name", value: "Jane")
3let lastNameField = SCSPrechatObject(label: "Last Name", value: "Doe")
4
5// Create entity fields
6let firstNameEntityField = 
7  SCSPrechatEntityField(fieldName: "FirstName", label: "First Name")
8firstNameEntityField.doFind = true
9firstNameEntityField.doCreate = true
10let lastNameEntityField = 
11  SCSPrechatEntityField(fieldName: "LastName", label: "Last Name")
12lastNameEntityField.doFind = true
13lastNameEntityField.doCreate = true
14
15// Create an entity object
16let contactEntity = 
17  SCSPrechatEntity(entityName: "Contact")
18contactEntity.showOnCreate = true
19
20// Add entity fields to entity object
21contactEntity.entityFieldsMaps.add(firstNameEntityField)
22contactEntity.entityFieldsMaps.add(lastNameEntityField)
23
24// Update config object with the pre-chat fields
25config!.prechatFields = [firstNameField, lastNameField]
26    
27// Update config object with the entity mappings
28config!.prechatEntities = [contactEntity]

In Objective-C:

1// Create pre-chat fields
2SCSPrechatObject* firstNameField = [[SCSPrechatObject alloc]
3                                    initWithLabel:@"First Name"
4                                    value:@"Banana"];
5SCSPrechatObject* lastNameField = [[SCSPrechatObject alloc]
6                                   initWithLabel:@"Last Name"
7                                   value:@"Town"];
8
9// Create entity fields
10SCSPrechatEntityField* firstNameEntityField = 
11  [[SCSPrechatEntityField alloc]
12  initWithFieldName:@"FirstName" label:@"First
13Name"];
14firstNameEntityField.doFind = YES;
15firstNameEntityField.doCreate = YES;
16SCSPrechatEntityField* lastNameEntityField = 
17  [[SCSPrechatEntityField alloc]
18  initWithFieldName:@"LastName" label:@"Last Name"];
19lastNameEntityField.doFind = YES;
20lastNameEntityField.doCreate = YES;
21
22// Create an entity object
23SCSPrechatEntity* contactEntity = [[SCSPrechatEntity alloc]
24                                   initWithEntityName:@"Contact"];
25contactEntity.showOnCreate = YES;
26
27// Add entity fields to entity object
28[contactEntity.entityFieldsMaps addObject:firstNameEntityField];
29[contactEntity.entityFieldsMaps addObject:lastNameEntityField];
30
31// Update config object with the pre-chat fields
32NSMutableArray<SCSPrechatObject *> *preChatFields = [NSMutableArray new];
33[preChatFields addObject:firstNameField];
34[preChatFields addObject:lastNameField];
35config.prechatFields = preChatFields;
36
37// Update config object with the entity mappings
38NSMutableArray<SCSPrechatEntity *> *prechatEntities = [NSMutableArray new];
39[prechatEntities addObject:contactEntity];
40config.prechatEntities = prechatEntities;

Entity Configuration Settings

The SCSPrechatEntity and SCSPrechatEntityField classes give you various configuration settings for mapping fields. For example, if a field doesn't exist, you can have the SDK create that field. The following code sample illustrates some basic building blocks when creating an SCSPrechatEntity object.

In Swift:

1// Create an entity
2let entity = SCSPrechatEntity(entityName: "Contact")
3entity.saveToTranscript = "ContactId"    // Save this entity to Transcript.ContactId
4entity.linkToEntityName = "Case"
5entity.linkToEntityField = "ContactId"   // Link this entity to Case.ContactId
6
7// Add an entity field map to our entity
8let entityField = SCSPrechatEntityField(fieldName: "FirstName", label: "First Name")
9entityField.doFind = true                // Attempt to search for that field
10entityField.isExactMatch = true          // Must be an exact match
11entityField.doCreate = true              // Create if not found
12entity.entityFieldsMaps.add(entityField) // Add field to entity map

In Objective-C:

1// Create an entity
2SCSPrechatEntity* entity = [[SCSPrechatEntity alloc] initWithEntityName:@"Contact"];
3entity.saveToTranscript = @"ContactId";    // Save this entity to Transcript.ContactId
4entity.linkToEntityName = @"Case";
5entity.linkToEntityField = @"ContactId";   // Link this entity to Case.ContactId
6  
7// Add an entity field map to our entity
8SCSPrechatEntityField* entityField = [[SCSPrechatEntityField alloc] 
9  initWithFieldName:@"FirstName" label:@"First Name"];
10entityField.doFind = YES;        // Attempt to search for that field
11entityField.isExactMatch = YES;  // Must be an exact match
12entityField.doCreate = YES;      // Create if not found
13[entity.entityFieldsMaps 
14  addObject:entityField];        // Add field to entity map

See the reference documentation for SCSPrechatEntity and SCSPrechatEntityField. Also refer to Chat REST API Data Types for the Entity and EntityFieldsMaps data types, which define the underlying functionality of these SDK objects.

Example

This code sample adds FirstName, LastName, Email to a Contact record and a Subject field to a Case record.

1let config = SCSChatConfiguration(liveAgentPod: "YOUR_POD_NAME",
2                                  orgId: "YOUR_ORG_ID",
3                                  deploymentId: "YOUR_DEPLOYMENT_ID",
4                                  buttonId: "YOUR_BUTTON_ID")
5
6// Create some basic pre-chat fields (with user input)
7let firstNameField = SCSPrechatTextInputObject(label: "First Name")
8firstNameField!.isRequired = true
9let lastNameField = SCSPrechatTextInputObject(label: "Last Name")
10lastNameField!.isRequired = true
11let emailField = SCSPrechatTextInputObject(label: "Email")
12emailField!.isRequired = true
13emailField!.keyboardType = .emailAddress
14emailField!.autocorrectionType = .no
15
16// Create a pre-chat field without user input
17let subjectField = SCSPrechatObject(label: "Subject", value: "Chat Session")
18
19// Create an entity mapping for a Contact record type
20let contactEntity = SCSPrechatEntity(entityName: "Contact")
21contactEntity.saveToTranscript = "Contact"
22contactEntity.linkToEntityName = "Case"
23contactEntity.linkToEntityField = "ContactId"
24
25// Add some field mappings to our Contact entity
26let firstNameEntityField = SCSPrechatEntityField(fieldName: "FirstName", label: "First Name")
27firstNameEntityField.doFind = true
28firstNameEntityField.isExactMatch = true
29firstNameEntityField.doCreate = true
30contactEntity.entityFieldsMaps.add(firstNameEntityField)
31let lastNameEntityField = SCSPrechatEntityField(fieldName: "LastName", label: "Last Name")
32lastNameEntityField.doFind = true
33lastNameEntityField.isExactMatch = true
34lastNameEntityField.doCreate = true
35contactEntity.entityFieldsMaps.add(lastNameEntityField)
36let emailEntityField = SCSPrechatEntityField(fieldName: "Email", label: "Email")
37emailEntityField.doFind = true
38emailEntityField.isExactMatch = true
39emailEntityField.doCreate = true
40contactEntity.entityFieldsMaps.add(emailEntityField)
41
42// Create an entity mapping for a Case record type
43let caseEntity = SCSPrechatEntity(entityName: "Case")
44caseEntity.saveToTranscript = "Case"
45caseEntity.showOnCreate = true
46
47// Add one field mappings to our Case entity
48let subjectEntityField = SCSPrechatEntityField(fieldName: "Subject", label: "Subject")
49subjectEntityField.doCreate = true
50caseEntity.entityFieldsMaps.add(subjectEntityField)
51
52// Update config object with the pre-chat fields
53config!.prechatFields =
54  [firstNameField, lastNameField, emailField, subjectField] as? [SCSPrechatObject]
55
56// Update config object with the entity mappings
57config!.prechatEntities = [contactEntity, caseEntity]
58
59// Start the session!
60ServiceCloud.shared().chatUI.showChat(with: config!, showPrechat: true)

Embedded Service Chat SDK for iOS Developer Guide

Create or Update Salesforce Records from a Chat Session

Overview

Basic Flow

Entity Configuration Settings

Example