Skip to content
Stream Chat official Android SDK. The tutorial covers how to build your own chat experience using either Java or Kotlin.
Branch: master
Clone or download
Latest commit 6d15c40 Oct 19, 2019


Build Status version Component Reference

stream-chat-android is the official Android SDK for Stream Chat, a service for building chat applications.

As a first step try the tutorial: Java Chat Tutorial, Kotlin Chat Tutorial.

You can sign up for a Stream account at This library includes both a low level chat SDK and a set of reusable UI components. Most users start out with the UI components, and fall back to the lower level API when they want to customize things.

Installing the Java Chat SDK

  • Step 1 Add repository into root build.gradle
allprojects {
    repositories {
    maven {
        url '' }
  • Step 2 Add library dependency into app build.gradle

See the jitpack badge above for the latest version number

android {
    dataBinding {
        enabled = true
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8

dependencies {
    implementation 'com.github.getstream:stream-chat-android:<latest-version>'


If you're using Proguard/R8 you'll want to have a look at the proguard file we use for the sample.

Setup Stream Chat

Make sure to initialize the SDK only once; the best place to do this is in your Application class.

public class BaseApplication extends Application {
    public void onCreate() {
        StreamChat.init("STREAM-API-KEY", getApplicationContext());

If this is a new Android app you will need to register BaseApplication inside AndroidManifest.xml as well.





With this you will be able to retrieve the shared Chat client from any part of your application using StreamChat.getInstance(). Here's an example:

public class MainActivity extends AppCompatActivity {

	protected void onCreate(Bundle savedInstanceState) {
		Client client = StreamChat.getInstance(this.getApplication());

Make sure that your AndroidManifest.xml file include INTERNET and ACCESS_NETWORK_STATE permissions:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="" package="...">


    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />



Initialize Chat for a user

  1. Retrieve the chat client:
Client client = StreamChat.getInstance(this.getApplication());
  1. Setup a user, you can use as many custom fields as you want. Both name and image are used automatically by UI components:
HashMap<String, Object> extraData = new HashMap<>();
extraData.put("name", "Happy Android");
extraData.put("image", "");
User user = new User(USER_ID, extraData);
  1. Setup chat for current user:
client.setUser(user, USER_TOKEN);

The USER_TOKEN variable is the unique token for the user with ID USER_ID in this case is hard-coded but in real-life it will be something that comes from your auth backend.

Once you called setUser you will be able to use Stream Chat APIs; all calls will automatically wait for the setUser call to complete. No need to add callbacks or complex syncronization code from your end.

If needed you can add callbacks to setUser via Client.onSetUserCompleted(ClientConnectionCallback)

client.onSetUserCompleted(new ClientConnectionCallback() {
    public void onSuccess(User user) {
    	Log.i(TAG, "user connected!");
	// do some more initialization

    public void onError(String errMsg, int errCode) {

Retrieve tokens server-side / Handle tokens with expiration

If you generate user tokens with an expiration (exp field) you can configure the SDK to request a new token upon expiration.

Here's an example where we make an HTTP call to retrieve a token for current user.

client.setUser(user, listener -> {
            OkHttpClient httpClient = new OkHttpClient()

            // request the token for this user
            Request request = new Request.Builder()
                    .header("Authorization", "user-session-id")

            httpClient.newCall(request).enqueue(new Callback() {
                public void onFailure(@NotNull Call call, @NotNull IOException e) {
                    // the request to get the token failed

                public void onResponse(@NotNull Call call, @NotNull Response response) throws IOException {
                    Log.w(TAG, "getting the token worked!");

The listener will be called to fetch the user token and once the token is expired; the SDK will retry failed API calls and re-sync history so that no messages are lost during the renewal process.

Switch users

You can switch from a user to another by calling disconnect and setUser again. When doing so you are responsible of reloading/re-render the UI.

This example switches to a different user and calls the reload method on the ChannelListViewModel when setUser is completed.

void switchUser(String userId, String token) {
    Client client = StreamChat.getInstance(getApplication());

    User user = new User(userId);
    client.setUser(user, token);

    viewModel = ViewModelProviders.of(this).get(ChannelListViewModel.class);

    client.onSetUserCompleted(new ClientConnectionCallback() {
        public void onSuccess(User user) {

        public void onError(String errMsg, int errCode) {


Online status

Connection status to Chat is available via StreamChat.getOnlineStatus() which returns a LiveData object you can attach observers to.


UI Components


Java Chat Tutorial page Official API Docs

Supported features

  • Channels list UI
  • Channel UI
  • Message Reactions
  • Link preview
  • Images, Videos and Files attachments
  • Edit and Delete message
  • Typing Inditicators
  • Read Inditicators
  • Push Notifications
  • Image gallery
  • GIF support
  • Light/Dark themes
  • Style customization
  • UI customization
  • Threads
  • Slash commands
  • Offline support


Channel List loading icons spins forever

Not setting the lifecycle owner on a data binding can cause the channel list loading icon to spin forever

mBinding = DataBindingUtil.inflate(inflater, R.layout.fragment_chat, container, false);

Getting started

TODO: but with Android code examples

You can’t perform that action at this time.