Android
Quick Start

Quick Start

Integrate real-time chat in your Android client apps with speed and efficiency. Our Chat SDK for Android helps you to focus on the client side implementation of initializing, configuring and building the chat. On the server side, Sendbird ensures reliable infra management services with the Chat SDK. This quick start shows a brief overview of the Chat SDK’s structure and features, then goes through the preliminary steps of implementing the Chat SDK in your own project.


Try the sample app

Our sample app has the core features of the Chat SDK. Download the app from our GitHub repository to get an idea of what you can build with the actual SDK and start building in your project.

Download Sample App

Note: The fastest way to see our Chat SDK in action is to build your chat app on top of our sample app. Make sure to change the application ID of the sample app to your own. Go to the Create a Sendbird application from your dashboard section to learn more.


How Sendbird Chat SDK works with your app

It is simple to implement chat in your client app with the Chat SDK: a user logs in, sees a list of channels, selects or creates a channel, and sends a message to the channel while receiving messages from other users within the channel.

We provide two types of channels: open and group. An open channel is a public channel anyone can participate in and chat with others. A group channel is a private channel that users can join as new members through invitation only, and has numerous distinctive properties and features compared to an open channel. There are a variety of group channel subtypes such as a public group channel working like an open channel.

All sent messages within channels are automatically delivered to channel event handlers registered to your app. While the SendBird instance in your user's client app is connected to Sendbird server, the event handlers receive callbacks from the server through onMessageReceived(), onUserJoined(), and other methods. These callbacks contain message or channel objects with the latest information of an incoming message or other events related to the objects.


Requirements

The minimum requirements for Chat SDK for Android are:

  • Android 4.0 (API level 14) or higher
  • Java 7 or higher
  • Gradle 3.4.0 or higher

Install and configure the Chat SDK

If you are ready to integrate chat to your app, follow the step-by-step instructions below.

Step 1: Create a Sendbird application from your dashboard

A Sendbird application comprises everything required in a chat service including users, message, and channels. To create an application:

  1. Go to the Sendbird Dashboard and enter your email and password, and create a new account. You can also sign up with a Google account.
  2. When prompted by the setup wizard, enter your organization information to manage Sendbird applications.
  3. Lastly, when your dashboard home appears after completing setup, click Create App at the top-right corner. A Sendbird application can also be created through the Chat API.

Only one Sendbird application can be integrated per app for your service regardless of the platform. All users within your Sendbird application can communicate with each other across all platforms. This means that your iOS, Android, and web client app users can all send and receive messages with one another without any further setup.

Note: All data is limited to the scope of a single application, and users in different Sendbird applications can't chat with each other.

Step 2: Install the Chat SDK

Installing the Chat SDK is simple if you’re familiar with using external libraries or SDKs. To install the Chat SDK using Gradle, add the following lines to the project's top-level build.gradle file.

Note: Chat SDK can be downloaded through JCenter Maven repository. Check your code to see if the jcenter() is added in the build.gradle file.

build.gradle
Light Color Skin
Copy
dependencies {
    implementation 'com.sendbird.sdk:sendbird-android-sdk:3.0.140'
}

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

Download Latest SDK

Step 3: Grant system permissions to the Chat SDK

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 grant system permissions, add the following lines to your AndroidManifest.xml file.

AndroidManifest.xml
Light Color Skin
Copy
<uses-permission android:name="android.permission.INTERNET" />

<!-- READ/WRITE_EXTERNAL_STORAGE permissions are required to upload or download files from/into external storage. -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

(Optional) Step 4: Configure ProGuard to shrink code and resources

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

Light Color Skin
Copy
-dontwarn com.sendbird.android.shadow.**

Send your first message

The Chat SDK simplifies chat features into an effortless and straightforward process. To send your first message, do the following steps:

Note: The methods in the following steps are all asynchronous, excluding the SendBird.init() method. 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 4: Enter the channel to learn more about how you can nest the openChannel.enter() in the OpenChannel.getChannel() method.

Step 1: Initialize the Chat SDK

Initialization binds the Chat SDK to Android’s context, thereby allowing it to respond to connection and state changes. To the init() method, pass the App ID of your Sendbird application in the dashboard to initialize the Chat SDK.

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

Light Color Skin
Copy
SendBird.init(APP_ID, Context context);

Step 2: Connect to Sendbird server

Connect a user to Sendbird server using their unique user ID. Any untaken user ID is automatically registered as a new user to the Sendbird system before being connected, while an existing ID is allowed to log in directly.

Note: Go to the Authentication page to learn more about authenticating with an access token.

Light Color Skin
Copy
SendBird.connect(USER_ID, new SendBird.ConnectHandler() {
    @Override
    public void onConnected(User user, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});

Step 3: Create a new open channel

Create an open channel. Once created, all users in your Sendbird application can easily participate in the channel.

Note: In a similar fashion, you can create a group channel by inviting users as new members to the channel.

Light Color Skin
Copy
OpenChannel.createChannel(new OpenChannel.OpenChannelCreateHandler() {
    @Override
    public void onResult(OpenChannel openChannel, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});

Step 4: Enter the channel

Enter the channel to send and receive messages.

Light Color Skin
Copy
OpenChannel.getChannel(CHANNEL_URL, new OpenChannel.OpenChannelGetHandler() {
    @Override
    public void onResult(OpenChannel openChannel, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }

        openChannel.enter(new OpenChannel.OpenChannelEnterHandler() {
            @Override
            public void onResult(SendBirdException e) {
                if (e != null) {    // Error.
                    return;
                }
            }
        });
    }
});

Step 5: Send a message to the channel

Finally, send a message to the channel. There are three types: a user message is a plain text, a file message is a binary file, such as an image or PDF, and an admin message is a plain text sent through the dashboard or Chat API.

Light Color Skin
Copy
openChannel.sendUserMessage(MESSAGE, new BaseChannel.SendUserMessageHandler() {
    @Override
    public void onSent(UserMessage userMessage, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});