Android
Quick Start

Quick Start

Integrate real-time chat in your Android client apps with speed and efficiency. Our Android SDK 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 SDK. This quick start shows a brief overview of the SDK’s structure and features, then goes through the preliminary steps of implementing the SDK in your own project.


Try the sample app

Our sample app has the core features of the 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 SDK in action is to build your messaging 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 new SendBird application from your dashboard section to learn more.


How SendBird works with your app

It is simple to implement messaging in your client app with the Android 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.


Install and configure the 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

First, create your SendBird application which comprises everything required in a chat service such as users, messages, and channels.

  1. In the SendBird Dashboard, type your email and password to create a new account. You can also sign in with or sign up for a Google or GitHub 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 for a new application. You can also create via the Platform API.

You can only integrate one SendBird application per app for your service regardless of the platforms. All users within your SendBird application can communicate with each other across all platforms. This means that your iOS, Android, web, .NET, and Unity client app users can all chat with one another without any further setup. Note that all data are limited to the scope of a single application, and users in different SendBird applications can't talk to each other.

Step 2: Install the SDK

Installing the Android SDK is simple if you’re familiar with using external libraries or SDKs. To install the SDK using Gradle, add the following lines to a build.gradle file at the app level.

build.gradle
Light Color Skin
Copy
repositories {
    maven { url "https://raw.githubusercontent.com/sendbird/SendBird-SDK-Android/master/" }
}
dependencies {
    implementation 'com.sendbird.sdk:sendbird-android-sdk:3.0.111'
}

Alternatively, you can download the .jar 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 SDK

The Android SDK requires system permissions. These permissions allow the 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 Android SDK simplifies messaging 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 SDK

Initialization binds the 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 SDK.

Note: The SendBird.init() method must be called once across your Android client app. We recommend you initialize the Android 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 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 Platform API.

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