# 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](https://getstream.io/chat/docs/unity/state-recovery/): 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

```csharp label="Unity"
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](https://getstream.io/chat/docs/unity/tokens-and-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.

```csharp label="Unity"
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.

<Admonition type="warning">

If you upgrade from an older SDK that kept the connection open in the background, this default is a behavior change. Set `DisconnectOnApplicationPause` to `false` if you want the old behavior.

</Admonition>

## 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:

```csharp label="Unity"
// 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.

```csharp label="Unity"
// 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](https://getstream.io/chat/docs/unity/state-recovery/).

## Pause vs logout

|                | Pause                                            | Logout                        |
| -------------- | ------------------------------------------------ | ----------------------------- |
| API            | `PauseConnectionAsync` / `ResumeConnectionAsync` | `DisconnectUserAsync`         |
| User appears   | Offline until resume                             | Offline                       |
| Local state    | Kept                                             | Cleared                       |
| Next connect   | Resume, then restore missed state                | `ConnectUserAsync`, new login |
| Auto-reconnect | Stopped until resume                             | Stopped                       |

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](https://getstream.io/chat/docs/unity/client-configuration/) for every `IStreamClientConfig` property
- [State recovery](https://getstream.io/chat/docs/unity/state-recovery/) for what happens after resume
- [Initialization & Users](https://getstream.io/chat/docs/unity/init-and-users/) for connect and disconnect
- [Events](https://getstream.io/chat/docs/unity/event-object/) for `Connected`, `Disconnected`, `ConnectionStateChanged`, and `StateRecovered`


---

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

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