# Quick Setup: Chat in the Service Chat SDK To add Chat to your iOS app, create an `SCSChatConfiguration` object and pass it to the `showChat` method. ## Before You Begin :::important The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then. During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid service interruptions to your customers, migrate to [Messaging for In-App and Web](https://help.salesforce.com/s/articleView?id=service.miaw_intro_landing.htm\&type=5) before that date. Messaging offers many of the [chat features](https://help.salesforce.com/s/articleView?id=service.miaw_chat_vs_messaging.htm\&type=5) that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement in [Help](https://help.salesforce.com/s/articleView?id=001790618\&type=1). ::: 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](/docs/service/service-sdk-android/guide/live-agent-cloud-setup.md). - Installed the SDK. To learn more, see [Install the Service Chat SDK for iOS](/docs/service/service-sdk-ios/guide/ios-sdk-install-overview.md). Once you’ve reviewed these prerequisites, you’re ready to begin. These steps describe how to set up Chat with the default UI. If you prefer to build your own user interface, see [Build Your Own UI with the Chat Core API](/docs/service/service-sdk-ios/guide/live-agent-chat-core-api.md). 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: ```java import ServiceCore import ServiceChat ``` In Objective-C: ```java @import ServiceCore; @import ServiceChat; ``` 2. Create an [`SCSChatConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatConfiguration.html) instance with information about your LiveAgent pod, your Salesforce org ID, the deployment ID, and the button ID. In Swift: ```java let config = SCSChatConfiguration(liveAgentPod: "TO_DO_POD_NAME", // e.g. "d.gla5.gus.salesforce.com" orgId: "TO_DO_ORG_ID", // e.g. "00DB00000003Rxz" deploymentId: "TO_DO_DEPLOYMENT_ID", // e.g. "573B00000005KXz" buttonId: "TO_DO_BUTTON_ID") // e.g. "575C00000004h3m" ``` In Objective-C: ```java SCSChatConfiguration *config = [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"TO_DO_POD_NAME" // e.g. "d.gla5.gus.salesforce.com" orgId:@"TO_DO_ORG_ID" // e.g. "00DB00000003Rxz" deploymentId:@"TO_DO_DEPLOYMENT_ID" // e.g. "573B00000005KXz" buttonId:@"TO_DO_BUTTON_ID"]; // e.g. "575C00000004h3m" ``` :::note You can get the required parameters for this method from your Salesforce org. See [Get Chat Settings from Your Org](/docs/service/service-sdk-android/guide/live-agent-cloud-setup-get-settings.md). If your Salesforce admin hasn’t already set up Chat in Service Cloud or you need more guidance, see [Org Setup for Chat in Lightning Experience with a Guided Flow](/docs/service/service-sdk-android/guide/live-agent-cloud-setup.md). ::: 3. (Optional) Configure the visitor name, queue display style, whether the user can minimize the chat session, and various other configuration settings. See [Configure a Chat Session](/docs/service/service-sdk-ios/guide/configure-lac-session.md) for more information. 4. (Optional) Customize the appearance with the configuration object. You can configure the colors, fonts, and images to your interface with an [`SCAppearanceConfiguration`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html) instance. It contains the methods [`setColor`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html#/c\:objc\(cs\)SCAppearanceConfiguration\(im\)setColor\:forName:), [`setFontDescriptor`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html#/c\:objc\(cs\)SCAppearanceConfiguration\(im\)setFontDescriptor\:fontFileName\:forWeight:), and [`setImage`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCAppearanceConfiguration.html#/c\:objc\(cs\)SCAppearanceConfiguration\(im\)setImage\:compatibleWithTraitCollection\:forName:). You can also configure the strings used throughout the interface. See [SDK Customizations with the Service Chat SDK for iOS](/docs/service/service-sdk-ios/guide/servicesdk-ui-customization.md). 5. (Optional) Specify any pre-chat fields. 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. These fields can be mapped directly to fields in a record in your org. See [Show Pre-Chat Fields to User](/docs/service/service-sdk-ios/guide/live-agent-prechat-fields.md) and [Create or Update Salesforce Records from a Chat Session](/docs/service/service-sdk-ios/guide/live-agent-send-custom-data.md) for more information. 6. To start a chat session, call the [`showChat(with:showPrechat:)`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatInterface.html#/c\:objc\(cs\)SCSChatInterface\(im\)showChatWithConfiguration\:showPrechat:) method on [`SCSChatInterface`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChatInterface.html). In Swift: ```java ServiceCloud.shared().chatUI.showChat(with: config!) ``` In Objective-C: ```java [[SCServiceCloud sharedInstance].chatUI showChatWithConfiguration:config]; ``` :::note The `showChat` method must be called on the main UI thread. ::: You can provide an optional completion block to execute code when the session has been fully connected to all services. During a successful session initialization, the SDK calls the completion block at the point that the session is active and the user is waiting for an agent to join. If there is a failure, the SDK calls the completion block with the associated error. 7. Listen for events and handle error conditions. You can detect when a session ends by implementing the [`session(didEnd:)`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html#/c\:objc\(pl\)SCSChatSessionDelegate\(im\)session\:didEnd:) method on the [`SCSChatSessionDelegate`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html) delegate. Register this delegate using the [`add(delegate:)`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html#/c\:objc\(cs\)SCSChat\(im\)addDelegate:) method on your [`SCSChat`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Classes/SCSChat.html) instance. In particular, we suggest that you handle the `.agent` reason (for when an agent ends a session) and the `.noAgentsAvailable` reason (for when there are no agents available). See [Listen for State Changes and Events](/docs/service/service-sdk-ios/guide/live-agent-listen-to-events.md). :::note The SDK doesn't show an alert when a session fails to start, or when a session ends. It's your responsibility to listen to events and display an error when appropriate. ::: These steps embed the chat experience into your app. :::note To learn about chat timeout limitations on iOS devices, see [When does a chat session time out?](https://github.com/forcedotcom/ServiceSDK-iOS/wiki/When-does-a-chat-session-time-out%3F) ::: ## Example To use this example code, create a Single View Application and [Install the Service Chat SDK for iOS](/docs/service/service-sdk-ios/guide/ios-sdk-install-overview.md). Use the storyboard to add a button to the view. Add a `Touch Up Inside` action in your `UIViewController` implementation with the name `startChat`. In the view controller code: - Implement the [`SCSChatSessionDelegate`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html) protocol so that you can be notified when there are errors or state changes. - Specify `self` as a chat delegate. - Start a chat session in the button action. - Implement the [`session(didEnd:)`](https://forcedotcom.github.io/ServiceSDK-iOS/releases/api/234.1/Protocols/SCSChatSessionDelegate.html#/c\:objc\(pl\)SCSChatSessionDelegate\(im\)session\:didEnd:) method and show a dialog when appropriate. In Swift: ```java import UIKit import ServiceCore import ServiceChat class ViewController : UIViewController, SCSChatSessionDelegate { override func viewDidLoad() { super.viewDidLoad() // Add our chat delegate ServiceCloud.shared().chatCore.add(delegate: self) } @IBAction func startChat(_ sender: AnyObject) { // Create config object if let config = SCSChatConfiguration(liveAgentPod: "YOUR-POD-NAME", orgId: "YOUR-ORG-ID", deploymentId: "YOUR-DEPLOYMENT-ID", buttonId: "YOUR-BUTTON-ID") { // Start a session ServiceCloud.shared().chatUI.showChat(with: config) } } func session(_ session: SCSChatSession!, didEnd endEvent: SCSChatSessionEndEvent!) { var description = "" // Here we'll handle the situation where the agent ends the session // and when there are no agents available... switch endEvent.reason { case .agent: description = "The agent has ended the session." case .noAgentsAvailable: description = "It looks like there are no agents available. Try again later." // TO DO: Handle other reasons default: description = "Session ended for an unknown reason." } let alert = UIAlertController(title: "Session Ended", message: description, preferredStyle: .alert) let okAction = UIAlertAction(title: "OK", style: .default, handler: nil) alert.addAction(okAction) self.present(alert, animated: true, completion: nil) } func session(_ session: SCSChatSession!, didError error: Error!, fatal: Bool) { // TO DO: Handle error condition NSLog("Chat error: \(error.localizedDescription)") } } ``` In Objective-C: ```java #import "ViewController.h" @import ServiceCore; @import ServiceChat; @interface ViewController : UIViewController @end @implementation ViewController - (void)viewDidLoad { [super viewDidLoad]; // Add our chat delegate [[SCServiceCloud sharedInstance].chatCore addDelegate:self]; } - (IBAction)startChat:(id)sender { // Create config object SCSChatConfiguration *config = [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"YOUR-POD-NAME" orgId:@"YOUR-ORG-ID" deploymentId:@"YOUR-DEPLOYMENT-ID" buttonId:@"YOUR-BUTTON-ID"]; // Start the session [[SCServiceCloud sharedInstance].chatUI showChatWithConfiguration:config]; } - (void)session:(id)session didEnd:(SCSChatSessionEndEvent *)endEvent { NSString *description = nil; // Here we'll handle the situation where the agent ends the session // and when there are no agents available... switch (endEvent.reason){ case SCSChatEndReasonAgent: description = @"The agent has ended the session."; break; case SCSChatEndReasonNoAgentsAvailable: description = @"It looks like there are no agents available. Try again later."; break; // TO DO: Handle other reasons default: description = @"Session ended for an unknown reason."; break; } UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Session Ended" message:description preferredStyle:UIAlertControllerStyleAlert]; UIAlertAction* okAction = [UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:nil]; [alert addAction:okAction]; [self presentViewController:alert animated:YES completion:nil]; } - (void)session:(id)session didError:(NSError *)error fatal:(BOOL)fatal { // TO DO: Handle error condition NSLog(@"Chat error: \(error.localizedDescription)"); } @end ```