Build an In-App Chat Feature with Jetpack Compose

If you're not using Compose yet, check out our Android tutorial with XML layouts!

To get started with the Jetpack Compose version of the Android Chat SDK, open Android Studio (Arctic Fox or later) and create a new project.

• Select the Empty Compose Activity template
• Name the project ChatTutorial
• Set the package name to com.example.chattutorial

Once you create and load the project, you need to add appropriate dependencies for Jetpack Compose.

Our SDKs are available from MavenCentral. Update your repositories in the settings.gradle file like so:

Go to the project level build.gradle file, and make sure that you're using Compose 1.2.1, Compose Compiler 1.3.0, and Kotlin 1.7.10 (or newer, compatible versions).

Depending on which version of Android Studio was used to create the project, the contents may look slightly differently:

Arctic Fox

Bumblebee and up

Next, you're going to add the Stream Chat Compose SDK to the project's dependencies. You'll also add a dependency on material-icons-extended, as you'll use an icon provided there for customization in later steps.

Open up the app module's build.gradle file and add the following two dependencies:

Next, make sure your project uses the correct Compose Compiler version on the build.gradle file:

You're now ready to use our SDK to build your first screen - the Channels Screen!

Stream provides a low-level client, an offline support library, and convenient Jetpack Compose UI components to help you easily integrate messaging in your app. In this section, you'll be using the components to quickly display a channel list.

Open MainActivity and replace the file's contents with the following code:

Let's have a quick look at the source code shown above:

1. You create a StreamOfflinePluginFactory to provide offline support. The OfflinePlugin class employs a new caching mechanism powered by side-effects we applied to ChatClient functions.
2. You create a connection to Stream by initializing the ChatClient using an API key. This key points to a tutorial environment, but you can sign up for a free Chat trial to get your own later. Next, we add the offlinePluginFactory to the ChatClient with withPlugin method for providing offline storage capabilities. For a production app, we recommend initializing this ChatClient in your Application class.
3. You create a User instance and pass it to the ChatClient's connectUser method, along with a pre-generated user token, in order to authenticate the user. In a real-world application, your authentication backend would generate such a token at login / signup and hand it over to the mobile app. For more information, see the Tokens & Authentication page.
4. You call the ChannelScreen composable function to render the entire ChannelScreen, and wrap it in our theme which provides styling options. You also pass in the app name as the screen's title, and an onBackPressed listener.

Now that you can display channels, let's open up one of them and start chatting!

To start chatting, you need to build another screen - the Messages Screen.

Create a new Empty Activity (New -> Activity -> Empty Compose Activity) and name it MessagesActivity.

After creating the Activity, add the following attribute to the MessagesActivity entry in your manifest:

This will make sure the Activity adjusts properly when you focus the input field.

Also, make sure to check that your Kotlin version is still 1.7.10:

Arctic Fox

Bumblebee and up

Android Studio can sometimes update the version when adding new Activities to the project and this can cause build time issues.

Next, replace the code in MessagesActivity with the following:

Let's review what's going on in this snippet:

1. You load the channelId from the Intent extras. If there is no channel ID, you can't show messages, so you finish the Activity and return. Otherwise, you can proceed to render the UI.
2. Similar to the ChannelsScreen, the MessagesScreen component sets up everything for you to show a list of messages and build a Chat experience. Note how this screen's composable should also wrapped in ChatTheme.
3. Set up a helper function to build an Intent for this Activity, that populates the arguments with the channel ID.

The MessagesScreen component is the second screen component in the SDK, out of the box it provides you with the following features:

• Header: Displays a back button, the name of the channel or thread and a channel avatar.
• Messages: Shows a paginated list of messages if the data is available, otherwise displays the correct empty or loading state. Sets up action handlers and displays a button for quick scroll to bottom action.
• Message composer: Handles message input, attachments and message actions like editing, replying and more.
• Attachment picker: Allows the user to select images, files and media capture.
• Message options: Shown when the user selects the message by long tapping. Allows the user to react to messages and perform different actions such as deleting, editing, replying, starting a thread and more.
• Reactions menu: Shown when the user taps on a reaction to a message. Displays all of the reactions left on the message along with the option to add or change yours.

You can explore all of these components individually, combine them to your requirements, and explore the Compose UI Components documentation to see how they behave and how you can customize them.

Congrats on getting your chat experience up and running! Stream Chat provides you with all the features you need to build an engaging messaging experience:

1. Offline support: send messages, edit messages and send reactions while offline
2. Reactions: long-press on a message to add a reaction
3. Attachments: use the paperclip button in MessageComposer to attach images and files
4. Edit message: long-press on your message for message options, including editing
5. Threads: start message threads to reply to any message
6. Replies: quote and reply to a message

You should also notice that the chat loads very quickly. Like - super fast! Stream’s API is powered by Go, RocksDB and Raft. The API tends to respond in less than 10ms and powers activity feeds and chat for over a billion end users.

Some features are hard to see in action with just one user online. You can open the same channel on the web and try user-to-user interactions like reactions and threads.

You now have a fully functional mobile chat interface. Not bad for a couple minutes of work! Maybe you'd like to change things up a bit though? No problem! Here are a few ways you can customize your Chat app experience:

1. Change the default theming and styling options in ChatTheme, such as shapes, typography or colors.
2. Combine our bound and stateless components with your own UI to create a custom screen.
3. Use our components and customize their content.
4. Build your custom UI components and connect them to the state exposed by our ViewModels.
5. Use the low-level client to build custom behavior, based on the available state.

Let's combine the first three approaches to customize the Messages screen. The remaining two options are great if you want to build complex features in your Chat app, but we'll skip those for now.

Changing MessagesScreen Theming

To change the theming of all the components wrapped by ChatTheme, all you have to do is override its default parameters. Let's do that, with the shapes parameter. Change the setContent() code in MessagesActivity.kt to the following:

This will require the following new imports at the top of the file:

With this small change, you can override the default shapes used in our Compose UI Components.

Combining Components

The next step of customization is combining our bound and stateless components instead of using the screen components. This gives you more control over which components you use and render and what the behavior is when tapping on items, selecting messages and more.

First, start off by building the required ViewModels for the messaging experience, at the top of the MessagesActivity class:

This requires the following new imports:

The next step is to build custom Messages screen UI. Replace the setContent() call with the following:

Now, instead of showing the MessagesScreen, you'll show your custom UI when opening a Channel. Time to add the MyCustomUi() function:

Here's a list of the new imports to add:

There is a lot going on here, so let's review the steps in the code:

Customize Component Content

Finally, let's build a customized MessageComposer. You'll use the MessageComposer, but you'll change its internal content by overriding the integrations and input composable function parameters.

Let's replace the MessageComposer() call in MyCustomUi() with a new MyCustomComposer() function:

This change will replace the default composer with your custom one.

Now create the MyCustomComposer() function with the following code:

Here are the new imports required:

Again, there's a few things going on here:

That didn't take a lot of work, but you've managed to customize the Messages screen in three different ways!

You've now built a messaging app using Stream's Compose Chat SDK.

As the next step of exploring the SDK, take a look at Compose UI Components documentation. This showcases all of our available components in detail, and explains many of the design principles and customization options of the Compose SDK.

Our Compose UI Components are still in beta, and we want to hear your feedback on using them! You can reach us easily on Twitter and on GitHub.

To use the Stream SDK in your app, you should get your own account and API key. You can get these by signing up for a free Chat trial. If you're building a hobby project or working for a small company, you might also be eligible for a Maker Account, which lets you use the Stream Chat API for free indefinitely.