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.

Before You 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

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 use the Chat Core API with your own custom UI. To use the default UI, see Quick Setup: Chat in the Service Chat SDK.

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

Create an SCSChatConfiguration object.

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"

See Configure a Chat Session on how to configure a chat session.

Implement SCSChatSessionDelegate and handle the relevant session-related methods.

Using this delegate, you can:
- Detect state transitions with session(didTransitionFrom:to:).
- Detect the end of the session with session(didEnd:).
- Detect error conditions with session(didError:fatal:).
- Detect queue state changes with session(didUpdateQueuePosition:estimatedWaitTime:). Pass your implementation to the SCSChat instance.
In Swift:
1ServiceCloud.shared().chatCore.add(delegate: mySessionDelegate)
In Objective-C:
1[[SCServiceCloud sharedInstance].chatCore addDelegate:mySessionDelegate];
To learn more, see Listen for State Changes and Events.
Implement SCSChatEventDelegate and handle the relevant event-related methods.

Using this delegate, you can:
- Detect when an agent joins with session(agentJoined:).
- Detect when an agent leaves with session(agentLeftConference:).
- Detect when an outgoing message is sent with session(processedOutgoingMessage:).
- Detect when the delivery status of a message has been updated with session(didUpdateOutgoingMessageDeliveryStatus:).
- Detect when an incoming message arrives with session(didReceiveMessage:).
- Detects when a URL is found in an message with session(didReceiveURL:).
- Detect when a chat bot menu arrives with session(didReceiveChatBotMenu:).
- Detect when a chat bot menu item is selected with 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 instance.
In Swift:
1ServiceCloud.shared().chatCore.addEvent(delegate: myEventDelegate)
In Objective-C:
1[[SCServiceCloud sharedInstance].chatCore addEventDelegate:myEventDelegate];

Start the session using startSession(with:) on SCSChat.

In Swift:

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

In Objective-C:

1[[SCServiceCloud sharedInstance].chatCore startSessionWithConfiguration:config];

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.