--- schema_version: "1" id: 0cbcbff5722dcc2a12e7981bfe0d8181517e0cfceab35f8dfe1ee39af780d972 title: Configure a Chat Session collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/service-sdk-ios/guides/configure-lac-session.md canonical_url: https://developer.salesforce.com/docs/service/service-sdk-ios/guide/configure-lac-session.html source_site: developer.salesforce.com content_type: documentation content_hash: 61251e5cebc2cbcc54bbee44483f9d1c77493159448ac767ad94b10f8e05b2c7 products: - Embedded Service Chat SDK for iOS Developer Guide - Service Cloud Developer Content --- # Configure a Chat Session Before starting a chat session, you have several ways to configure the session using the `SCSChatConfiguration` object. These configuration settings allow you to specify pre-chat fields, determine whether a session starts minimized or full screen, and get updates about the user's queue position. **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). When you start a chat session, you specify an [`SCSChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) object as one of the arguments. This object contains all the configuration settings necessary for Chat to start a session. To create an [`SCSChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) object, you specify information about your org and deployment. 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" ``` **note:** You can get the required parameters for this method from your Salesforce org. See [Get Chat Settings from Your Org](https://developer.salesforce.com/docs/service/service-sdk-android/guides/shared/live-agent-cloud-setup-get-settings.md). If your Salesforce admin hasn't already set up Chat in Service Cloud or you need more guidance, see [Org Setup for Chat in Lightning Experience with a Guided Flow](https://developer.salesforce.com/docs/service/service-sdk-android/guides/shared/live-agent-cloud-setup.md). However, there are other options you can set using [`SCSChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) at configuration time. The following features are available for configuration: | Property Name | Description | Type & Default Value | | -------------------- | --------------------------------------------------------------------------------------------- | -------------------- | | `allowMinimization` | Indicates whether the user is allowed to minimize the chat session view. | `Bool`: `true`/`YES` | | `allowURLPreview` | Indicates whether the user is shown URL previews when the agent types a URL in the chat feed. | `Bool`: `true`/`YES` | | `defaultToMinimized` | Indicates whether the chat session starts out as a minimized thumbnail view. | `Bool`: `true`/`YES` | **note:** When the minimized view is visible, it displays the number of unread messages. This value represents the total number of bot, agent, and system messages that are unread. | Property Name | Description | Type & Default Value | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | `allowBackgroundExecution` | Indicates whether to allow extended background execution to support active chat sessions. When `true`, active chat sessions can remain in the background for more than three minutes. See `allowBackgroundNotifications` for related functionality. | `Bool`: `true`/`YES` | | `allowBackgroundNotifications` | Indicates whether the session posts local notifications based on chat activity. Requires that `allowBackgroundExecution` is also set to `true`. To learn more, see [Notifications for Chat Activity](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/live-agent-notifications.md). | `Bool`: `true`/`YES` | **note:** When turning on background execution, be sure that Idle Connection Timeout Duration is set in your org. To learn more, see [Chat Deployment Settings](https://help.salesforce.com/articleView?id=service.live_agent_deployment_settings.htm&type=5). | Property Name | Description | Type & Default Value | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | [`prechatEntities`](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)prechatEntities>) | Pre-chat fields are always sent to the agent at the start of the session. 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 an [`SCSPrechatEntityField`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntityField.html) for each field (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). | [`SCSPrechatEntity`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntity.html) array: `nil` | | [`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>) | You can specify both optional and required fields shown to the user before a chat session starts. You can also directly pass data to an agent without requiring any user input. 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. To learn more, see [Show Pre-Chat Fields to User](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/live-agent-prechat-fields.md). | [`SCSPrechatObject`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html) array: `nil` | | Property Name | Description | Type & Default Value | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | | `eventList` | Adds a custom path that displays a custom tile and performs a custom action within your app. To learn more, see [Handle Custom URLs in Chat](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/chat-url-event.md). | `SCSAppEventList` | | [`queueStyle`](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)queueStyle>) | Determines the style of the queue: queue position number (`.position`), estimated wait time (`.estimatedWaitTime`), or no queue information (`.none`). You can subscribe to queue position events using [`session(didUpdateQueuePosition:estimatedWaitTime:)`](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/%3Chttps://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html#/c:objc(pl)SCSChatSessionDelegate(im)session:didUpdateQueuePosition:estimatedWaitTime:>) on [`SCSChatSessionDelegate`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html). To understand the algorithm used for the estimated wait time, see the estimated wait time documentation in the [Chat REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.live_agent_rest.meta/live_agent_rest/live_agent_rest_estimated_wait_time.htm). | `SCSChatConfigurationQueueStyle`: `.position` | | `remoteLoggingEnabled` | Indicates whether session logs are sent for collection. (Logs sent remotely don't collect personal information. Unique IDs are created for tying logs to sessions and those IDs can't be correlated back to specific users.) | `Bool`: `true`/`YES` | | `visitorName` | Name of the chat visitor. This value is used by the Service Cloud console and displayed to the agent. | `String`: "`Visitor`" | When using the estimated wait time, the wait time is shown to the user in minutes. However, you can set the minimum ([`minimumEstimatedWaitTime`](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)minimumEstimatedWaitTime>)) and maximum () wait time values. If the wait time exceeds the maximum value, a generic message appears, which [you can customize](https://developer.salesforce.com/docs/service/service-sdk-ios/guide/localization.md) (using the customizable chat strings in the `ServiceCloud.Chat.Status.EstimatedWait` namespace). When using the queue position number, the queue position is 0 if the agent capacity is greater than or equal to the number of customer requests. Otherwise, the position value represents how far the customer is from getting served by an agent. ```java q = max(n - c, 0) ``` Where: - q is the queue position - n is the position of the customer compared to all waiting customers - c is the total capacity of all agents For example, if the total capacity is 10, the first 10 waiting visitors have a position of 0, the 11th has a position of 1, the 12th has a position of 2, and so on. Once you've fully configured the [`SCSChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) object, you can start the session using the `startSession` method. ## Example The following example configures a session with one pre-chat field and a visitor name "Jane Doe". In Swift: ```java let config = SCSChatConfiguration(liveAgentPod: "YOUR_POD_NAME", orgId: "YOUR_ORG_ID", deploymentId: "YOUR_DEPLOYMENT_ID", buttonId: "YOUR_BUTTON_ID") // Set the visitor name config?.visitorName = "Jane Doe" // Change from queue position to estimated wait time config?.queueStyle = .estimatedWaitTime // Add a required email field (with an email keyboard and no auto-correction) let emailField = SCSPrechatTextInputObject(label: "Email") emailField?.isRequired = true emailField?.keyboardType = .emailAddress emailField?.autocorrectionType = .no config?.prechatFields.append(emailField!) ``` In Objective-C: ```java SCSChatConfiguration *config = [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"YOUR_POD_NAME" orgId:@"YOUR_ORG_ID" deploymentId:@"YOUR_DEPLOYMENT_ID" buttonId:@"YOUR_BUTTON_ID"]; // Set the visitor name config.visitorName = @"Jane Doe"; // Change from queue position to estimated wait time config.queueStyle = SCSChatConfigurationQueueStyleEstimatedWaitTime; // Add a required email field (with an email keyboard and no auto-correction) SCSPrechatTextInputObject* emailField = [[SCSPrechatTextInputObject alloc] initWithLabel:@"Email"]; emailField.required = YES; emailField.keyboardType = UIKeyboardTypeEmailAddress; emailField.autocorrectionType = UITextAutocorrectionTypeNo; [config.prechatFields addObject:emailField]; ```