# legacydeveloper Service Sdk Ios - Full Documentation # Accessibility with the for iOS for iOS The Service Chat SDK is accessible to customers that use a screen reader. Depending on your needs, you can also change some settings to expand accessibility. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). ## Disable the Minimized View in Chat By default, a chat session starts out as a minimized, thumbnail view that you tap to open. This minimized view is not optimal for accessibility because a visually impaired person could have trouble locating the thumbnail. To improve accessibility, we suggest starting the session in the full-screen view. When creating the [SCSChatConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) object, set allowMinimization and defaultToMinimized to false. let config = SCSChatConfiguration(liveAgentPod: "YOUR\_POD\_NAME", orgId: "YOUR\_ORG\_ID", deploymentId: "YOUR\_DEPLOYMENT\_ID", buttonId: "YOUR\_BUTTON\_ID") config?.allowMinimization = false config?.defaultToMinimized = false See [Configure a Chat Session](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/configure_lac_session.htm "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."). ## Contrast Ratio Considerations By default, we brand the SDK using a 4.2 contrast ratio. You can customize the colors to increase this contrast ratio. See [Customize Colors with the](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/customize_colors.htm "Customize the colors by defining the branding token colors used throughout the interface."). ## Dynamic Text Warning When changing the iOS text size, the Apple Accessibility Inspector displays the following warning: “Dynamic Text font sizes are unsupported.” Dynamic text is supported, but it requires restarting the app after changing the font size. # Add the Service SDK Frameworks Manually Add the SDK frameworks by manually embedding the appropriate frameworks. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### Note If you are using Xcode 12.3 or later, you must install the SDK using XCFramework files. 1. Download the SDK frameworks from the [Service Chat SDK download page](https://github.com/forcedotcom/ServiceSDK-iOS/wiki/Get-the-iOS-SDK). 2. Embed the relevant Service Chat SDK frameworks into your project. You can find the framework files within the Frameworks folder. Specifically, the following frameworks are available for you to use: | Framework | Description | | --- | --- | | ServiceCore | Contains all the common components used by the Service SDK. | | ServiceChat | Contains access to the Chat features of the SDK. | Add the relevant frameworks to the **Frameworks, Libraries, and Embedded Content** section of the **General** tab for your target app. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### Important Before embedding a framework into your project, be sure to copy the framework file into your project folder (or another location found in the framework search path). If Xcode can’t find the framework, you won’t be able to access its contents in your code. Once you've added the SDK frameworks, proceed with [the installation instructions](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/ios_sdk_install_overview.htm "Before you can use the iOS SDK, install the SDK and configure your project."). # Add the Service SDK Frameworks with CocoaPods Add the SDK frameworks using CocoaPods, a developer tool that automatically manages dependencies. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). 1. If you haven't already done so, install the [CocoaPods](https://cocoapods.org/) gem and initialize the CocoaPods main repository. sudo gem install cocoapods pod setup ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### Note The minimum supported version of CocoaPods is 1.0.1. If you're not sure what version you have, use pod --version to check the version number. 2. If you already have [CocoaPods](https://cocoapods.org/) installed, update your pods to the latest version. pod update 3. Change to the root directory of your application project. 4. Create or edit a file named Podfile that contains the Service Chat SDK dependency. 1. If you want to install the complete Service Chat SDK, update your Podfile to include ServiceSDK. source 'https://github.com/CocoaPods/Specs.git' source 'https://github.com/goinstant/pods-specs-public' # To use the SDK (with all components) target '' do pod 'ServiceSDK' end 2. If you want to install a single Service Chat SDK component, create a similar Podfile to the one specified above, but only include the desired pod. | Feature | Pod name | | --- | --- | | Chat | ServiceSDK/Chat | For example, the following Podfile installs Chat. source 'https://github.com/CocoaPods/Specs.git' source 'https://github.com/goinstant/pods-specs-public' # To use Chat target '' do pod 'ServiceSDK/Chat' end If you don't specify a version number, you automatically get the latest version of that component. If you want to add a specific version to your component, be sure to add the version number of the Service Chat SDK and _not_ the version number of the individual component. 5. Run the CocoaPods installer. pod install This command generates a .xcworkspace file for you with all the dependencies included. ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### Note If you run into issues installing or updating the SDK, clear the local CocoaPods cache and then perform a pod update. 6. Open the .xcworkspace file that CocoaPods generated and continue with the installation process. ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### Note Be sure to open the .xcworkspace file (which includes all the dependencies) and _not_ the .xcodeproj file. Once you've added the SDK frameworks, proceed with [the installation instructions](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/ios_sdk_install_overview.htm "Before you can use the iOS SDK, install the SDK and configure your project."). # Additional Resources If you’re looking for other resources, check out this list of links to related documentation. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). - Embedded Service Chat SDK for Mobile Apps Resources - [Service Chat SDK Developer Center](https://developer.salesforce.com/developer-centers/service-cloud/sdk/) - Service Chat SDK [Trailhead Learning Module](https://trailhead.salesforce.com/modules/service_snap-ins_mobile_apps) - iOS: [Release Notes](https://github.com/forcedotcom/ServiceSDK-iOS/releases), [Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_ios_dev_guide.htm), [Reference Docs](https://forcedotcom.github.io/ServiceSDK-iOS/), [Examples](https://github.com/forcedotcom/ServiceSDK-iOS/tree/master/Examples) - Android: [Release Notes](https://github.com/forcedotcom/ServiceSDK-Android/releases), [Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_android.meta/service_sdk_android/servicesdk_android_dev_guide.htm), [Reference Docs](https://forcedotcom.github.io/ServiceSDK-Android/), [Examples](https://github.com/forcedotcom/ServiceSDK-Android/tree/master/Examples) - General Resources - [Service Cloud Developer Center](https://developer.salesforce.com/developer-centers/service-cloud/) - [Salesforce Developer Documentation](https://developer.salesforce.com/docs/) - [Salesforce Help](https://help.salesforce.com/apex/Help_Home) # Agent Availability Check Always Fails What to look into when agent availability fails. If you use the [Permitted Domains setting in your Chat deployment](https://help.salesforce.com/articleView?id=live_agent_deployment_settings.htm&type=0&language=en_US), you’ll get unreliable information from the chat availability check in the SDK. For instance, the agent availability status may always return false. If you want to use Permitted Domains for your web chat deployment, we strongly advise that you create a separate deployment for the Service SDK. # Authentication with the for iOS for iOS The Service Chat SDK provides an authentication mechanism that allows your users to access user-specific information in Service Cloud. To authenticate, create an SCSAuthenticationSettings object and pass it to the SDK. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). ## Authentication Settings Authentication with the Service Chat SDK uses an [SCSAuthenticationSettings](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSAuthenticationSettings.html) object. Create this object with a client ID and a dictionary containing authentication settings. This authentication settings dictionary must contain a URL for your org (SCSOAuth2JSONKeyInstanceUrl) and an access token (SCSOAuth2JSONKeyAccessToken). If your OAuth2 flow supports refresh tokens, include a refresh token (SCSOAuth2JSONKeyRefreshToken) to the authentication settings. In Swift: // Specify auth info let myClientId: String = "CLIENT\_ID\_VALUE" let authDictionary: \[SCSOAuth2JSONKey: String\] = \[ .instanceUrl : "https://MyDomainName.my.salesforce.com", .accessToken : "ACCESS\_TOKEN\_VALUE" \] // Create auth settings object let authSettings = SCSAuthenticationSettings(oauth2: authDictionary, clientId: myClientId) In Objective-C: // Specify auth info NSString \*myClientId = @"CLIENT\_ID\_VALUE"; NSDictionary \*authDictionary = @{ SCSOAuth2JSONKeyInstanceUrl : @"https://URL\_FOR\_YOUR\_ORG.com", SCSOAuth2JSONKeyAccessToken : @"ACCESS\_TOKEN\_VALUE" }; // Create auth settings object SCSAuthenticationSettings \*authSettings = \[\[SCSAuthenticationSettings alloc\] initWithOAuth2Dictionary: authDictionary clientId: myClientId\]; If you're using the [Salesforce Mobile SDK](https://developer.salesforce.com/page/Mobile_SDK), we provide a helper method that allows you to construct an [SCSAuthenticationSettings](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSAuthenticationSettings.html) object directly from the Mobile SDK user account. You can use this sample code after you've successfully logged in a user. In Swift: // Get user account info from the Salesforce Mobile SDK let identity: SFUserAccountIdentity = SFUserAccountIdentity(userId: myUserId, orgId: myOrgId) let account: SFUserAccount = SFUserAccountManager.sharedInstance().userAccount(forUserIdentity: identity)! // Create auth settings object from SFUserAccount let authSettings = SCSAuthenticationSettings(mobileSDK: account) In Objective-C: // Get user account info from the Salesforce Mobile SDK SFUserAccountIdentity \*identity = \[SFUserAccountIdentityClass identityWithUserId:myUserId orgId:myOrgId\]; SFUserAccount \*account = \[\[SFUserAccountManagerClass sharedInstance\] userAccountForUserIdentity:identity\]; // Create auth settings object from SFUserAccount SCSAuthenticationSettings \*authSettings = \[\[SCSAuthenticationSettings alloc\] initWithMobileSDKAccount:account\]; ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### Note For developers who plan to use the [Salesforce Mobile SDK](https://developer.salesforce.com/page/Mobile_SDK) for authentication, the [Mobile SDK Developer’s Guide](https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/intro.htm?search_text=SFUserAccount) contains [authentication](https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/intro_oauth.htm) instructions. If you're using a Salesforce Experience Cloud site, be sure to configure the login endpoint as described in the Salesforce Mobile SDK documentation ([Configure the Login Endpoint](https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/communities_login_endpoint.htm)). This documentation describes how to use the SFDCOAuthLoginHost property in your info.plist file to create a custom login URI. If you plan to use remote push notification to alert the user when an event occurs in your org, call registerForPushNotifications on the [SCSAuthenticationSettings](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSAuthenticationSettings.html) object. To learn more, see [Notifications with the for iOS for iOS](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/ios_push_notifications.htm "The Service Chat SDK can display notifications for activity related to Chat."). However you create an [SCSAuthenticationSettings](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSAuthenticationSettings.html) object, pass it to the Service Chat SDK during the authentication flow. ## Authentication Flow You can either authenticate on-demand when the SDK calls [serviceCloud(shouldAuthenticateServiceType:completion:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html#/c:objc\(pl\)SCServiceCloudDelegate\(im\)serviceCloud:shouldAuthenticateServiceType:completion:) in your [SCServiceCloudDelegate](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html) implementation, or you can authenticate explicitly (that is, before the app attempts to show the relevant UI) using the [setAuthenticationSettings(settings:forServiceType:completion:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html#/c:objc\(cs\)SCServiceCloud\(im\)setAuthenticationSettings:forServiceType:completion:) method in the [ServiceCloud](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html) shared instance. With on-demand authentication, you perform the authentication asynchronously, after the SDK calls your [serviceCloud(shouldAuthenticateServiceType:completion:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html#/c:objc\(pl\)SCServiceCloudDelegate\(im\)serviceCloud:shouldAuthenticateServiceType:completion:) delegate method. Once authenticated, pass the [SCSAuthenticationSettings](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSAuthenticationSettings.html) object to the completion block that you're given in the [serviceCloud(shouldAuthenticateServiceType:completion:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html#/c:objc\(pl\)SCServiceCloudDelegate\(im\)serviceCloud:shouldAuthenticateServiceType:completion:) method. The following sequence diagram illustrates the basic authentication flow for on-demand authentication. On-Demand Authentication ![OAuth on demand diagram](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/ios-oauth-diagram-on-demand.png) Alternatively, you can explicitly authenticate before any UI appears that requires authentication. Call the [setAuthenticationSettings(settings:forServiceType:completion:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html#/c:objc\(cs\)SCServiceCloud\(im\)setAuthenticationSettings:forServiceType:completion:) method in the [ServiceCloud](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html) shared instance using the [SCSAuthenticationSettings](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSAuthenticationSettings.html) object. The following sequence diagram illustrates the authentication flow for explicit authentication. Explicit Authentication![OAuth explicit diagram](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/ios-oauth-diagram-explicit.png) To programmatically log out a user, call [setAuthenticationSettings(settings:forServiceType:completion:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html#/c:objc\(cs\)SCServiceCloud\(im\)setAuthenticationSettings:forServiceType:completion:) using nil for the [SCSAuthenticationSettings](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSAuthenticationSettings.html) argument. ## Error Conditions Implement [serviceCloud(authenticationFailed:forServiceType:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html#/c:objc\(pl\)SCServiceCloudDelegate\(im\)serviceCloud:authenticationFailed:forServiceType:) in your [SCServiceCloudDelegate](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html) object to handle error conditions. The SDK calls this method if the access token expires, and for any other scenario that results in an authentication failure. If you return true or YES, the SDK assumes that you want to proceed, and it subsequently calls [serviceCloud(shouldAuthenticateServiceType:completion:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html#/c:objc\(pl\)SCServiceCloudDelegate\(im\)serviceCloud:shouldAuthenticateServiceType:completion:) to give you a chance to send updated authentication information. If you return false or NO, the SDK goes back to the guest user state. ## Sample Code The following sample code illustrates how to implement an [SCServiceCloudDelegate](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCServiceCloudDelegate.html) object to handle authentication. class MyAuthHandler: NSObject, SCServiceCloudDelegate { override init() { super.init() // Subscribe to ServiceCloud events ServiceCloud.shared().delegate = self } /\*\* Implementation of a \`ServiceCloudDelegate\` method that allows you to authenticate for a given service. \*/ func serviceCloud(\_ serviceCloud: ServiceCloud, shouldAuthenticateServiceType service: SCServiceType, completion: @escaping (SCSAuthenticationSettings?) -> Void) -> Bool { // Rather than scrutinize the service to see if we want to authenticate, // let's just assume that we always want to authenticate... // TO DO: Authenticate asynchronously let urlRequest = URLRequest.init(url: URL(string: "https://example.com/auth")!) URLSession.shared.dataTask(with: urlRequest) { (data, response, error) in // TO DO: Populate the \`SCSAuthenticationSettings\` object from the result. var authSettings: SCSAuthenticationSettings? // Call the completion block with the authentication settings (asynchronously) completion(authSettings) }.resume() // Tell the SDK that we do plan to authenticate return true } /\*\* Implementation of a \`ServiceCloudDelegate\` method to handle authentication failure events. \*/ func serviceCloud(\_ serviceCloud: ServiceCloud, authenticationFailed error: Error, forServiceType service: SCServiceType) -> Bool { // For this example, let's not bother handling the error, // and just fall back to the guest user state... // TO DO: In your code, you should inspect this error. // If you want to handle the error, you could // return \`true\` and then you'd be called back in the // \`shouldAuthenticateServiceType\` method above. return false } } # Block Sensitive Data in a Chat Session To block sending sensitive data to agents, specify a regular expression in your org's setup. When the regular expression matches text in the user's message, the matched text is replaced with customizable text before it leaves the device. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). To learn more, see [Block Sensitive Data in Chats](https://help.salesforce.com/articleView?id=live_agent_block_sensitive_data.htm&language=en_US). # Build Your Own UI with the Chat Core API With the Chat Core API, you can access the functionality of Chat without a UI. This API is useful if you want to build your own UI and not use the default. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). Before running through these steps, be sure you’ve already: - Set up Service Cloud to work with Chat. To learn more, see [Org Setup for Chat in Lightning Experience with a Guided Flow](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_cloud_setup.htm "Use the guided setup flow in Lightning Experience to add chat to your org."). - Installed the SDK. To learn more, see [Install the for iOS for iOS](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/ios_sdk_install_overview.htm "Before you can use the iOS SDK, install the SDK and configure your project."). Once you’ve reviewed these prerequisites, you’re ready to begin. These steps describe how to use the Chat Core API with your own custom UI. To use the default UI, see [Quick Setup: Chat in the](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_basic_setup.htm "To add Chat to your iOS app, create an SCSChatConfiguration object and pass it to the showChat method."). 1. Import the SDK. Wherever you intend to use the Chat SDK, be sure to import the ServiceCore framework and the ServiceChat framework. In Swift: import ServiceCore import ServiceChat In Objective-C: @import ServiceCore; @import ServiceChat; 2. Create an [SCSChatConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) object. In Swift: 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: 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/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/configure_lac_session.htm#configure_lac_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.") on how to configure a chat session. 3. Implement [SCSChatSessionDelegate](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html) and handle the relevant session-related methods. Using this delegate, you can: - Detect state transitions with [session(didTransitionFrom:to:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html#/c:objc\(pl\)SCSChatSessionDelegate\(im\)session:didTransitionFromState:toState:). - Detect the end of the session with [session(didEnd:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html#/c:objc\(pl\)SCSChatSessionDelegate\(im\)session:didEnd:). - Detect error conditions with [session(didError:fatal:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html#/c:objc\(pl\)SCSChatSessionDelegate\(im\)session:didError:fatal:). - Detect queue state changes with [session(didUpdateQueuePosition:estimatedWaitTime:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html#/c:objc\(pl\)SCSChatSessionDelegate\(im\)session:didUpdateQueuePosition:estimatedWaitTime:). Pass your implementation to the [SCSChat](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html) instance. In Swift: ServiceCloud.shared().chatCore.add(delegate: mySessionDelegate) In Objective-C: \[\[SCServiceCloud sharedInstance\].chatCore addDelegate:mySessionDelegate\]; To learn more, see [Listen for State Changes and Events](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_listen_to_events.htm "Implement SCSChatSessionDelegate to be notified about state changes made before, during, and after a chat session. This delegate also allows you to listen for error conditions so you can present alerts to the user when applicable."). 4. Implement [SCSChatEventDelegate](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html) and handle the relevant event-related methods. Using this delegate, you can: - Detect when an agent joins with [session(agentJoined:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:agentJoined:). - Detect when an agent leaves with [session(agentLeftConference:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:agentLeftConference:). - Detect when an outgoing message is sent with [session(processedOutgoingMessage:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:processedOutgoingMessage:). - Detect when the delivery status of a message has been updated with [session(didUpdateOutgoingMessageDeliveryStatus:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:didUpdateOutgoingMessageDeliveryStatus:). - Detect when an incoming message arrives with [session(didReceiveMessage:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:didReceiveMessage:). - Detects when a URL is found in an message with [session(didReceiveURL:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:didReceiveURL:). - Detect when a chat bot menu arrives with [session(didReceiveChatBotMenu:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:didReceiveChatBotMenu:). - Detect when a chat bot menu item is selected with [session(didSelectMenuItem:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatEventDelegate.html#/c:objc\(pl\)SCSChatEventDelegate\(im\)session:didSelectMenuItem:). - Detect when the agent starts and finishes typing. - Detect events related to the file transfer process. - Detects when the user is transferred to an agent from a chat bot. Pass your implementation to the [SCSChat](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html) instance. In Swift: ServiceCloud.shared().chatCore.addEvent(delegate: myEventDelegate) In Objective-C: \[\[SCServiceCloud sharedInstance\].chatCore addEventDelegate:myEventDelegate\]; 5. Start the session using [startSession(with:)](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html#/c:objc\(cs\)SCSChat\(im\)startSessionWithConfiguration:) on [SCSChat](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html). In Swift: ServiceCloud.shared().chatCore.startSession(config) In Objective-C: \[\[SCServiceCloud sharedInstance\].chatCore startSessionWithConfiguration:config\]; 6. Send activity to the [SCSChatSession](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSession.html) object found in [SCSChat](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html). You can access the session object either from the SCSChat.session property, or from any of your delegate event methods that the SDK calls. With this session object, you can: - Send sneak peek data about the user's message to the agent with sendSneakPeek. - Send a message to the agent with sendMessage. - Get or set the user's typing status with userTyping. - Get information about the actors in the chat session with actors. - Get the history of all events from the chat session with allEvents. - Get the current queue position when the user is waiting for an agent with queuePosition. # Can't Connect to Chat If you can't make a successful connection from your app, even when an agent is standing by, review how you've set up your chat implementation. Run through this checklist to help diagnose the root cause. 1. If you’re using the default UI for chat, verify that you are calling showChat on the main UI thread. 2. Verify that the chat endpoint in your code only specifies the hostname. For instance, if your endpoint is https://MyDomainName.my.salesforce-scrt.com/chat/rest/, then use the following value in your code: MyDomainName.my.salesforce-scrt.com. 3. Verify that you're using the correct chat endpoint. See [Get Chat Settings from Your Org](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_cloud_setup_get_settings.htm#live_agent_cloud_setup_get_settings "After you’ve set up chat in the console, supply your app developer with four values: the chat endpoint hostname, the organization ID, the deployment ID, and the button ID. You can get this information from your org’s setup.") for more info. 4. Verify that you're using the correct deployment ID and button ID. See [Get Chat Settings from Your Org](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_cloud_setup_get_settings.htm#live_agent_cloud_setup_get_settings "After you’ve set up chat in the console, supply your app developer with four values: the chat endpoint hostname, the organization ID, the deployment ID, and the button ID. You can get this information from your org’s setup.") for more info. 5. Verify that you've correctly set up your chat implementation. See [Org Setup for Chat in Lightning Experience with a Guided Flow](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_cloud_setup.htm "Use the guided setup flow in Lightning Experience to add chat to your org.") for more info. # Chat in the for iOS for iOS Using Chat within the Service Chat SDK, you can provide real-time chat sessions from within your native app. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). Once you’ve [set up chat for Service Cloud](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_cloud_setup.htm "Use the guided setup flow in Lightning Experience to add chat to your org."), it takes [just a few calls to the SDK](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_basic_setup.htm "To add Chat to your iOS app, create an SCSChatConfiguration object and pass it to the showChat method.") to have your app ready to handle agent chat sessions. ![Chat session](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/lac-chat-publisher-ios.png) This chat session can be minimized so that the user can continue to navigate from within the app while speaking with an agent. And if you've implemented Einstein Bots, the user first [speaks with a chat bot](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_einstein_bots.htm "With Einstein Bots, you can complement your chat support experience with a smart, automated system that saves your agents time and keeps your customers happy. Once you've set up Einstein Bots in your org, the SDK automatically begins the chat experience using your bot. You can design your bot to transfer to an agent at any point.") before optionally getting transferred to an agent. When an agent sends links to your users, they see link previews right from within the chat session. The SDK tries to use Open Graph meta tags (og:title, og:description, og:image) to extract relevant information for the preview. ![Chat hyperlinks](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/lac-chat-hyperlinks-ios.png) You can also [customize the look and feel](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_ui_customization.htm "Once you’ve played around with some of the SDK features, use this section to learn how to customize the Service Chat SDK user interface so that it fits the look and feel of your app. This section also contains instructions for localizing strings in all supported languages.") of the interface so that it fits naturally within your app. These customizations include the ability to fine-tune the colors, the fonts, the images, and the strings used throughout the interface. # Check Agent Availability Before starting a session, you can check the availability of your chat agents and then provide your users with more accurate expectations. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). ![Warning](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_warning.png) #### Warning If you use the [Permitted Domains setting in your Chat deployment](https://help.salesforce.com/articleView?id=live_agent_deployment_settings.htm&type=0&language=en_US), you’ll get unreliable information from the chat availability check in the SDK. For instance, the agent availability status may always return false. If you want to use Permitted Domains for your web chat deployment, we strongly advise that you create a separate deployment for the Service SDK. To check whether agents are available, call the [determineAvailabilityWithConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html#/c:objc\(cs\)SCSChat\(im\)determineAvailabilityWithConfiguration:completion:) method on the [chatCore](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html#/c:objc\(cs\)SCServiceCloud\(py\)chatCore) property, similar to how you [start a chat session](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_basic_setup.htm "To add Chat to your iOS app, create an SCSChatConfiguration object and pass it to the showChat method."). In Swift: let config = SCSChatConfiguration(liveAgentPod: "YOUR-POD-NAME", orgId: "YOUR-ORG-ID", deploymentId: "YOUR-DEPLOYMENT-ID", buttonId: "YOUR-BUTTON-ID") ServiceCloud.shared().chatCore.determineAvailability(with: config, completion: { (error: Error?, available: Bool, estimatedWaitTime: TimeInterval) in if (error != nil) { // TO DO: Handle error } else if (available) { // TO DO: Enable chat button... // Optionally, use the estimatedWaitTime to // show an estimated wait time until an agent // is available. This value is only valid if // SCSChatConfiguration.queueStyle is set to // EstimatedWaitTime. Estimate is returned // in seconds. } else { // TO DO: Disable button or warn user that no agents are available } }) In Objective-C: SCSChatConfiguration \*config = \[\[SCSChatConfiguration alloc\] initWithLiveAgentPod:@"YOUR-POD-NAME" orgId:@"YOUR-ORG-ID" deploymentId:@"YOUR-DEPLOYMENT-ID" buttonId:@"YOUR-BUTTON-ID"\]; \[\[SCServiceCloud sharedInstance\].chatCore determineAvailabilityWithConfiguration:config completion:^(NSError \*error, BOOL available, NSTimeInterval estimatedWaitTime) { if (error != nil) { // TO DO: Handle error } else if (available) { // TO DO: Enable chat button... // Optionally, use the estimatedWaitTime to // show an estimated wait time until an agent // is available. This value is only valid if // SCSChatConfiguration.queueStyle is set to // EstimatedWaitTime. Estimate is returned // in seconds. } else { // TO DO: Disable button or warn user that no agents are available } }); 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.260.0.live_agent_rest.meta/live_agent_rest/live_agent_rest_estimated_wait_time.htm). # 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](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). 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: 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: 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](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### 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/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_cloud_setup_get_settings.htm#live_agent_cloud_setup_get_settings "After you’ve set up chat in the console, supply your app developer with four values: the chat endpoint hostname, the organization ID, the deployment ID, and the button ID. You can get this information from your org’s setup."). 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/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_cloud_setup.htm "Use the guided setup flow in Lightning Experience to add chat to your org."). 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: Table 1. Session Display Configuration Settings | 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](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### 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.
Table 2. Background Configuration Settings
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
![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### 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&language=en_US).
Table 3. Pre-Chat Configuration Settings
Property Name Description Type & Default Value
prechatEntities

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

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
Table 4. Other Configuration Settings
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. The queue can either display the queue position number (.position), the estimated wait time (.estimatedWaitTime), or no queue information at all (.none).

You can subscribe to queue position events using session(didUpdateQueuePosition:estimatedWaitTime:) on SCSChatSessionDelegate.

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). To understand the algorithm used for the estimated wait time, see the estimated wait time documentation in the Chat REST API Developer Guide.

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.

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.

