Flutter Introduction

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 builder s.

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.

dependencies:
	# client + UX
 stream_chat_flutter: ^1.0.1-beta
	# core business logic widgets
 stream_chat_flutter_core: ^1.0.1-beta
	# client only
 stream_chat: ^1.0.2-beta

Chat client

final apiKey = "{{ api_key }}";
final userToken = "{{ chat_user_token }}";

/// Create a new instance of [StreamChatClient] passing the apikey obtained from 
/// your project dashboard.
final client = StreamChatClient(
  's2dxdhpxd94g',
  logLevel: Level.INFO,
);

/// Set the current user and connect the websocket. 
/// In a production scenario, this should be done using a backend to generate
/// a user token using our server SDK.
/// Please see the following for more information:
/// https://getstream.io/chat/docs/ios_user_setup_and_tokens/
 await client.connectUser(
  User(id: 'super-band-9'),
  userToken,
 );

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.

Channels

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:

final channel = client.channel(
  'messaging',
  id: 'flutterdevs',
  extraData: {
   'name': 'Flutter devs',
  },
);

await channel.watch();

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.

Messages

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

final message = Message(
  text:
    'I told them I was pesca-pescatarian. Which is one who eats solely fish who eat other fish.',
  extraData: {
   'customField': '123',
  },
 );
 await channel.sendMessage(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.

final filter = {
 "type": "messaging",
 "members": {
  "\$in": ["john"]
 }
};

final sort = [SortOption("last_message_at", direction: SortOption.DESC)];

final channels = await client.queryChannels(
 filter: filter,
 sort: sort,
);

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

Conclusion

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.

Tokens & Authentication