> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Room Connections

> Connect your app to a MeshAgent room from React or Flutter.

Use a room connection helper when your app needs a live `RoomClient`.

This is the primitive that turns a room URL and participant token into an active room connection your UI can render on top of.

## What you need

* A room URL
* A participant token
* A way to fetch both from your backend

In production, your backend usually gets those values from MeshAgent and returns them to the client. For local or controlled development flows, the SDKs also expose static or development authorization helpers.

## React

Use `useRoomConnection` from `@meshagent/meshagent-react`:

```tsx theme={null}
import { useRoomConnection } from "@meshagent/meshagent-react";

export function RoomScreen() {
  const { client, state, error } = useRoomConnection({
    authorization: async () => {
      const resp = await fetch("/api/room-connection");
      return await resp.json(); // { url, jwt }
    },
  });

  if (state === "authorizing" || state === "connecting") {
    return <div>Connecting...</div>;
  }

  if (state === "done" || !client) {
    return <div>Connection failed: {String(error)}</div>;
  }

  return <div>Connected to {client.roomName}</div>;
}
```

`useRoomConnection` creates the `RoomClient`, starts it, and optionally enables messaging.

If your React app also needs OAuth login, pair this with `@meshagent/meshagent-react-auth` for hook-based auth flows or `@meshagent/meshagent-ts-auth` for framework-agnostic auth helpers.

## Flutter

Use `RoomConnectionScope` from `meshagent_flutter`:

```dart theme={null}
import 'package:flutter/widgets.dart';
import 'package:meshagent/meshagent.dart';
import 'package:meshagent_flutter/meshagent_flutter.dart';

class SampleWidget extends StatelessWidget {
  const SampleWidget({
    super.key,
    required this.projectId,
    required this.roomName,
    required this.url,
    required this.jwt,
  });

  final String projectId;
  final String roomName;
  final Uri url;
  final String jwt;

  @override
  Widget build(BuildContext context) {
    return RoomConnectionScope(
      authorization: staticAuthorization(
        projectId: projectId,
        roomName: roomName,
        url: url,
        jwt: jwt,
      ),
      authorizingBuilder: (context) =>
          const Center(child: CircularProgressIndicator()),
      connectingBuilder: (context, client) =>
          const Center(child: Text('Connecting...')),
      builder: (context, client) => const Text('Connection established'),
      doneBuilder: (context, error) =>
          Text('Connection ended with error: $error'),
      enableMessaging: true,
    );
  }
}
```

`RoomConnectionScope` manages authorization, connection state, reconnect behavior, and disposal for you.

## When to use which helper

* Use **React `useRoomConnection`** in web apps built around React hooks.
* Use **Flutter `RoomConnectionScope`** in Flutter apps where you want connection state to drive the widget tree.

## What to do next

Once the room is connected, you can:

* render messages and participants
* call agents or tools
* open documents with [Document Connections](./document_connection_scope)
* use the runtime APIs documented in [Room API](../room_api/overview)