SCSChatConfiguration

QueueStyle: .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"
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: 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: 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\]; # 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](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). ## Overview Before reading these instructions, review [Show Pre-Chat Fields to User](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/live_agent_prechat_fields.htm#live_agent_prechat_fields "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.") 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](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). Each pre-chat entity must map to a pre-chat object ([SCSPrechatObject](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html), [SCSPrechatTextInputObject](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatTextInputObject.html), or [SCSPrechatPickerObject](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatPickerObject.html)). The label string in this pre-chat object must be identical to the label used in your [SCSPrechatEntityField](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntityField.html) object. Use the config object's [prechatFields](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html#/c:objc\(cs\)SCSChatConfiguration\(py\)prechatFields) property for the array of your pre-chat objects and the [prechatEntities](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html#/c:objc\(cs\)SCSChatConfiguration\(py\)prechatEntities) property for the array of your entity objects. ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### 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 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](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatTextInputObject.html) instead of [SCSPrechatObject](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatObject.html) to allow user input. In Swift: // Create pre-chat fields let firstNameField = SCSPrechatObject(label: "First Name", value: "Jane") let lastNameField = SCSPrechatObject(label: "Last Name", value: "Doe") // Create entity fields let firstNameEntityField = SCSPrechatEntityField(fieldName: "FirstName", label: "First Name") firstNameEntityField.doFind = true firstNameEntityField.doCreate = true let lastNameEntityField = SCSPrechatEntityField(fieldName: "LastName", label: "Last Name") lastNameEntityField.doFind = true lastNameEntityField.doCreate = true // Create an entity object let contactEntity = SCSPrechatEntity(entityName: "Contact") contactEntity.showOnCreate = true // Add entity fields to entity object contactEntity.entityFieldsMaps.add(firstNameEntityField) contactEntity.entityFieldsMaps.add(lastNameEntityField) // Update config object with the pre-chat fields config!.prechatFields = \[firstNameField, lastNameField\] // Update config object with the entity mappings config!.prechatEntities = \[contactEntity\] In Objective-C: // Create pre-chat fields SCSPrechatObject\* firstNameField = \[\[SCSPrechatObject alloc\] initWithLabel:@"First Name" value:@"Banana"\]; SCSPrechatObject\* lastNameField = \[\[SCSPrechatObject alloc\] initWithLabel:@"Last Name" value:@"Town"\]; // Create entity fields SCSPrechatEntityField\* firstNameEntityField = \[\[SCSPrechatEntityField alloc\] initWithFieldName:@"FirstName" label:@"First Name"\]; firstNameEntityField.doFind = YES; firstNameEntityField.doCreate = YES; SCSPrechatEntityField\* lastNameEntityField = \[\[SCSPrechatEntityField alloc\] initWithFieldName:@"LastName" label:@"Last Name"\]; lastNameEntityField.doFind = YES; lastNameEntityField.doCreate = YES; // Create an entity object SCSPrechatEntity\* contactEntity = \[\[SCSPrechatEntity alloc\] initWithEntityName:@"Contact"\]; contactEntity.showOnCreate = YES; // Add entity fields to entity object \[contactEntity.entityFieldsMaps addObject:firstNameEntityField\]; \[contactEntity.entityFieldsMaps addObject:lastNameEntityField\]; // Update config object with the pre-chat fields NSMutableArray \*preChatFields = \[NSMutableArray new\]; \[preChatFields addObject:firstNameField\]; \[preChatFields addObject:lastNameField\]; config.prechatFields = preChatFields; // Update config object with the entity mappings NSMutableArray \*prechatEntities = \[NSMutableArray new\]; \[prechatEntities addObject:contactEntity\]; config.prechatEntities = prechatEntities; ## Entity Configuration Settings The [SCSPrechatEntity](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntity.html) and [SCSPrechatEntityField](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntityField.html) 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](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntity.html) object. In Swift: // Create an entity let entity = SCSPrechatEntity(entityName: "Contact") entity.saveToTranscript = "ContactId" // Save this entity to Transcript.ContactId entity.linkToEntityName = "Case" entity.linkToEntityField = "ContactId" // Link this entity to Case.ContactId // Add an entity field map to our entity let entityField = SCSPrechatEntityField(fieldName: "FirstName", label: "First Name") entityField.doFind = true // Attempt to search for that field entityField.isExactMatch = true // Must be an exact match entityField.doCreate = true // Create if not found entity.entityFieldsMaps.add(entityField) // Add field to entity map In Objective-C: // Create an entity SCSPrechatEntity\* entity = \[\[SCSPrechatEntity alloc\] initWithEntityName:@"Contact"\]; entity.saveToTranscript = @"ContactId"; // Save this entity to Transcript.ContactId entity.linkToEntityName = @"Case"; entity.linkToEntityField = @"ContactId"; // Link this entity to Case.ContactId // Add an entity field map to our entity SCSPrechatEntityField\* entityField = \[\[SCSPrechatEntityField alloc\] initWithFieldName:@"FirstName" label:@"First Name"\]; entityField.doFind = YES; // Attempt to search for that field entityField.isExactMatch = YES; // Must be an exact match entityField.doCreate = YES; // Create if not found \[entity.entityFieldsMaps addObject:entityField\]; // Add field to entity map See the reference documentation for [SCSPrechatEntity](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntity.html) and [SCSPrechatEntityField](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSPrechatEntityField.html). Also refer to [Chat REST API Data Types](https://developer.salesforce.com/docs/atlas.en-us.260.0.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. ## Example This code sample adds FirstName, LastName, Email to a Contact record and a Subject field to a Case record. let config = SCSChatConfiguration(liveAgentPod: "YOUR\_POD\_NAME", orgId: "YOUR\_ORG\_ID", deploymentId: "YOUR\_DEPLOYMENT\_ID", buttonId: "YOUR\_BUTTON\_ID") // Create some basic pre-chat fields (with user input) 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 // Create a pre-chat field without user input let subjectField = SCSPrechatObject(label: "Subject", value: "Chat Session") // Create an entity mapping for a Contact record type let contactEntity = SCSPrechatEntity(entityName: "Contact") contactEntity.saveToTranscript = "Contact" contactEntity.linkToEntityName = "Case" contactEntity.linkToEntityField = "ContactId" // Add some field mappings to our Contact entity let firstNameEntityField = SCSPrechatEntityField(fieldName: "FirstName", label: "First Name") firstNameEntityField.doFind = true firstNameEntityField.isExactMatch = true firstNameEntityField.doCreate = true contactEntity.entityFieldsMaps.add(firstNameEntityField) let lastNameEntityField = SCSPrechatEntityField(fieldName: "LastName", label: "Last Name") lastNameEntityField.doFind = true lastNameEntityField.isExactMatch = true lastNameEntityField.doCreate = true contactEntity.entityFieldsMaps.add(lastNameEntityField) let emailEntityField = SCSPrechatEntityField(fieldName: "Email", label: "Email") emailEntityField.doFind = true emailEntityField.isExactMatch = true emailEntityField.doCreate = true contactEntity.entityFieldsMaps.add(emailEntityField) // Create an entity mapping for a Case record type let caseEntity = SCSPrechatEntity(entityName: "Case") caseEntity.saveToTranscript = "Case" caseEntity.showOnCreate = true // Add one field mappings to our Case entity let subjectEntityField = SCSPrechatEntityField(fieldName: "Subject", label: "Subject") subjectEntityField.doCreate = true caseEntity.entityFieldsMaps.add(subjectEntityField) // Update config object with the pre-chat fields config!.prechatFields = \[firstNameField, lastNameField, emailField, subjectField\] as? \[SCSPrechatObject\] // Update config object with the entity mappings config!.prechatEntities = \[contactEntity, caseEntity\] // Start the session! ServiceCloud.shared().chatUI.showChat(with: config!, showPrechat: true) # Customize and Localize Strings with the You can change the text used throughout the user interface. To customize text, create string resource values in a Localizable.strings file in the Localization bundle for the languages you want to update. Create string tokens that match the tokens you intend to override. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). Service Chat SDK text is translated into more than 25 different languages. In order for your string customizations to take effect in a given language, provide a translation for that language. For any language you do not override manually in your app, the SDK uses its default values for that language. Refer to [Internationalization at developer.apple.com](https://developer.apple.com/internationalization/) for more info about localization. The following list of string tokens are available for customization: - [ServiceChat (Chat) String Resources](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/servicechatstringconstants.html) - [ServiceCore (Common) String Resources](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/servicecorestringconstants.html) The following languages are currently supported: Table 1. Supported Languages | Language Code | Language | | --- | --- | | ar | Arabic | | cs | Czech | | da | Danish | | de | German | | el | Greek | | en | English | | es | Spanish | | fi | Finnish | | fr | French | | hu | Hungarian | | id | Indonesian | | it | Italian | | iw | Hebrew | | ja | Japanese | | ko | Korean | | nb | Norwegian Bokmål | | nl | Dutch | | pl | Polish | | pt | Portuguese | | ro | Romanian | | ru | Russian | | sv | Swedish | | th | Thai | | tr | Turkish | | uk | Ukranian | | vi | Vietnamese | | zh\_TW | Chinese (Taiwan) | | zh-Hans | Chinese (Simplified) | | zh-Hant | Chinese (Traditional) | | zh | Chinese | # Customize Colors with the Customize the colors by defining the branding token colors used throughout the interface. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). To customize colors, create an SCAppearanceConfiguration instance, specify values for each token you want to change, and store the instance in the [appearanceConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html#/c:objc\(cs\)SCServiceCloud\(py\)appearanceConfiguration) property of the [ServiceCloud](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html) [sharedInstance](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html#/c:objc\(cs\)SCServiceCloud\(cm\)sharedInstance). In Swift: // Create appearance configuration instance let appearance = SCAppearanceConfiguration() // Customize color tokens appearance.setColor(COLOR\_VALUE, forName: TOKEN\_NAME) // Add other customizations here... // Save configuration instance ServiceCloud.shared().appearanceConfiguration = appearance In Objective-C: // Create appearance configuration instance SCAppearanceConfiguration \*appearance = \[SCAppearanceConfiguration new\]; // Customize color tokens \[appearance setColor:COLOR\_VALUE forName:TOKEN\_NAME\]; // Add other customizations here... // Save configuration instance \[SCServiceCloud sharedInstance\].appearanceConfiguration = appearance; To support dark mode in iOS 13 and later, [specify adaptive colors](https://github.com/forcedotcom/ServiceSDK-iOS/wiki/Handling-Dark-Mode-for-iOS-13-with-the-Service-SDK) for each branding token. The following branding tokens are available for customization.
Token Name / Swift Value / Objective-C Value Default Dark Mode Default Description / Sample Uses
Navigation Bar Background

