# Client configuration

You can pass an optional `StreamClientConfig` when you create the client. Most apps can use the defaults. Change these settings when your app needs different behavior:

- What the SDK logs
- Whether the SDK disconnects when the app goes to the background
- How the SDK catches up after reconnect
- Whether a user's own sent messages appear immediately
- How many recent messages the SDK keeps in memory for each channel

```csharp label="Unity"
using StreamChat.Core;
using StreamChat.Core.Configs;

var config = new StreamClientConfig
{
    LogLevel = StreamLogLevel.Debug,
    DisconnectOnApplicationPause = true,
    StateRecoveryStrategy = StateRecoveryStrategy.ReplayEvents,
    OptimisticMessageInsert = true,
    DefaultMessageCacheWindow = null,
};
var client = StreamChatClient.CreateDefaultClient(config);
```

`CreateDefaultClient()` with no arguments uses the same defaults as a new `StreamClientConfig`.

## Options

| Property                       | Default            | Controls                                                     |
| ------------------------------ | ------------------ | ------------------------------------------------------------ |
| `LogLevel`                     | `FailureOnly`      | SDK logging                                                  |
| `DisconnectOnApplicationPause` | `true`             | Background pause and resume                                  |
| `StateRecoveryStrategy`        | `ReplayEvents`     | How the SDK catches up after reconnect                       |
| `OptimisticMessageInsert`      | `true`             | Whether sent messages appear before server confirmation      |
| `DefaultMessageCacheWindow`    | `null` (unlimited) | How many recent messages are kept in memory for each channel |

## Log level

`FailureOnly` is the production default. It logs errors and exceptions only. Use `All` while you set up or test chat. Use `Debug` when you need extra connection logs. `Disabled` turns SDK logs off; use it only if your app already records SDK errors another way.

## Disconnect on application pause

When `true` (the default), `CreateDefaultClient` closes the chat connection when the app goes to the background and opens it again when the app returns. Other users see this user as offline while the app is in the background. After resume, the SDK catches up on messages and other changes that happened while the app was away. Set this to `false` if your app must stay connected in the background.

This setting is ignored in the Unity Editor. See [Connection lifecycle](https://getstream.io/chat/docs/unity/connection-lifecycle/).

## State recovery strategy

After a reconnect, the SDK needs to catch up on the channels the user had open. `ReplayEvents` (default) sends missed messages, reactions, and other changes through the normal event handlers. `BatchStateUpdate` updates local channel state without those event handlers, then raises `StateRecovered` so you can refresh the UI. `Disabled` turns this recovery off; use it only if your app reloads channel state itself.

See [State recovery](https://getstream.io/chat/docs/unity/state-recovery/).

## Optimistic message insert

When `true` (default), a message a user sends appears in `channel.Messages` and raises `MessageReceived` immediately, before the server confirms it. When the server later sends back the same message, the SDK ignores the duplicate so the message does not appear twice.

Set this to `false` when every client, including the sender, must show messages only after the server accepts them. For example, use this for a shared feed where all users must see the same message order.

```csharp label="Unity"
var config = new StreamClientConfig
{
    OptimisticMessageInsert = false,
};
var client = StreamChatClient.CreateDefaultClient(config);
```

## Message cache window

`DefaultMessageCacheWindow` limits how many messages the SDK keeps in memory for each channel. `null` (default) means unlimited. This does not delete messages from Stream or change channel history. `LoadOlderMessagesAsync` can still load older messages when needed.

Use `MessageCacheWindow.Recommended` for high-volume channels, such as livestream chats. It keeps the newest 500 messages in memory and trims older messages as new ones arrive. Override one channel with `channel.OverrideMessageCacheWindow`, or remove the override with `channel.ClearMessageCacheWindowOverride`.

```csharp label="Unity"
var config = new StreamClientConfig
{
    DefaultMessageCacheWindow = MessageCacheWindow.Recommended,
};
var client = StreamChatClient.CreateDefaultClient(config);

channel.OverrideMessageCacheWindow(MessageCacheWindow.Recommended);
channel.ClearMessageCacheWindowOverride();
```

Calling `LoadOlderMessagesAsync` pauses trimming automatically so the page the user just loaded is not removed right away. Call `channel.ResumeMessageCacheTrimming()` when the user scrolls back to the newest messages.

## Related

- [Connection lifecycle](https://getstream.io/chat/docs/unity/connection-lifecycle/) for pause, resume, and logout
- [State recovery](https://getstream.io/chat/docs/unity/state-recovery/) for `StateRecoveryStrategy` and `StateRecovered`
- [Initialization & Users](https://getstream.io/chat/docs/unity/init-and-users/) for connect and disconnect


---

This page was last updated at 2026-09-02T15:00:32.069Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/unity/client-configuration/](https://getstream.io/chat/docs/unity/client-configuration/).