Send your first message

Sendbird Chat SDK for Android is a development kit that enables an easy and fast integration of standard chat features into client apps. 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.

If you are looking to build an app with chat features, we recommend you build a client app on top of our sample app. If you already have an app and you are looking to add chat to it, proceed with this guide to integrate chat into your app. This guide walks you through installing the Chat SDK in your app, creating a channel, and sending your first message to the channel.

Note: To implement Kotlin in your app, see our tutorials on How to build in-app chat using Kotlin Part 1 and Part 2.

The minimum requirements for Chat SDK for Android are the following.

• Android 5.0 (API level 21) or higher
• Java 8 or higher
• Android Gradle plugin 3.4.2 or higher

Note: The 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.

In this quickstart guide, you will be installing Sendbird SDK, implementing codes to create a open channel with a user, and send a message within a few minutes. Before you start, you need to have the following:

• Sendbird application on Sendbird Dashboard
• A user in the Sendbird application

A Sendbird application comprises everything required in a chat service including users, messages, and channels. You need the Application ID of your Sendbird application from the dashboard when initializing the Chat SDK.

1. Go to Sendbird Dashboard and create an account for a free trial. If you already have a Sendbird account, sign into your account.

2. Create a new application by clicking Create + at the bottom right of your screen.

3. Enter a name for your application. Choose a Product Type and Region. Then, click Confirm.

4. Click the application you just created under Applications. You will see the application's Application ID which you will need when initializing the Chat SDK.

Note: 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.

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

In this guide, we will create a user on the Sendbird dashboard first.

1. Go to the Users menu on the left-hand side of the dashboard and click Create user+.

2. Enter the User ID and Nickname. It is recommended that you check the box next to Issue access token for user authentication. Then, click Create.

Note: Sendbird supports user authentication through access token for stronger security. However, on the dashboard, you can also configure the token permission in Settings > Application > Security > Access token permission to allow users without a token to access our functionalities. To learn more, see Authentication.

3. Copy and store the user ID. You will use it to connect to the Sendbird server.

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 Overview for Android.

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.

To send a message in a client app, you should build and configure an in-app chat using Sendbird Chat SDK, which can be installed through Gradle or by accessing our remote repository.

You can install the Chat SDK for Android through Gradle.

If you are using Gradle 6.8 or higher, add the following to your settings.gradle file:

dependencyResolutionManagement {
    repositories {
        maven { setUrl("https://repo.sendbird.com/public/maven") }
    }
}

If you are using Gradle 6.7 or lower, add the following code to your root build.gradle file:

allprojects {
    repositories {
        maven { setUrl("https://repo.sendbird.com/public/maven") }
    }
}

Note: Make sure the above code block isn't added to your module build.gradle file.

Add the dependency to your module build.gradle file.

dependencies {
    implementation("com.sendbird.sdk:sendbird-chat:4.21.1")
}

The Chat SDK requires system permissions. These permissions allow the Chat SDK to communicate with the 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" />

If you're building your APK with minifyEnabled true, add the following line to the module's ProGuard rules file.

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

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 your Sendbird application's Application ID, which can be found on the Sendbird Dashboard.

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

Before initializing, you should determine whether to enable local caching using InitParams and InitResultHandler() in the SendbirdChat.init() method. The useCaching property of InitParams determines whether or not the client app is going to use local storage through the SDK. If you want to build a client app without our local caching functionalities, set the value of useCaching to false.

Note: If you aren't using local caching, onMigrationStarted() and onInitFailed() in InitResultHandler() won't be called. To learn more, see Initialize the Chat SDK with APP_ID.

SendbirdChat.init(
    InitParams(APP_ID, applicationContext, useCaching = true),
    object : InitResultHandler {
        override fun onMigrationStarted() {
            Log.i("Application", "Called when there's an migration in local cache.")
        }

        override fun onInitFailed(e: SendbirdException) {
            when (e.code) {
                SendbirdError.ERR_INITIALIZATION_CANCELED -> {
                    Log.i("Application", "Called when initialize failed for some reason such as empth APP_ID. Retry SendbirdChat.init() again with correct InitParams.")
                }
                SendbirdError.ERR_DATABASE_ERROR_ENCRYPTION -> {
                    Log.i("Application", "Called when initialize failed when InitParams.LocalCacheConfig.SqlcipherConfig is set but SqlCipher dependency is not set. Please add the dependency and try SendbirdChat.init again.")
                }
                else -> {
                    Log.i("Application", "Called when initialize failed. SDK will still operate properly as if useLocalCaching is set to false.")
                }
            }
        }

        override fun onInitSucceed() {
            Log.i("Application", "Called when initialization is completed.")
        }
    }
)

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

While it is also possible to invoke SendbirdChat.init() from the onCreate() method of an Activity or a Fragment as shown below, this approach requires additional considerations. For instance, if you need to mark a push notification as delivered when the app is in the background or terminated, an Activity or Fragment may not be created, leaving only the Application active to call the SendbirdChat.init() method. For more details, please refer to the Mark push notifications as delivered page.

SendbirdChat.init(
    InitParams("APP_ID", applicationContext, useCaching = true).apply {
        // let SDK know it's called from foreground
        isForeground = true
    },
    object : InitResultHandler {
        override fun onMigrationStarted() {
            Log.i("Application", "Called when there's an update in Sendbird server.")
        }

        override fun onInitFailed(e: SendbirdException) {
            Log.i("Application", "Called when initialize failed. SDK will still operate properly as if useLocalCaching is set to false.")
        }

        override fun onInitSucceed() {
            Log.i("Application", "Called when initialization is completed.")
        }
    }
)

You need a user connected to the Sendbird server first before sending a message to a channel.

• If you already have a user in your Sendbird application: In connect(), specify a user ID from the user list in your Sendbird application.

• If you don't have an existing user: Specifying a unique userId in connect() will automatically generate a new user in your Sendbird application before being connected.

Note: Sendbird supports user authentication via access tokens, but defaults to allowing access without a token for ease of initial use. For enhanced security, we recommend adjusting access settings under Settings > Application > Security > Access token permission on the dashboard for new users. To learn about access token and authentication, see the Authentication guide.

// Use the ID of a user you've created on the dashboard.
// If there isn't one, specify a unique ID so that a new user can be created with the value.
SendbirdChat.connect(userId) { user, e ->
    if (user != null) {
        if (e != null) {
            // Proceed in offline mode with the data stored in the local database.
            // Later, connection is made automatically,
            // and can be notified through ConnectionHandler.onReconnectSucceeded().
        } else {
            // Proceed in online mode.
        }
    } else {
        // Handle error.
    }
}

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

For Chat SDKs that don't use local caching, the connection process remains the same. When an error occurs, the SDK must attempt to reconnect again.

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

OpenChannel.createChannel(OpenChannelCreateParams()) { channel, e ->
    if (e != null) {
        // Handle error.
    }

    // An open channel is successfully created.
    // You can get the open channel's data from the result object passed to the callback handler.
}

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

Enter the channel to send and receive messages.

// The following sample code continues from Step 5.
OpenChannel.createChannel(OpenChannelCreateParams()) { channel, e ->
    if (e != null) {
        // Handle error.
    }

    // Call the instance method of the result object in the openChannel parameter
    // of the callback handler.
    channel?.enter { e ->
        if (e != null) {
            // Handle error.
        }

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

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(UserMessageCreateParams(MESSAGE)) { message, e ->
    if (e != null) {
        // Handle error.
    }

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