navbarBackground

SCSAppearanceColorTokenNavbarBackground

 #FAFAFA

Navigation bar background

 #1A2129

Navigation bar background dark

Background color for the navigation bar.
Navigation Bar Inverted

navbarInverted

SCSAppearanceColorTokenNavbarInverted

 #010101

Navigation bar inverted

 #C6CBCF

Navigation bar inverted dark

Navigation bar text and icon color.
Brand Primary

brandPrimary

SCSAppearanceColorTokenBrandPrimary

 #007F7F

Brand primary

 #00B4B4

Brand primary dark
Brand Secondary

brandSecondary

SCSAppearanceColorTokenBrandSecondary

 #2872CC

Brand secondary

 #0070D2

Brand secondary dark

Used throughout the UI for button colors.

Chat: Agent text bubbles.
Primary Brand Inverted

brandPrimaryInverted

SCSAppearanceColorTokenBrandPrimaryInverted

 #FBFBFB

Primary inverted

 #FBFBFB

Primary inverted dark
Secondary Brand Inverted

brandSecondaryInverted

SCSAppearanceColorTokenBrandSecondaryInverted

 #FCFCFC

Secondary inverted

 #F7F7F7

Secondary inverted dark

Text on areas where a brand color is used for the background.
Contrast Primary

contrastPrimary

