To add Chat to your iOS app, create an SCSChatConfiguration object and pass it to the showChat method.
The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then. During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement in Help.
Important
Before running through these steps, be sure you’ve already:
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.
Import the SDK. Wherever you intend to use the Chat SDK, be sure to import the ServiceCore framework and the ServiceChat framework.
In Swift:
1import ServiceCore
2import ServiceChatIn Objective-C:
1@import ServiceCore;
2@import ServiceChat;Create an SCSChatConfiguration instance with information about your LiveAgent pod, your Salesforce org ID, the deployment ID, and the button ID.
In Swift:
1let config = SCSChatConfiguration(liveAgentPod: "TO_DO_POD_NAME",
2 // e.g. "d.gla5.gus.salesforce.com"
3 orgId: "TO_DO_ORG_ID",
4 // e.g. "00DB00000003Rxz"
5 deploymentId: "TO_DO_DEPLOYMENT_ID",
6 // e.g. "573B00000005KXz"
7 buttonId: "TO_DO_BUTTON_ID")
8 // e.g. "575C00000004h3m"In Objective-C:
1SCSChatConfiguration *config =
2 [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"TO_DO_POD_NAME"
3 // e.g. "d.gla5.gus.salesforce.com"
4 orgId:@"TO_DO_ORG_ID"
5 // e.g. "00DB00000003Rxz"
6 deploymentId:@"TO_DO_DEPLOYMENT_ID"
7 // e.g. "573B00000005KXz"
8 buttonId:@"TO_DO_BUTTON_ID"];
9 // e.g. "575C00000004h3m"You can get the required parameters for this method from your Salesforce org. See Get Chat Settings from Your Org. If your Salesforce admin hasn’t already set up Chat in Service Cloud or you need more guidance, see Org Setup for Chat in Lightning Experience with a Guided Flow.
Note
(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 for more information.
(Optional) Customize the appearance with the configuration object.
You can configure the colors, fonts, and images to your interface with an SCAppearanceConfiguration instance. It contains the methods setColor, setFontDescriptor, and setImage. You can also configure the strings used throughout the interface. See SDK Customizations with the Service Chat SDK for iOS.
(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 and Create or Update Salesforce Records from a Chat Session for more information.
To start a chat session, call the showChat(with:showPrechat:) method on SCSChatInterface.
In Swift:
1ServiceCloud.shared().chatUI.showChat(with: config!)In Objective-C:
1[[SCServiceCloud sharedInstance].chatUI showChatWithConfiguration:config];The showChat method must be called on the main UI thread.
Note
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.
Listen for events and handle error conditions.
You can detect when a session ends by implementing the session(didEnd:) method on the SCSChatSessionDelegate delegate. Register this delegate using the add(delegate:) method on your SCSChat 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.
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.
Note
These steps embed the chat experience into your app.
To learn about chat timeout limitations on iOS devices, see When does a chat session time out?
Note
To use this example code, create a Single View Application and Install the Service Chat SDK for iOS.
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:
SCSChatSessionDelegate protocol so that you can be notified when there are errors or state changes.self as a chat delegate.session(didEnd:) method and show a dialog when appropriate.In Swift:
1import UIKit
2import ServiceCore
3import ServiceChat
4
5class ViewController : UIViewController, SCSChatSessionDelegate {
6
7 override func viewDidLoad() {
8 super.viewDidLoad()
9
10 // Add our chat delegate
11 ServiceCloud.shared().chatCore.add(delegate: self)
12 }
13
14 @IBAction func startChat(_ sender: AnyObject) {
15
16 // Create config object
17 if let config = SCSChatConfiguration(liveAgentPod: "YOUR-POD-NAME",
18 orgId: "YOUR-ORG-ID",
19 deploymentId: "YOUR-DEPLOYMENT-ID",
20 buttonId: "YOUR-BUTTON-ID") {
21
22 // Start a session
23 ServiceCloud.shared().chatUI.showChat(with: config)
24 }
25 }
26
27 func session(_ session: SCSChatSession!, didEnd endEvent: SCSChatSessionEndEvent!) {
28
29 var description = ""
30
31 // Here we'll handle the situation where the agent ends the session
32 // and when there are no agents available...
33 switch endEvent.reason {
34 case .agent:
35 description = "The agent has ended the session."
36 case .noAgentsAvailable:
37 description = "It looks like there are no agents available. Try again later."
38 // TO DO: Handle other reasons
39 default:
40 description = "Session ended for an unknown reason."
41 }
42
43 let alert = UIAlertController(title: "Session Ended",
44 message: description,
45 preferredStyle: .alert)
46 let okAction = UIAlertAction(title: "OK",
47 style: .default,
48 handler: nil)
49 alert.addAction(okAction)
50 self.present(alert, animated: true, completion: nil)
51 }
52
53 func session(_ session: SCSChatSession!, didError error: Error!, fatal: Bool) {
54 // TO DO: Handle error condition
55 NSLog("Chat error: \(error.localizedDescription)")
56 }
57}In Objective-C:
1#import "ViewController.h"
2@import ServiceCore;
3@import ServiceChat;
4
5@interface ViewController : UIViewController <SCSChatSessionDelegate>
6
7@end
8
9@implementation ViewController
10
11- (void)viewDidLoad {
12 [super viewDidLoad];
13
14 // Add our chat delegate
15 [[SCServiceCloud sharedInstance].chatCore addDelegate:self];
16}
17
18- (IBAction)startChat:(id)sender {
19
20 // Create config object
21 SCSChatConfiguration *config =
22 [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"YOUR-POD-NAME"
23 orgId:@"YOUR-ORG-ID"
24 deploymentId:@"YOUR-DEPLOYMENT-ID"
25 buttonId:@"YOUR-BUTTON-ID"];
26 // Start the session
27 [[SCServiceCloud sharedInstance].chatUI showChatWithConfiguration:config];
28}
29
30- (void)session:(id<SCSChatSession>)session didEnd:(SCSChatSessionEndEvent *)endEvent {
31
32 NSString *description = nil;
33
34 // Here we'll handle the situation where the agent ends the session
35 // and when there are no agents available...
36 switch (endEvent.reason){
37 case SCSChatEndReasonAgent:
38 description = @"The agent has ended the session.";
39 break;
40 case SCSChatEndReasonNoAgentsAvailable:
41 description = @"It looks like there are no agents available. Try again later.";
42 break;
43 // TO DO: Handle other reasons
44 default:
45 description = @"Session ended for an unknown reason.";
46 break;
47 }
48
49 UIAlertController *alert = [UIAlertController
50 alertControllerWithTitle:@"Session Ended"
51 message:description
52 preferredStyle:UIAlertControllerStyleAlert];
53
54 UIAlertAction* okAction = [UIAlertAction
55 actionWithTitle:@"OK"
56 style:UIAlertActionStyleDefault
57 handler:nil];
58
59 [alert addAction:okAction];
60 [self presentViewController:alert animated:YES completion:nil];
61}
62
63- (void)session:(id<SCSChatSession>)session didError:(NSError *)error fatal:(BOOL)fatal {
64 // TO DO: Handle error condition
65 NSLog(@"Chat error: \(error.localizedDescription)");
66}
67
68@end
j