Chat SDKs Android v3
Chat SDKs Android
Chat SDKs
Android
Version 3
Sendbird Chat SDK v3 for Android is no longer supported as a new version is released. Check out our latest Chat SDK v4

Send your first message

Copy link

With Sendbird Chat SDK for Android, you can efficiently integrate real-time chat into a client app. On the client-side implementation, you can initialize and configure the chat with minimal effort. On the server-side, Sendbird ensures reliable infra-management services for your chat within the app.

This page demonstrates how to install the Chat SDK in your app so that you can send your first message in just a few simple steps.

Note: The fastest way to see Sendbird Chat SDK in action is to build your app on top of our sample app. Download the sample app to jumpstart your build. To implement Kotlin in your app, see tutorials for How to build in-app chat using Kotlin Part 1 and Part 2.


Requirements

Copy link

The minimum requirements for Chat SDK for Android are:

  • Android 4.1 (API level 16) or higher
  • Java 7 or higher
  • Android Gradle plugin 3.4.0 or higher

Note: Sendbird server supports Transport Layer Security (TLS) from versions 1.0 up to 1.3. For example, in the server regions where TLS 1.3 isn’t available, lower versions from 1.0 to 1.2 will be sequentially supported for secure data transmission.


Before you start

Copy link

Before installing Sendbird Chat SDK, you need to create a Sendbird application on Sendbird Dashboard, which comprises everything required in a chat service including users, messages, and channels. You will need the Application ID of your Sendbird application from the dashboard when initializing the Chat SDK.

Each Sendbird application can be integrated with a single client app. Within the same application, users can communicate with each other across all platforms, whether they are on mobile devices or on the web.

Sendbird UIKit

Copy link

UIKit is a Sendbird Chat SDK add-on with user interfaces that enables easy and fast integration of standard chat features into new or existing client apps.

If you would like a sample app with embedded UI, see UIKit Quickstart for Android.

Access control list

Copy link

Sendbird provides various access control options when using the Chat SDK. By default, the following attributes are turned on to avoid unexpected errors when creating sample apps and sending your first message:

  • Allow retrieving user list
  • Allow updating user metadata
  • Allow creating open channels
  • Allow creating group channels

However, this may grant access to unwanted data or operations, leading to potential security concerns. To manage your access control settings, you can turn on or off each option in Settings > Application > Security > Access control list on Sendbird Dashboard.


Get started

Copy link

To send a message in a client app, you should build and configure an in-app chat using Sendbird Chat SDK. Sendbird Chat SDK can be installed through Gradle.

Step 1 Install the Chat SDK

Copy link

If you're using Gradle 6.8 or higher, add the following code to your settings.gradle file. If Gradle 6.7 or lower is used, add the following code to your root build.gradle file. See this release note to learn more about updates to Gradle.

Gradle 6.8 or higherGradle 6.7 or lower
// Add the following to your settings.gradle file.

dependencyResolutionManagement {
    repositories {
        maven { url "https://repo.sendbird.com/public/maven" }
    }
}

Next, for all Gradle versions, add the dependency to your module build.gradle file.

dependencies {
    implementation 'com.sendbird.sdk:sendbird-android-sdk:3.1.27'
}

Alternatively, you can download the .aar file. Copy this file into your libs/ folder, and make sure you include the library in your build.gradle file as well.

Step 2 Request to access system permissions

Copy link

The Chat SDK requires system permissions. These permissions allow the Chat SDK to communicate with Sendbird server and read from and write on a user device’s storage. To request system permissions, add the following lines to your AndroidManifest.xml file.

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

Step 3 (Optional) Configure ProGuard to shrink code and resources

Copy link

When you build your APK with minifyEnabled true, add the following line to the module's ProGuard rules file.

-dontwarn com.sendbird.android.shadow.**

Step 4 Initialize the Chat SDK

Copy link

Now, initialize the Chat SDK in the app to allow the Chat SDK to respond to changes in the connection status of Android client apps. Initialization requires the App ID, which can be found on Sendbird Dashboard.

Note: The methods in the following steps are all asynchronous. This means that when using asynchronous methods, your client app must receive success callbacks from Sendbird server through their callback handlers in order to proceed to the next step. A good way to do this is the nesting of methods: Go to Step 7: Enter the channel to learn more about how you can nest the openChannel.enter() in the OpenChannel.getChannel() method.

With local caching, two new parameters have been added to the SendBird.init() method, which are useLocalCaching and InitResultHandler(). The following will show how you can initialize the Chat SDK with or without local caching.

