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

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.
Installed the SDK. To learn more, see Install the Service Chat SDK for iOS.

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:
```
import ServiceCore
import ServiceChat
```
In Objective-C:
```
@import ServiceCore;
@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:

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

(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:
```
ServiceCloud.shared().chatUI.showChat(with: config!)
```
In Objective-C:
```
[[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.
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.

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?

Example

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:

Implement the SCSChatSessionDelegate 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:) method and show a dialog when appropriate.

In Swift:

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:

#import "ViewController.h"
@import ServiceCore;
@import ServiceChat;

@interface ViewController : UIViewController <SCSChatSessionDelegate>

@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<SCSChatSession>)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<SCSChatSession>)session didError:(NSError *)error fatal:(BOOL)fatal {
  // TO DO: Handle error condition
  NSLog(@"Chat error: \(error.localizedDescription)");
}

@end