Skip to main content
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: 
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: 
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
  • use the runtime APIs documented in Room API