The useLocalCaching determines whether the client app will use the local storage through Sendbird Chat SDK or not. If you want to build a client app with our local caching functionalities, set the useLocalCaching to true.

The InitResultHandler() gets the initialization status through different event handlers. The onMigrationStarted() is called when there's an upgrade in the local database. Meanwhile, the onInitFailed() and onInitSucceeded() informs the client app whether the initialization is completed.

Note: If you are not using local caching, the onMigrationStarted() and onInitFailed() in the InitResultHandler() won't be called.

If the onInitFailed() is called when you set the useLocalCaching to true, the SDK will operate normally and change the value of the useLocalCaching to false. If you still wish to use the local caching, clear the database using the SendBird.clearCachedData(getApplicationContext(), CompletionHandler); and try the SendBird.init() again with the useLocalCaching set to true.

With local cachingWithout local caching
// When the useLocalCaching is set to true.
SendBird.init(APP_ID, getApplicationContext(), true, new InitResultHandler() {
    @Override
    public void onMigrationStarted() {
        Log.i("Application", "Called when there's an update in Sendbird server.");
    }

    @Override
    public void onInitFailed(SendBirdException e) {
        Log.i("Application", "Called when initialize failed. SDK will still operate properly as if useLocalCaching is set to false.");
    }

    @Override
    public void onInitSucceed() {
        Log.i("Application", "Called when initialization is completed.");
    }
});

Note: The SendBird.init() method must be called across a client app at least once. It is recommended to initialize the Chat SDK with the onCreate() method of the Application instance.

Step 5 Connect to Sendbird server

Copy link

You will need a user in order to send a message to a channel. You can either create a user on our dashboard or you can use a unique ID that hasn’t been taken by any of your Sendbird application users. In the latter case, a new user will be automatically created in your Sendbird application before being connected.

For those who use the Chat SDK with local caching, refer to the sample codes on the first tab. If not, refer to the second tab.

Note: To learn more about authenticating with an access token, go to Authentication.

With local cachingWithout local caching
// When useLocalCaching is set to true.
SendBird.connect(userId, new SendBird.ConnectHandler() {
    @Override
    public void onConnected(User user, SendBirdException e) {
        if (user != null) {
            if (e != null) {
                // Proceed in offline mode with the data stored in the local database.
                // Later, connection will be made automatically
                // and can be notified through the ConnectionHandler.onReconnectSucceeded().
            } else {
                // Proceed in online mode.
            }
        } else {
            // Handle error.
        }
    }
});

Note: You must receive the result of the InitResultHandler() before calling the connect(). Any methods can be called once the user is connected to Sendbird server.

Step 6 Create a new open channel

Copy link

Create an open channel using the following codes. Open channels are where all users in your Sendbird application can easily participate without an invitation.

OpenChannel.createChannel(new OpenChannel.OpenChannelCreateHandler() {
    @Override
    public void onResult(OpenChannel openChannel, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // An open channel is successfully created.
        // Through the openChannel parameter of the onResult() callback method,
        // you can get the open channel's data from the result object that Sendbird server has passed to the onResult().
    }
});

Note: You can also create a group channel to send a message. To learn more, see Create a channel in the Group channel page.

Step 7 Enter the channel

Copy link

Enter the channel to send and receive messages.

// The following sample code continues from Step 6.
OpenChannel.createChannel(new OpenChannel.OpenChannelCreateHandler() {
    @Override
    public void onResult(OpenChannel openChannel, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // Call the instance method of the result object in the openChannel parameter of the onResult() callback method.
        openChannel.enter(new OpenChannel.OpenChannelEnterHandler() {
            @Override
            public void onResult(SendBirdException e) {
                if (e != null) {
                    // Handle error.
                }

                // The current user successfully enters the open channel,
                // and can chat with other users in the channel by using APIs.
            }
        });
    }
});

Step 8 Send a message to the channel

Copy link

Finally, send a message to the channel. To learn about the message types you can send, refer to Message overview in Chat Platform API.

You can check the message you've sent in Sendbird Dashboard. To learn about receiving a message, refer to the receive messages through a channel event handler page.

openChannel.sendUserMessage(MESSAGE, new BaseChannel.SendUserMessageHandler() {
    @Override
    public void onSent(UserMessage userMessage, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // The message is successfully sent to the channel.
        // The current user can receive messages from other users
        // through the onMessageReceived() method of an event handler.
    }
});