Unity Client Overview


This section will cover in-depth working with StreamChatClient - the main client to interact with Stream Chat API.

Plugin Structure


Stream Chat SDK package consists of multiple modules, among which you'll find a Sample Project and Code Samples.

Stream Chat Unity SDK after importing to Unity


  1. Config* - Sample config asset

  2. Core - The main logic of the Stream Chat SDK

  3. EditorTools*

  4. Libs - libraries, dependencies

  5. SampleProject* - Example UGUI project

  6. Samples* - Code samples

  7. Tests* - unit & integration tests

* - These folders are optional and can be safely removed. Note that they will not contribute to your application build size as they're wrapped in Unity's Assembly Definition and target only the Editor hence they'll be excluded from the build. The only required modules are Core and Libs

Client Lifecycle


There are 4 stages of the StreamChatClient that happen throughout your application's lifecycle:

  1. Initialize - Instantiate and configure the client

  2. Connect - Connect with the Stream server

  3. Update - Update the client per frame

  4. Destroy - Dispose of the client when you're done using it

We'll go through each stage in more detail below.

1. Initialize


In order to create an instance of StreamChatClient you can use the static StreamChatClient.CreateDefaultClient factory method as shown in the example below:

This will instantiate the client using the default dependencies.

Note that instantiated client is not yet connected to the Stream server.

Auth Credentials


You need to pass valid credentials in order to connect with the Stream server.

param name



You can get your API KEY from the Dashboard


- In production mode - User ID should be provided by your backend solution

- In development mode - You can enable Developer Tokens


- In production mode - User Token should be provided by your backend solution

- In development mode - You can enable Developer Tokens

Optional Configuration


When creating the client you can pass an optional StreamClientConfig parameter that allows you to set a desired logging level of the client as shown below:

The LogLevel field supports the following options:

  • StreamLogLevel.All - All logs will be emitted. Recommended for development or production mode.

  • StreamLogLevel.FailureOnly - Only Errors and Exception. Recommended for production mode.

  • StreamLogLevel.Debug - Additional logs will be emitted. Useful when debugging the StreamChatClient or internal WebSocket connection.

  • StreamLogLevel.Disabled - Logging is entirely disabled. This option is not recommended.

2. Connect


After your client is instantiated and configured you can now establish a connection with the Stream server by calling the streamChatClient.Connect()method.

This is deliberately separated from the initialization step as depending on your scenario, you may wish to defer connection with the server until the user opens a chat window.

3. Update


Once the client is connected it needs to be updated every frame by calling streamChatClient.Update(Time.deltaTime). There are a few things that StreamChatClient takes care of when being updated:

  1. Monitor connection health - Detect broken connection as soon as possible

  2. Retry the connection if it gets lost. The interval is based on the retry strategy configuration which you can control via StreamChatClient.SetReconnectStrategySettings method

  3. Exchange messages between the WebSocket buffers

Calling streamChatClient.Update per frame is necessary for the client to work.

4. Destroy


After you're done using the client (e.g. closing your application) you should call the streamChatClient.Dispose() method on the client instance to disconnect and clear resources.

Complete Example


A common pattern is to wrap the StreamChatClient instance in a MonoBehaviour, here's a complete example of how to instantiate, connect, update and destroy the client:

The Awake(), Update() and OnDestroy() are all Unity's special methods that are automatically called by the Unity Engine on every script that inherits from MonoBehaviour and is attached to an active GameObject in a scene.



The internal WebSocket communication is being handled on the background threads and exchanged with the main thread only via thread-safe buffers, which makes the client perform very efficiently.

Working with the API


Working with the API is achieved via 4 API submodules accessible as properties in the StreamChatClient instance:

  • StreamChatClient.ChannelApi - Channel endpoints e.g. Create, Query, Update, Delete

  • StreamChatClient.MessageApi - Message endpoints e.g. Send, Update, Delete, Add reaction, Upload file

  • StreamChatClient.ModerationApi - Moderation endpoints e.g. Mute, Ban, ShadowBan, Flag

  • StreamChatClient.UserApi - User endpoints e.g. Query, Create, Update

Async/Await pattern


StreamChatClient utilizes .NET's modern approach to asynchronous programming using the Task async/await model syntax meaning that every call to the API is wrapped in Task as shown in the example below:

Run Task as Callback


If you wish to use the client with a classical callback pattern, you can achieve this by using the AsCallback helper method as shown in the example below.

However, we recommend using the async/await pattern as it strongly simplifies the code logic.

Error Handling


The StreamChatClient client may throw a StreamApiException in case a request failed on the server, or another type of Exception if it failed in the Unity client.

In the simplest approach you may want to just log the Exception caught in a try/catch block as shown in the example below:

The StreamApiException contains detailed information about what exactly went wrong with your request.

StreamApiException properties:

Property name



Response HTTP status code


API error code. More info here


Message describing an error


URL with additional information


Additional error info

This allows you to apply a dedicated recovery strategy depending on the exact type of the problem.

Example below shows how you can achieve this:

Run Client without Unity Engine


It is possible to run the StreamChatClient within .NET/C# application without the Unity Engine. The Core module of the SDK has no dependencies on the Unity Engine. Only a few libraries in the Libs module use Unity Engine API but these can be easily replaced. Consider this Github repository as an example of how to use Stream Chat Unity SDK in a .NET Console Application.