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

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

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.

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.

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.

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.

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 for pause, resume, and logout
• State recovery for StateRecoveryStrategy and StateRecovered
• Initialization & Users for connect and disconnect