Embedded Service Chat SDK for Android Developer Guide

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

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

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:

    In Kotlin:

    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:

    In Kotlin:

    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:

    In Kotlin:

    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.

    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:

    Sample alternate configuration in Kotlin:

  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