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.
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.
When you start a chat session, you specify an SCSChatConfiguration object as one of the arguments. This object contains all the configuration settings necessary for Chat to start a session. To create an SCSChatConfiguration object, you specify information about your org and deployment.
In Swift:
In Objective-C:
You can get the required parameters for this method from your Salesforce org. See Get Chat Settings from Your Org. 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.
However, there are other options you can set using SCSChatConfiguration 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 |
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. | Bool: true/YES |
When turning on background execution, be sure that Idle Connection Timeout Duration is set in your org. To learn more, see Chat Deployment Settings.
| Property Name | Description | Type & Default Value |
|---|---|---|
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 for each Salesforce object (for example, Case or Contact) and an SCSPrechatEntityField for each field (for example, Subject or LastName). To learn more, see Create or Update Salesforce Records from a Chat Session. | SCSPrechatEntity array: nil |
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 instances to the prechatFields property on the SCSChatConfiguration object. To learn more, see Show Pre-Chat Fields to User. | SCSPrechatObject 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. | SCSAppEventList |
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:) on SCSChatSessionDelegate. To understand the algorithm used for the estimated wait time, see the estimated wait time documentation in the Chat REST API Developer Guide. | 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) and maximum () wait time values. If the wait time exceeds the maximum value, a generic message appears, which you can customize (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.
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 object, you can start the session using the startSession method.
The following example configures a session with one pre-chat field and a visitor name “Jane Doe”.
In Swift:
In Objective-C: