Embedded Service Chat SDK for Android Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Embedded Service Chat SDK for Android Developer Guide
Release Notes
Service Cloud Setup
SDK Setup
Android Examples
Chat
Overview
Quick Setup
Use Einstein Bots with Chat
Handle Custom URLs in Chat
Listen for State Changes and Events
Show Pre-Chat Fields to User
Create or Update Salesforce Records from a Chat Session
Check Agent Availability
Transfer File to Agent
Block Sensitive Data in a Chat Session
Build Your Own UI with the Chat Core API
SDK Customizations
Troubleshooting
Data Protection and Security
Reference Documentation
Additional Resources
PDF

Quick Setup: Chat in the Service Chat SDK

To add Chat to your Android app, create a configuration object that points to your org and then create a Chat UI client.

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 starting, make sure that you’ve already:

To set up Chat with the default UI, create a configuration object that points to your org and then start a chat session. If you prefer to build your own user interface, see Build Your Own UI with the Chat Core API.

  1. Specify your Chat org settings.

    In Java:

    public static final String ORG_ID = "YOUR_ORG_ID";
public static final String DEPLOYMENT_ID = "YOUR_DEPLOYMENT_ID";
public static final String BUTTON_ID = "YOUR_BUTTON_ID";
public static final String LIVE_AGENT_POD = "YOUR_LAC_ORG_URL"; 
                                    // e.g. "d.la.salesforce.com"

    In Kotlin:

    val ORG_ID = "YOUR_ORG_ID"
val DEPLOYMENT_ID = "YOUR_DEPLOYMENT_ID"
val BUTTON_ID = "YOUR_BUTTON_ID"
val LIVE_AGENT_POD = "YOUR_LAC_ORG_URL"
             // e.g. "d.la.salesforce.com"

    You can get the required parameters from your Salesforce org. If your Salesforce admin hasn’t set up Chat in Service Cloud or you need more guidance, see Org Setup for Chat in Lightning Experience with a Guided Flow.

    Note

  2. Create a ChatConfiguration object using your org settings.

    In Java:

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

    In Kotlin:

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

    You can use the ChatConfiguration.Builder class to configure other behaviors, such as how to handle the pre-chat view (see Show Pre-Chat Fields to User) and how to specify the name of the visitor speaking with the agent (use the visitorName method).

    Tip

  3. Configure and launch a chat session using ChatUI, ChatUIConfiguration, and ChatUIClient.

    In Java:

    // Create a UI configuration instance from a core config object
// and start session!
ChatUI.configure(ChatUIConfiguration.create(chatConfiguration))
  .createClient(getApplicationContext())
  .onResult(new Async.ResultHandler<ChatUIClient>() {
      @Override public void handleResult (Async<?> operation, 
        ChatUIClient chatUIClient) {
            chatUIClient.startChatSession(MainActivity.this);
      }
});

    In Kotlin:

    // Create a UI configuration instance from a core config object
// and start session!
ChatUI.configure(ChatUIConfiguration.create(chatConfiguration))
  .createClient(applicationContext)
  .onResult { _, 
    chatUIClient -> chatUIClient.startChatSession(this@MainActivity) 
  }

    Don't create more than 1 instance of ChatUIClient. The system returns an Async error if there is already an active instance. The SDK only supports 1 session at a time per device. Wait until the chat session ends before attempting to start a new session.

    Warning

    When calling startChatSession, pass the context for the Activity that you want to show the chat UI on top of. The chat session starts minimized and the user can tap the thumbnail to go full screen. If you want the session to start in full-screen mode, call defaultToMinimized(false) on the builder.

    When the minimized view is visible, it displays the number of unread messages. This value represents the total number of bot, agent, and system messages that are unread.

    Note

    By default, the user's queue position is shown while the user waits for an agent. You can change this information from a position number to an estimated wait time using the queueStyle build method and specifying QueueStyle.EstimatedWaitTime. When using the estimated wait time, you can set the minimum (minimumWaitTime) and maximum (maximumWaitTime) wait time values. If the wait time exceeds the maximum value, a generic message appears, which you can customize (using the customizable chat strings). To understand the algorithm used for the estimated wait time, see the estimated wait time documentation in the Chat REST API Developer Guide. To hide queue information entirely, use a queue style of None.

    Sample alternate configuration in Java:

    ChatUIConfiguration uiConfig = new ChatUIConfiguration.Builder()
  .chatConfiguration(chatConfiguration)
  .queueStyle(QueueStyle.EstimatedWaitTime) // Use estimated wait time
  .defaultToMinimized(false)                // Start in full-screen mode
  .build();

    Sample alternate configuration in Kotlin:

    val uiConfig = ChatUIConfiguration.Builder()
  .chatConfiguration(chatConfiguration)
  .queueStyle(QueueStyle.EstimatedWaitTime) // Use estimated wait time
  .defaultToMinimized(false)                // Start in full-screen mode
  .build()
  4. (Optional) Customize the interface.

    You can customize the colors, strings, and other aspects of the interface. You can also localize the strings into other languages.

  5. (Optional) Add listeners for state changes or events.

    You can add listeners for state changes and events during a chat session and respond accordingly. For instance, when the client ends a session, you can display a dialog to the user. See Listen for State Changes and Events.

    If you use an incorrect button ID in your ChatConfiguration, the chat fails and your SessionStateListener reports a ChatEndReason of NetworkError.

    Warning

When a session launches, it appears minimized.

Chat session minimzed

The user can tap the session to make it full screen and begin a conversation with an agent.

Chat session full screen

When the app is in the background, the SDK ensures that the session remains open. A timeout should only occur when there is a connection issue, the agent closes the session, or the app is removed from memory.

Note