Flutter Introduction

LAST EDIT Jul 19 2024

The Flutter SDK enables you to build any type of chat or messaging experience for Android, iOS, Web and Desktop.

It consists of 4 packages:

  • stream_chat: A pure Dart package that can be used on any Dart project. It provides a low-level client to access the Stream Chat service.

  • stream_chat_flutter_core: Provides business logic to fetch common things required for integrating Stream Chat into your application. The core package allows more customization and hence provides business logic but no UI components.

  • stream_chat_flutter: This library includes both a low-level chat SDK and a set of reusable and customisable UI components. The full documentation for this package is available here.

  • stream_chat_persistence: Provides a persistence client for fetching and saving chat data locally.

We recommend building prototypes using the full UI package since it contains UI widgets already integrated with Stream's API. stream_chat_flutter is the fastest way to get up and running using Stream chat in your app.

If you're building a very custom UI and would prefer a more lean package, our core package will be suited to this use case. Core allows you to build custom, expressive UIs while retaining the benefits of our full Flutter SDK. APIs for accessing and controlling users, sending messages, etc are seamlessly integrated into this package and accessible via providers and builders.

Before reading the docs, consider trying our online API tour, it is a nice way to learn how the API works. It's in-browser so Javascript-based but the ideas are pretty much the same as Dart.

Getting started


This guide will quickly help you get up to speed on Stream’s Chat API. The API is flexible and allows you to build any type of chat or messaging application.

Add one of the 3 packages to your app dependencies, to do that just open pubspec.yaml and add it inside the dependencies section.

You're currently not logged in. Create an account to automatically add your API key and secret to these code examples.

Chat client


The user token is typically provided by your backend when you login or register in the app. If authentication is disabled for your app you can also use a client.devToken(userId) to generate an insecure token for development. You should never launch into production with authentication disabled.

For more complex token generation and expiration examples have a look at the token provider documentation.



Let’s continue by watching your first channel. A channel contains messages and a list of members who are permanently associated with the channel and a list of watchers currently watching the channel. The example below shows how to set up a channel:

The first two arguments are the Channel Type and the Channel ID (messaging and flutterdevs in this case). The Channel ID is optional; if you leave it out, the ID is determined based on the list of members. The channel type controls the settings we’re using for this channel.

There are 5 default types of channels:

  • livestream

  • messaging

  • team

  • gaming

  • commerce

These five options above provide you with the most suitable defaults for those use cases. You can also define custom channel types if the 5 defaults don’t work for your use-case.

The third argument is an object containing the channel data. You can add as many custom fields as you would like as long as the total size of the object is less than 5KB.



Now that we have the channel set up, let's send our first chat message:

Similar to users and channels, the sendMessage method allows you to add custom fields. When you send a message to a channel, Stream Chat automatically broadcasts to all the people that are watching this channel and updates in real-time.

Querying Channels


The client.queryChannels method enables you to retrieve a list of channels. You can specify a filter and sort order. The client keeps the channels list updates as new messages, reactions and new channels arrive.

To learn more about which fields you can query and sort on have a look at the query channels documentation.



Now that you understand the building blocks of a fully functional chat integration, you can take a tour of the Flutter Chat tutorial to understand how to add the UI/UX directly into your app.

We also recommend to take a look at sample chat application.; a fully-fledged messaging app built using a combination of our pre-made widgets and custom Flutter widgets.

In the next sections of the documentation, we dive deeper into details on each API endpoint.