--- schema_version: "1" id: b7f289df53d2a38bf66dc0ade93132c9b99ce871fb50874b3040bcd6ef3af30e title: Show Pre-Chat Fields to User collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/service-sdk-ios/guides/live-agent-prechat-fields.md canonical_url: https://developer.salesforce.com/docs/service/service-sdk-ios/guide/live-agent-prechat-fields.html source_site: developer.salesforce.com content_type: documentation content_hash: d82b92b9d9603c3b659cfb1f5abc8818bf26c9f4204bfe2e919bd813697dd50b products: - Embedded Service Chat SDK for iOS Developer Guide - Service Cloud Developer Content --- # Show Pre-Chat Fields to User Before a chat session begins, you can request that the user enter pre-chat fields that are sent to the agent at the start of the 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). To create pre-chat fields, add [`SCSPrechatObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html) instances to the [`prechatFields`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html#/c:objc(cs)SCSChatConfiguration(py)prechatFields>) property on the [`SCSChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) object. 1. Create an [`SCSChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) object. In Swift: ```java let config = SCSChatConfiguration(liveAgentPod: "TO_DO_POD_NAME", // e.g. "d.gla5.gus.salesforce.com" orgId: "TO_DO_ORG_ID", // e.g. "00DB00000003Rxz" deploymentId: "TO_DO_DEPLOYMENT_ID", // e.g. "573B00000005KXz" buttonId: "TO_DO_BUTTON_ID") // e.g. "575C00000004h3m" ``` In Objective-C: ```java SCSChatConfiguration *config = [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"TO_DO_POD_NAME" // e.g. "d.gla5.gus.salesforce.com" orgId:@"TO_DO_ORG_ID" // e.g. "00DB00000003Rxz" deploymentId:@"TO_DO_DEPLOYMENT_ID" // e.g. "573B00000005KXz" buttonId:@"TO_DO_BUTTON_ID"]; // e.g. "575C00000004h3m" ``` See [Configure a Chat Session](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/configure-lac-session.md) on how to configure a chat session. 2. Create [`SCSPrechatObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html) objects for the pre-chat fields you want to specify in your app. There are several types of pre-chat fields: - [`SCSPrechatObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html) does not require user input and can be used to send custom data directly to the agent. - [`SCSPrechatTextInputObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatTextInputObject.html) (a subclass of `SCSPrechatObject`) takes user input from a text field. - [`SCSPrechatPickerObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatPickerObject.html) (a subclass of `SCSPrechatObject`) provides the user with a dropdown list of options. Each type has different properties you can configure. 1. Create objects that don't require user input using [`SCSPrechatObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html). In Swift: ```java let customData = SCSPrechatObject(label: "CustomEmailField", value: "lauren@example.com") ``` In Objective-C: ```java SCSPrechatObject* customData = [[SCSPrechatObject alloc] initWithLabel:@"CustomEmailField" value:@"lauren@example.com"]; ``` When using [`SCSPrechatObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html) to send data without user input, specify both the label and the value. The [`SCSPrechatObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html) base class contains the following properties: - `label`—name of the pre-chat field shown to agent. - `value`—value of the pre-chat field; only use this property if you don't intend for the user to fill in this field. - `displayLabel`—optional display name of the pre-chat field shown to the user if different than the label. - `transcriptFields`—optional array of field identifiers on the `LiveAgentChatTranscript` object in Salesforce. - `displayToAgent`—indicates whether this pre-chat detail is shown to an agent accepting the chat session; defaults to `true`. 2. Create text input objects using [`SCSPrechatTextInputObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatTextInputObject.html). In Swift: ```java // Create a text field let myPrechatField = SCSPrechatTextInputObject(label: "Full Name") ``` In Objective-C: ```java // Create a text field SCSPrechatTextInputObject* myPrechatField = [[SCSPrechatTextInputObject alloc] initWithLabel:@"Full Name"]; ``` When using a [`SCSPrechatTextInputObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatTextInputObject.html), you can control several other properties: - `required`—indicates whether the field is required. - `keyboardType`—provides access to other standard keyboards (such as `UIKeyboardTypeEmailAddress`). - `autocapitalizationType`—controls how text capitalization works. - `autocorrectionType`—controls auto-correction behavior. - `maxLength`—specifies the maximum length of the field - `displayLabel`—optional display name of the pre-chat field shown to the user if different than the label. - `transcriptFields`—optional array of field identifiers on the `LiveAgentChatTranscript` object in Salesforce. - `displayToAgent`—indicates whether this pre-chat detail is shown to an agent accepting the chat session; defaults to `true`. 3. Create dropdown lists using [`SCSPrechatPickerObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatPickerObject.html). In Swift: ```java // Create dropdown choices let statusOptions = NSMutableArray() statusOptions.add(SCSPrechatPickerOption(label:"New Issue", value:"New")) statusOptions.add(SCSPrechatPickerOption(label:"Fixed Issue", value:"Fixed")) // Create a dropdown list with choices let statusPickerField = SCSPrechatPickerObject( label: "Issue Type", options: statusOptions as! [SCSPrechatPickerOption]) ``` In Objective-C: ```java // Create a dropdown list with two choices NSMutableArray *statusOptions = [[NSMutableArray alloc] init]; [statusOptions addObject: [[SCSPrechatPickerOption alloc] initWithLabel:@"New Issue" value:@"New"]]; [statusOptions addObject: [[SCSPrechatPickerOption alloc] initWithLabel:@"Fixed Issue" value:@"Fixed"]]; // Create a dropdown list with choices SCSPrechatPickerObject *picker = [[SCSPrechatPickerObject alloc] initWithLabel:@"Issue Type" options:statusOptions]; ``` When using a [`SCSPrechatPickerObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatPickerObject.html), you can access these properties: - `required`—indicates whether the field is required. - `options`—specifies items in the dropdown list. This property is an array of [`SCSPrechatPickerOption`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatPickerOption.html) objects. - `displayLabel`—optional display name of the pre-chat field shown to the user if different than the label. - `transcriptFields`—optional array of field identifiers on the `LiveAgentChatTranscript` object in Salesforce. - `displayToAgent`—indicates whether this pre-chat detail is shown to an agent accepting the chat session; defaults to `true`. 3. (Optional) Create [`SCSPrechatEntity`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntity.html) objects to associate pre-chat fields with fields from a record in your org. 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`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntity.html) for each Salesforce object (for example, `Case` or `Contact`) and instantiate an [`SCSPrechatEntityField`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntityField.html) for each field association within that Salesforce object (for example, `Subject` or `LastName`). To learn more, see [Create or Update Salesforce Records from a Chat Session](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/live-agent-send-custom-data.md). 4. Update the config object's [`prechatFields`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html#/c:objc(cs)SCSChatConfiguration(py)prechatFields>) property with an array of your pre-chat objects. In Swift: ```java // Add the array of pre-chat fields to the config object config?.prechatFields = myPrechatFields ``` In Objective-C: ```java // Add the array of pre-chat fields to the config object config.prechatFields = myPrechatFields; ``` 5. Show the pre-chat form and start a chat session by calling [`showChat(with:showPrechat:)`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatInterface.html#/c:objc(cs)SCSChatInterface(im)showChatWithConfiguration:showPrechat:>) and specify `true` for whether to show the pre-chat form. 1. If you want to show the pre-chat form and then send those results to the agent when starting a session, call [`showChat(with:showPrechat:)`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatInterface.html#/c:objc(cs)SCSChatInterface(im)showChatWithConfiguration:showPrechat:>). In Swift: ```java // Show the pre-chat form and start a session ServiceCloud.shared().chatUI.showChat(with: config, showPrechat: true) ``` In Objective-C: ```java // Show the pre-chat form and start a session [[SCServiceCloud sharedInstance].chatUI showChatWithConfiguration:config showPrechat: YES]; ``` 2. If you want to programmatically change the pre-chat data before passing it to the org or agent, call the [`showPrechat(withFields:modal:completion:)`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatInterface.html#/c:objc(cs)SCSChatInterface(im)showPrechatWithFields:modal:completion:>) method first. From within the completion block of this method, update the config object's [`prechatFields`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html#/c:objc(cs)SCSChatConfiguration(py)prechatFields>) property and then call [`showChat(with:showPrechat:)`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatInterface.html#/c:objc(cs)SCSChatInterface(im)showChatWithConfiguration:showPrechat:>) and specify `false` for `showPrechat`. For example, the following Swift code asks the user for their first and last name. After the user completes the pre-chat form, the code creates a new field by concatenating the two name fields. When we start the chat session, only this new field is sent to the agent. ```java // Create two text fields let firstNameField = SCSPrechatTextInputObject(label: "First Name") let lastNameField = SCSPrechatTextInputObject(label: "Last Name") let prechatInputFields = [firstNameField, lastNameField] as? [SCSPrechatObject] // Show the pre-chat form... ServiceCloud.shared().chatUI.showPrechat(withFields: prechatInputFields, completion: { (prechatResultFields, completed) in // If the pre-chat form completed successfully... if (completed && prechatResultFields != nil && prechatResultFields!.count >= 2) { // Create the full name from the values of the two pre-chat name fields let fullName = prechatResultFields![0].value + " " + prechatResultFields![1].value // Create a full name field let fullNameField = SCSPrechatObject(label: "Full Name", value: fullName) // Add this new field to the config object // (We DON'T include the original pre-chat fields because we don't need to send them...) config!.prechatFields = [fullNameField] // And now start a chat session (without showing pre-chat) ServiceCloud.shared().chatUI.showChat(with: config!) } else { // TO DO: Handle the scenario where the user cancels out of the pre-chat form } }) ``` ## Example This code sample builds a set of pre-chat fields that are shown to the user. ```java let config = SCSChatConfiguration(liveAgentPod: "YOUR-POD-NAME", orgId: "YOUR-ORG-ID", deploymentId: "YOUR-DEPLOYMENT-ID", buttonId: "YOUR-BUTTON-ID") // Add some required fields let firstNameField = SCSPrechatTextInputObject(label: "First Name") firstNameField!.isRequired = true let lastNameField = SCSPrechatTextInputObject(label: "Last Name") lastNameField!.isRequired = true let emailField = SCSPrechatTextInputObject(label: "Email") emailField!.isRequired = true emailField!.keyboardType = .emailAddress emailField!.autocorrectionType = .no // Add some optional fields let originField = SCSPrechatTextInputObject(label: "Where are you from?") originField!.isRequired = false let phoneField = SCSPrechatTextInputObject(label: "Phone Number") phoneField!.isRequired = false phoneField!.keyboardType = .phonePad let descriptionField = SCSPrechatTextInputObject(label: "Please describe your problem:") descriptionField!.isRequired = false // Add a picklist field let statusOptions = NSMutableArray() statusOptions.add(SCSPrechatPickerOption(label:"New Issue", value:"New")) statusOptions.add(SCSPrechatPickerOption(label:"Fixed Issue", value:"Fixed")) let statusPickerField = SCSPrechatPickerObject(label: "Status", options: statusOptions as NSArray as! [SCSPrechatPickerOption]) statusPickerField!.isRequired = false // Add hidden field containing the subject let subjectField = SCSPrechatObject(label: "Subject", value: "Chat Session") // Create an array of all pre-chat fields let prechatFields: [SCSPrechatObject] = [firstNameField!, lastNameField!, emailField!, originField!, phoneField!, descriptionField!, statusPickerField!, subjectField] // Add the array of pre-chat fields to the config object config?.prechatFields = prechatFields // And NOW show the chat UI ServiceCloud.shared().chatUI.showChat(with: config!, showPrechat: true) ``` With this code, the user sees the following pre-chat UI in their mobile app. ![Pre-chat UI on app](https://developer.salesforce.com/docs/media/service-sdk/ios-chat-prechat-app.png '{"class": "image-sm"}') And the agent sees the following UI from the console. ![Pre-chat UI on console](https://developer.salesforce.com/docs/media/service-sdk/ios-chat-prechat-console.png '{"class": "image-xl"}')