Connection lifecycle

The Stream Chat Unity SDK keeps an open connection to Stream while a user is signed in. The SDK uses this connection to receive new messages, reactions, typing events, and other chat updates. You can pause the connection when the app goes to the background, resume it later, or log the user out.

Pause and logout are different:

• PauseConnectionAsync temporarily closes the connection. Other users see this user as offline. Loaded channels, messages, and related data stay in memory. The SDK does not reconnect until you call ResumeConnectionAsync. After resume, the SDK catches up on missed state: it reloads the channels the user had open and applies messages and events that happened while the connection was closed.
• DisconnectUserAsync logs the user out. Local chat state is cleared. The next ConnectUserAsync starts a new login. The SDK does not restore messages or channels from the previous session.

Pause and resume

await client.PauseConnectionAsync();
await client.ResumeConnectionAsync();

ResumeConnectionAsync does nothing if the client is already connected or connecting. For the first sign-in, use ConnectUserAsync, not resume.

If you passed an ITokenProvider to ConnectUserAsync, the SDK still uses it on resume when it needs a new token. See Tokens & Authentication.

Auto-pause on background

DisconnectOnApplicationPause defaults to true. With CreateDefaultClient, Unity's OnApplicationPause uses the same pause and resume flow: when the app goes to the background, the connection closes; when the app returns, the connection opens again and the SDK catches up on anything missed while disconnected.

using StreamChat.Core;
using StreamChat.Core.Configs;

var config = new StreamClientConfig
{
    DisconnectOnApplicationPause = false,
};
var client = StreamChatClient.CreateDefaultClient(config);

Set it to false if the user should stay connected and appear online while the app is in the background.

Editor

Auto-pause is ignored in the Unity Editor so pausing play mode or unfocusing the Game view does not close the connection. A warning is logged once. Call PauseConnectionAsync / ResumeConnectionAsync yourself if you need to test that path in the Editor.

Custom update loop

CreateDefaultClient handles the SDK update loop and Unity's OnApplicationPause for you.

If you use CreateClientWithCustomDependencies and call Update() each frame yourself, also pass application pause changes to the client:

// Only needed if you call Update() yourself instead of CreateDefaultClient().
client.OnApplicationPause(isPaused);

You can call PauseConnectionAsync / ResumeConnectionAsync instead of OnApplicationPause. After a manual pause, call ResumeConnectionAsync yourself. Auto-resume on foreground only runs after an auto-pause.

Connection state

Connected, Disconnected, and ConnectionStateChanged run on the Unity main thread, so it is safe to call Unity APIs from those handlers.

// These callbacks run on the Unity main thread.
client.Connected += localUserData => Debug.Log($"Connected as {localUserData.UserId}");
client.Disconnected += () => Debug.Log("Disconnected");
client.ConnectionStateChanged += (previous, current) =>
    Debug.Log($"{previous} -> {current}");

Possible ConnectionState values: Disconnected, Connecting, WaitToReconnect, Connected, Closing.

During recovery, WatchedChannels can be empty until the SDK starts watching those channels again. See State recovery.

Pause vs logout

Use pause when the app goes to the background, for a short break, or any case where the user should return to the same chat session. Use logout when the player signs out.

Related

• Client configuration for every IStreamClientConfig property
• State recovery for what happens after resume
• Initialization & Users for connect and disconnect
• Events for Connected, Disconnected, ConnectionStateChanged, and StateRecovered