Skip to main content

Getting Started#

Let's see how you can get started with the Android Chat SDK after adding the required dependencies. This page shows you how to initialize the SDK in your app.


If you're looking for a complete, step-by-step guide that includes setting up an Android project from scratch, try the Android In-App Messaging Tutorial instead.

Creating a ChatClient#

Your first step is initializing the ChatClient, which is the main entry point for all operations in the library. ChatClient is a singleton: you'll create it once and re-use it across your application.

A best practice is to initialize ChatClient in the Application class:

class App : Application() {
override fun onCreate() {
val chatClient = ChatClient.Builder("apiKey", applicationContext).build()

The Builder for ChatClient exposes configuration options for features such as Logging.


To generate an API key, you can sign up for a free 30-day trial. You can then access your api key in the Dashboard.

If you create the ChatClient instance following the pattern in the previous example, you will be able to access that instance from any part of your application using the instance() method:

class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
val chatClient = ChatClient.instance() // Returns the singleton instance

Adding the Offline Plugin#

If you want to have offline support or use the UI Components package, you'll need to initialize the OfflinePlugin class and add it to the ChatClient.Builder. You can skip this initialization step if you're only using the low-level client.

The initialization should be done using StreamOfflinePluginFactory:

val offlinePluginFactory = StreamOfflinePluginFactory(
config = Config(
// Enables the background sync which is performed to sync user actions done without the Internet connection.
backgroundSyncEnabled = true,
// Enables the ability to receive information about user activity such as last active date and if they are online right now.
userPresence = true,
// Enables using the database as an internal caching mechanism.
persistenceEnabled = true,
// An enumeration of various network types used as a constraint inside upload attachments worker.
uploadAttachmentsNetworkType = UploadAttachmentsNetworkType.NOT_ROAMING,
// Whether the SDK will use a new sequential event handling mechanism.
useSequentialEventHandler = false,
appContext = context,

ChatClient.Builder(apiKey, context).withPlugin(offlinePluginFactory).build()

For more about working with OfflinePlugin, see Offline Support

Connecting a User#

The next step is connecting the user. This requires a valid Stream Chat token. As you must use your API_SECRET to create this token, it is unsafe to generate this token outside of a secure server.

val user = User(
id = "bender",
name = "Bender",
image = "",

ChatClient.instance().connectUser(user = user, token = "userToken") // Replace with a real token
.enqueue { result ->
if (result.isSuccess) {
// Handle success
} else {
// Handle error

To learn about how to create a token and different user types, see Tokens & Authentication.

If the connectUser call was successful, you are now ready to use the SDK! 🎉


You shouldn't call connectUser if the user is already set! You can use ChatClient.instance().getCurrentUser() to verify if the user is already connected.

The methods of the ChatClient class allow you to create channels, send messages, add reactions, and perform many more low-level operations. You can also use the SDK's pre-built UI Components that will perform data fetching and sending for you, as described below.

Adding UI Components#

There are two UI Component implementations available: one built on regular, XML based Android Views, and another built from the ground up in Jetpack Compose.

Take a look at the Overview pages of the implementations to get started with them:

Did you find this page helpful?