SCSAppearanceColorTokenContrastPrimary

 #000000

Contrast primary

 #E2E4E6

Contrast primary dark

Primary body text color.
Contrast Secondary

contrastSecondary

SCSAppearanceColorTokenContrastSecondary

 #6D6D6D

Contrast secondary

 #898D92

Contrast secondary dark
Contrast Tertiary

contrastTertiary

SCSAppearanceColorTokenContrastTertiary

 #BABABA

Contrast tertiary

 #A0A6AD

Contrast tertiary dark
Contrast Quaternary

contrastQuaternary

SCSAppearanceColorTokenContrastQuaternary

 #F1F1F1

Contrast quaternary

 #09121B

Contrast quaternary dark

Chat: Background color.
Contrast Inverted

contrastInverted

SCSAppearanceColorTokenContrastInverted

 #FFFFFF

Contrast inverted

 #323232

Contrast inverted dark

Page background, navigation bar, table cell background.
Feedback Primary

feedbackPrimary

SCSAppearanceColorTokenFeedbackPrimary

 #E74C3C

Feedback primary

 #E0A7A9

Feedback primary dark

Text color for error messages.
Feedback Secondary

feedbackSecondary

SCSAppearanceColorTokenFeedbackSecondary

 #2ECC71

Feedback secondary

 #9ACDB7

