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

Set up Service Cloud to work with Chat. See Org Setup for Chat in Lightning Experience with a Guided Flow.
Installed the SDK. See Install the Service SDK for Android.

These steps describe how to use the Chat Core API. To use the default UI, see Quick Setup: Chat in the.

To listen for agent activity, create an AgentListener implementation.
From the agent listener, you can:
- Detect when an agent has joined using onAgentJoined(AgentInformation agentInformation).
- Detect when an agent is typing a message using onAgentIsTyping(boolean isAgentTyping).
- Receive an incoming message from an agent using onChatMessageReceived(ChatMessage chatMessage).
To listen for session state changes, create a SessionStateListener.
From a session state listener, you can:
- Detect when the session state changes using onSessionStateChange(ChatSessionState state). For example, this method is useful for when the session disconnects (ChatSessionState.Disconnected).
- Detect when the session ends using onSessionEnded(ChatEndReason endReason). This method is useful to know why a session ends and report the information to the user. For example, ChatEndReason.EndedByAgent is passed when the agent ends the session.
To learn more about using this listener, see Listen for State Changes and Events.
To listen for changes related to a user's position or estimated wait time in the agent queue, create a QueueListener.
When a user is trying to connect to an agent, you can monitor where the user is in the queue. The estimated wait time is returned in minutes and the queue position is an integer value related to the overall agent capacity.

When using the queue position number, the queue position is 0 if the agent capacity is greater than or equal to the number of customer requests. Otherwise, the position value represents how far the customer is from getting served by an agent.
1q = max(n - c, 0)
Where:
- q is the queue position
- n is the position of the customer compared to all waiting customers
- c is the total capacity of all agents
For example, if the total capacity is 10, the first 10 waiting visitors have a position of 0, the 11th has a position of 1, the 12th has a position of 2, and so on.
To listen for Einstein bot activity, create a ChatBotListener.
From a bot listener, you can:
- Detect when you receive a persistent footer menu from the Einstein bot with onChatFooterMenuReceived. A footer menu is always accessible to the user and typically handles options that are not context-specific, such as "Transfer to agent."
- Detect when you receive menu options from the Einstein bot with onChatMenuReceived.
- Detect when you receive choice button options from the Einstein bot with onChatButtonMenuReceived.

Build a ChatConfiguration object as described in Quick Setup: Chat in the.

In Java:

1// Create a core configuration instance
2ChatConfiguration chatConfiguration = 
3  new ChatConfiguration.Builder(ORG_ID, BUTTON_ID, 
4                                DEPLOYMENT_ID, LIVE_AGENT_POD)
5                                .build();

In Kotlin:

1// Create a core configuration instance
2val chatConfiguration = 
3  ChatConfiguration.Builder(ORG_ID, BUTTON_ID,
4                            DEPLOYMENT_ID, LIVE_AGENT_POD)
5                            .build()

Create a ChatCore object with your chat configuration object.

In Java:

1ChatCore core = ChatCore.configure(chatConfiguration);

In Kotlin:

1val core = ChatCore.configure(chatConfiguration)

Create a ChatClient, adding your listener objects.

Define ChatClient at the Application scope to ensure that the session is trackable throughout the application's lifetime rather than just within an Activity, for example.

In Java:

1private @Nullable ChatClient mChatClient;
2
3// ...
4
5core.createClient(this)
6  .onResult(new Async.ResultHandler<ChatClient>() {
7    @Override public void handleResult (Async<?> operation, 
8                                        @NonNull ChatClient chatClient) {
9      mChatClient = chatClient
10        .addSessionStateListener(myStateListener)
11        .addAgentListener(myAgentListener)
12        .addQueueListener(myQueueListener)
13        .addChatBotListener(myEinsteinBotListener);
14    }
15});

In Kotlin:

1var mChatClient: ChatClient? = null
2
3// ...
4
5core.createClient(this)
6  .onResult { operation, chatClient ->
7    mChatClient = chatClient
8      .addSessionStateListener(myStateListener)
9      .addAgentListener(myAgentListener)
10      .addQueueListener(myQueueListener)
11      .addChatBotListener(myEinsteinBotListener)
12  }

When you receive a chat client instance, a session has successfully started.

Perform session actions with the ChatClient object.
From the chat client object, you can perform the following functions:
- Tell the agent when the user is typing a message using setIsUserTyping(boolean isUserTyping).
- Send a message to the agent using sendChatMessage(String message).
- Handle file transfer activity using addFileTransferRequestListener(FileTransferRequestListener fileTransferRequestListener). See Transfer File to Agent.
- Handle Einstein bot responses with sendFooterMenuSelection, sendMenuSelection, and sendButtonSelection.
- End the chat session using endChatSession().

Embedded Service Chat SDK for Android Developer Guide

Build Your Own UI with the Chat Core API