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.

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.

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

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 Service Chat SDK.

  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 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 on how to configure a chat session.

  3. Implement SCSChatSessionDelegate and handle the relevant session-related methods.

    Using this delegate, you can:

    Pass your implementation to the SCSChat 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.

  4. Implement SCSChatEventDelegate and handle the relevant event-related methods.

    Using this delegate, you can:

    Pass your implementation to the SCSChat instance.

    In Swift:

    ServiceCloud.shared().chatCore.addEvent(delegate: myEventDelegate)

    In Objective-C:

    [[SCServiceCloud sharedInstance].chatCore addEventDelegate:myEventDelegate];
  5. Start the session using startSession(with:) on SCSChat.

    In Swift:

    ServiceCloud.shared().chatCore.startSession(config)

    In Objective-C:

    [[SCServiceCloud sharedInstance].chatCore startSessionWithConfiguration:config];
  6. Send activity to the SCSChatSession object found in SCSChat.

    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.