Breakout rooms

Split a meeting into smaller private rooms, move people between them, and bring everyone back.

A breakout is a room of its own inside a meeting. The host — or your server — splits the people who are present into groups, each group talks privately, and everyone comes back to the main room when the session ends. The main room stays open, so hosts can keep talking to anyone who stayed behind.

Start breakout rooms

// Deal everyone in the meeting out at random, for ten minutes.
const session = await deewan.breakouts.start(roomId, {
  rooms: 4,                 // or names: ["Red", "Blue", "Green", "Gold"]
  assign: "auto",           // "auto" | "manual" | "none" (people choose)
  duration_seconds: 600,    // closes by itself; omit to run until ended
  auto_join: true,          // move people without asking
  allow_return: true,       // let people go back to the main room alone
});

// Or place people yourself.
await deewan.breakouts.start(roomId, {
  rooms: ["Design", "Build"],
  assign: "manual",
  placements: [
    { participant: "user_2fK9…", room: 0 },
    { participant: "api_Xk3mQp9Lr2", room: 1 },
  ],
});

curl

curl https://deewan.io/api/v1/rooms/$ROOM_ID/breakouts \
  -H "Authorization: Bearer $DEEWAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rooms":3,"assign":"auto","duration_seconds":600}'

Move people, announce, end

// Who is where right now
const { active } = await deewan.breakouts.get(roomId);
console.log(active?.rooms.map((r) => [r.name, r.members.length]), active?.unassigned);

// Move one person, or send them home with null. canReturn: may they go back alone?
await deewan.breakouts.move(roomId, "api_Xk3mQp9Lr2", active!.rooms[1].id, { canReturn: false });
await deewan.breakouts.move(roomId, "api_Xk3mQp9Lr2", null);

// Change the rooms while the session runs
await deewan.breakouts.addRoom(roomId, "Overflow");
await deewan.breakouts.renameRoom(roomId, active!.rooms[0].id, "Design review");
await deewan.breakouts.removeRoom(roomId, active!.rooms[1].id); // its people go home

// A banner in every room
await deewan.breakouts.announce(roomId, "Five minutes left.");

// Bring everyone back — with a 60-second countdown
await deewan.breakouts.end(roomId, { warn: true });

Who is a participant?

Signed-in people are identified by their account id; people who joined with a join link by the external_id you gave when you created it (a stable id derived from it, shown in the participants list); guests by an id Deewan assigns. You can pass either that id or the connection identity from GET /rooms/{room_id}/participants.

Privacy and security

Every breakout has its own end-to-end encryption key, handed out only with a pass into that room. A person who was not placed in a room can neither join it nor decrypt it.
Placement is decided on our servers. A browser cannot move itself: it can only ask for a pass, and the answer comes from the plan.
With allow_return: false, people cannot leave their room until the host ends the session.
Announcements are short banners and are not end-to-end encrypted — never put anything private in one.
Recording, captions and attendance run in the main room only.

Events

Subscribe to breakout.started and breakout.ended to keep your own records — for example, to log which group a student was in. The payload lists the rooms and how many people each held.