Feedback secondary dark
Feedback Tertiary

feedbackTertiary

SCSAppearanceColorTokenFeedbackTertiary

 #F5A623

Feedback tertiary

 #FADBAE

Feedback tertiary dark
Overlay

overlay

SCSAppearanceColorTokenOverlay

 Contrast Primary

(at 40% alpha)

 #323232

Contrast inverted dark
These screenshots illustrate how the branding tokens affect the UI. Chat UI Branding: ![Chat color branding](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/branding-chat-ios.png) ## Example The following code sample changes three of the branding tokens. In Swift: // Create appearance configuration instance let appearance = SCAppearanceConfiguration() // Customize color tokens appearance.setColor( UIColor(red: 80/255, green: 227/255, blue: 194/255, alpha: 1.0), forName: .brandPrimary) appearance.setColor( UIColor(red: 74/255, green: 144/255, blue: 226/255, alpha: 1.0), forName: .brandSecondary) appearance.setColor( UIColor(red: 252/255, green: 252/255, blue: 252/255, alpha: 1.0), forName: .brandSecondaryInverted) // Save configuration instance ServiceCloud.shared().appearanceConfiguration = appearance In Objective-C: // Create appearance configuration instance SCAppearanceConfiguration \*appearance = \[SCAppearanceConfiguration new\]; // Customize color tokens \[appearance setColor:\[UIColor colorWithRed: 80/255 green: 227/255 blue: 194/255 alpha: 1.0\] forName:SCSAppearanceColorTokenBrandPrimary\]; \[appearance setColor:\[UIColor colorWithRed: 74/255 green: 144/255 blue: 226/255 alpha: 1.0\] forName:SCSAppearanceColorTokenBrandSecondary\]; \[appearance setColor:\[UIColor colorWithRed: 252/255 green: 252/255 blue: 252/255 alpha: 1.0\] forName:SCSAppearanceColorTokenBrandSecondaryInverted\]; // Save configuration instance \[SCServiceCloud sharedInstance\].appearanceConfiguration = appearance; For an example of how to specify adaptive colors that work with the dark mode feature that was introduced in iOS 13, see [Handling Dark Mode for iOS 13 with the Service SDK](https://github.com/forcedotcom/ServiceSDK-iOS/wiki/Handling-Dark-Mode-for-iOS-13-with-the-Service-SDK). # Customize Fonts with the There are three customizable font settings used throughout the UI: SCFontWeightLight, SCFontWeightRegular, SCFontWeightBold. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). You can customize three font settings used throughout the Service Chat SDK interface: | Font Setting | Default Value | Samples Uses in the SDK | | --- | --- | --- | | SCFontWeightLight | Helvetica Neue - Light | Knowledge article cell summary, Case Management field text, Case Management submit success view, content of error messages | | SCFontWeightRegular | Helvetica Neue | Navigation bar, Chat text, Knowledge data category cell in detail view, Knowledge "show more" article footer, Knowledge "show more" button cell | | SCFontWeightBold | Helvetica Neue - Semibold | Knowledge category headers, Knowledge article cell title, Case Management field labels, Case Management submit button, title of error messages | To configure your app to use different fonts: 1. Add new fonts to your Xcode project. Any new fonts must be added as a resource to your Xcode project. When adding, be sure to select **Copy items if needed**. 2. Add new fonts to your project target. For each new font, add it to your project target under **Target Membership**. ![Target Membership for font](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/ios-font-customization-1.png) 3. Add the font to your app's Info.plist. You'll need to add all new fonts into a string array. Each string element of the array must be the name of each font resource file. If you're viewing your Info.plist as a **Property List**, add an Array named **Fonts provided by application**. If you're viewing your Info.plist as **Source Code**, add an array named UIAppFonts. For example: UIAppFonts MyCustomFont1.ttf MyCustomFont2.ttf MyCustomFont3.ttf 4. Customize any of the Service Chat SDK font values using [SCAppearanceConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html). To customize the fonts, create an [SCAppearanceConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html) instance, set the font descriptor for each font setting you want to change, and store the SCAppearanceConfiguration instance in the [appearanceConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html#/c:objc\(cs\)SCServiceCloud\(py\)appearanceConfiguration) property of the [ServiceCloud](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceCloud.html) shared instance. Swift Example: // Create appearance configuration instance let config = SCAppearanceConfiguration() // Customize font let descriptor = UIFontDescriptor(fontAttributes: \[UIFontDescriptor.AttributeName.family : "Proxima Nova"\]) config.setFontDescriptor(descriptor, fontFileName: "ProximaNova-Light.otf", forWeight: SCFontWeightLight) // Add other customizations here... // Save configuration instance ServiceCloud.shared().appearanceConfiguration = config Objective-C Example: // Create appearance configuration instance SCAppearanceConfiguration \*config = \[SCAppearanceConfiguration new\]; // Customize font UIFontDescriptor \*descriptor = \[UIFontDescriptor fontDescriptorWithFontAttributes:@{ UIFontDescriptorFamilyAttribute: @"Proxima Nova", UIFontDescriptorFaceAttribute: @"Light" }\]; \[config setFontDescriptor:descriptor fontFileName:@"ProximaNova-Light.otf" forWeight:SCFontWeightLight\]; // Add other customizations here... // Save configuration instance \[SCServiceCloud sharedInstance\].appearanceConfiguration = config; Be sure to use the exact font descriptor attribute name and font file name for your custom font. # Customize Images with the You can specify custom images used throughout the UI. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). Use the [setImage](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html#/c:objc\(cs\)SCAppearanceConfiguration\(im\)setImage:compatibleWithTraitCollection:forName:) method on the [SCAppearanceConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html) object to **replace a stock image** with your image. Use the enumeration value for the image you intend to replace. Supported image file formats include: tiff, tif, jpg, jpeg, gif, png, bmp, BMPF, ico, cur. For specific images, use the SCSAppearanceImageToken enumeration specified by the SDK and add it to the [SCAppearanceConfiguration](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html) object with the [setImage](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html#/c:objc\(cs\)SCAppearanceConfiguration\(im\)setImage:compatibleWithTraitCollection:forName:) method. Table 1. Stock Image Enum Values | Image Description | Enum Value | | --- | --- | | Close button | close | | Done button | done | | Small warning icon used when an error occurs | error | | Error image used in a view for timeouts, when no agents are available, or for an unknown error | genericError | | Minimize button (Knowledge and Chat) | minimizeButton | | No connection | noConnection | | Send button (Case Publisher and Chat) | send | | Next field button (Case Publisher and Chat) | submitButtonNextArrow | | Previous field button (Case Publisher and Chat) | submitButtonPreviousArrow | | Attachment button when the user can attach a file | attachmentClipIcon | | Avatar used for the agent (only the inscribed circle is visible in the chat feed) | chatAgentAvatar | | Avatar used for Einstein bot (only the inscribed circle is visible in the chat feed) | chatBotAvatar | | Icon used for Einstein bot persistent footer menu | chatBotFooterMenu | | Icon used in the pre-chat screen | preChatIcon | In Swift: // Create appearance configuration instance let config = SCAppearanceConfiguration() // Specify images config.setImage(MY\_CUSTOM\_IMAGE, compatibleWithTraitCollection: MY\_TRAITS, forName: ENUM\_VALUE) // Add other customizations here... // Save configuration instance ServiceCloud.shared().appearanceConfiguration = config In Objective-C: // Create appearance configuration instance SCAppearanceConfiguration \*config = \[SCAppearanceConfiguration new\]; // Specify images \[config setImage:MY\_CUSTOM\_IMAGE compatibleWithTraitCollection: MY\_TRAITS forName: ENUM\_VALUE\]; // Add other customizations here... // Save configuration instance \[SCServiceCloud sharedInstance\].appearanceConfiguration = config; # Data Collection for the The Service Chat SDK collects and transmits data to perform basic operations. This data falls into three categories: pre-chat data, chat message data, and logging data. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). ## Pre-Chat Data Data types collected: - Personal info (for example, name, email). Most pre-chat forms contain some personal info. - Other info. Other data collected depends on how you design your pre-chat form. All data specified in the pre-chat form is securely transmitted to your Salesforce org using HTTPS communication (TLS 1.3). This data is stored in your org indefinitely, depending on how you handle pre-chat information in your org. You can change this behavior from within your org. You can even remove the pre-chat form altogether. ## Chat Message Data Data types collected: - In-app messages. User chat messages get sent to agents through your Salesforce org. - Photos. Users can send photos to agents. - Other info. Any content a user types into a message gets sent to an agent or chatbot. All user messages are securely transmitted to your Salesforce org using HTTPS communication (TLS 1.3). This data is stored in your org indefinitely. You can remove any of this data from your org. ## Logging Data Data types collected: - App interactions - Other actions For logging purposes, we send anonymized information to Splunk servers using HTTPS communication (TLS 1.3). This data doesn't contain any customer-identifiable or hardware-identifiable information. We log info about how users interact with the SDK and we log some basic system information (such as battery stats) while they use the SDK. # Data Protection and Security in the for iOS for iOS The Service Chat SDK does not collect or store personal data from its users. We ensure that data is secure both locally and when in transit. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). - **Secure data at rest**. We don't store personal data about the user. We manage keys using iOS Keychain Services. All content fetched from Salesforce servers is stored locally using AES-128 encryption. When the user logs out, we remove all user-specific data from the device. - **Secure data in transit**. All network communication occurs over SSL using TLS 1.2. # Embedded Service Chat SDK for iOS Developer Guide Developer Guide The Embedded Service Chat SDK for Mobile Apps makes it easy to give customers access to powerful chat features right from within your native app. This guide helps you get started using the SDK in your mobile app. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). **October 2023 Release (Version 246.0.0)** This documentation describes the Service Chat SDK, which uses the following components. | Component | Version Number | | --- | --- | | Chat | 4.1.2 | | ServiceCore | 4.2.8 | ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### Note If you are using Xcode 12.3 or later, you must install the SDK using XCFramework files. To learn more, review the [installation instructions](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/ios_sdk_install_overview.htm "Before you can use the iOS SDK, install the SDK and configure your project."). - **[Release Notes](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/ios_release_notes.htm)** Check out the new features and known issues for the iOS Service Chat SDK. - **[Service Cloud Setup for the](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_cloud_setup.htm)** Set up Service Cloud in your org before using the Service Chat SDK. - **[Setup Setup](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_sdk_setup.htm)** Set up the SDK to start using Service Cloud features in your mobile app. - **[iOS Tutorials & Examples](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_quick_start.htm)** Get going quickly with these short introductory tutorials. - **[Using Chat with the](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_using_live_agent.htm)** Add the Chat experience to your mobile app. - **[SDK Customizations with the for iOS for iOS](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_ui_customization.htm)** Once you’ve played around with some of the SDK features, use this section to learn how to customize the Service Chat SDK user interface so that it fits the look and feel of your app. This section also contains instructions for localizing strings in all supported languages. - **[Troubleshooting the](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_troubleshooting.htm)** Get some guidance when you run into issues. - **[Data Protection and Security in the for iOS for iOS](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/ios_data_protection.htm)** The Service Chat SDK does not collect or store personal data from its users. We ensure that data is secure both locally and when in transit. - **[Reference Documentation](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_ios_ref_overview.htm)** Reference documentation for Service Chat SDK for iOS. - **[Additional Resources](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/servicesdk_additional_resources.htm)** If you’re looking for other resources, check out this list of links to related documentation. #### See Also - [Service SDK for iOS Release Notes](https://github.com/forcedotcom/ServiceSDK-iOS/releases "Service SDK for iOS Release Notes - HTML (New Window)") - [Service SDK for iOS Reference Documentation](https://forcedotcom.github.io/ServiceSDK-iOS/ "Service SDK for iOS Reference Documentation - HTML (New Window)") - [Service SDK for Android Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_android.meta/service_sdk_android/servicesdk_android_dev_guide.htm "Service SDK for Android Developer Guide - HTML (New Window)") # Enable Debug Logging for the iOS SDK To configure the Service Chat SDK logs, set the level property on the ServiceLogger shared instance. Use the [shared](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceLogger.html#/c:objc\(cs\)SCServiceLogger\(cpy\)sharedLogger) singleton on [ServiceLogger](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceLogger.html) to adjust the [level](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceLogger.html#/c:objc\(cs\)SCServiceLogger\(py\)level). In Swift: ServiceLogger.shared.level = .debug In Objective-C: \[SCServiceLogger sharedLogger\].level = SCSLoggerLevelDebug; The log level is specified using the SCSLoggerLevel enumerated type. It can be one of these values: - SCSLoggerLevelDebug (.debug in Swift) - SCSLoggerLevelInfo (.info in Swift) - SCSLoggerLevelError (.error in Swift)—Default value - SCSLoggerLevelFault (.fault in Swift) - SCSLoggerLevelOff (.off in Swift) By default, logs go to the console output. You can have logs go to a file using the [filehandle](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCServiceLogger.html#/c:objc\(cs\)SCServiceLogger\(py\)filehandle) property. # Get Chat Settings from Your Org After you’ve set up chat in the console, supply your app developer with four values: the chat endpoint hostname, the organization ID, the deployment ID, and the button ID. You can get this information from your org’s setup. ![Important](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note_important.png) #### 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&language=en_US) before that date. Messaging offers many of the [chat features that you](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm&type=5&language=en_US) 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&language=en_US). ![Note](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/icon_note.png) #### Note If the endpoint for your server changes (due to an org migration, for example), the SDK automatically reroutes you to the correct server. However, to avoid unnecessary rerouting, you should still update the server endpoint when you notice it has changed inside your org’s settings. Chat Endpoint Hostname The hostname for the Chat endpoint that your organization has been assigned. To get this value, from Setup, search for **Chat Settings** and copy the hostname from the **API Endpoint**. ![Pod hostname](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/chat_org_pod_hostname.png) Be sure not to include the protocol or the path. For instance, if the API Endpoint is: https://d.gla5.gus.salesforce.com/chat/rest/ The chat endpoint hostname is: d.gla5.gus.salesforce.com Org ID The Salesforce org ID. To get this value, from Setup, search for **Company Information** and copy the **Salesforce Organization ID**. ![Org ID](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/chat_org_org_id.png) Deployment ID The unique ID of your Chat deployment. To get this value, from Setup, select **Chat** | **Deployments**. The script at the bottom of the page contains a call to the liveagent.init function with the **pod**, the **deploymentId**, and **orgId** as arguments. Copy the **deploymentId** value. ![Deployment ID](https://developer.salesforce.com/docs/atlas.en-us.service_sdk_ios.meta/service_sdk_ios/images/chat_org_deployment_id.png) For instance, if the deployment code contains the following information: