Zoom Breakout Rooms (Beta)

🚧

Feature is in beta

Although this feature is public, we are also still working on polishing parts of this feature (workarounds outlined below). You can assume the examples below will work and the API's will updated with backwards-compatibility in mind

Overview

When using Zoom breakout rooms, the Recall.ai bot operates much like a human participant. That is, a single bot instance can only monitor one breakout room at a time. To record every breakout room concurrently, you will need to deploy one bot per room.

You can control how Recall.ai bots behave in breakout rooms:

• accept any invite (the default)
• join a specific room
• stay in the main meeting room.

How It Works

No special setup or configuration is required to use Zoom breakout rooms. Use the Zoom breakout rooms invite link generated by Zoom and the bot will be able to join and start recording automatically

• Inviting the Bot: Simply have the host invite the Recall.ai bot to a breakout room. Once invited, the bot will automatically join that room and begin capturing the meeting data, including recordings, transcripts, and metadata.
• One Bot per Room: Since a human cannot be present in multiple breakout rooms simultaneously, each Recall.ai bot instance is limited to a single breakout room. To monitor multiple breakout rooms concurrently, deploy a separate bot for each room.
• When did the Bot join the room? When a Bot leaves a room and joins another (main session or breakout room), from the bots perspective all participants will leave and participants that are in the new room will join. This is seen in participant metadata as everyone leaving and participants in the new room joining.

Configuring Breakout Room Behavior

Default: auto_accept_all_invites

By default, a Recall.ai bot accepts all invites to breakout rooms. As the meeting host, you may assign the bot to any of the breakout rooms.

In the following request to Create Bot, breakout_room.mode: "auto_accept_all_invites" is the default and, therefore, optional.

{
  "meeting_url": "https://zoom.us/j/...",
  "breakout_room": {
    "mode": "auto_accept_all_invites"
  }
}

A Recall.ai bot emits a breakout_room_entered webhook when joining a breakout room and a breakout_room_left webhook when leaving a breakout room. The webhook payload returns information about the breakout room ID and the room name.

📘

Breakout Room IDs are normalized by Recall and do not represent Zoom's internal breakout room IDs.

{
  "event": "bot.status_change",
  "data": {
    "bot_id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
    "status": {
      "code": "breakout_room_entered",
      "created_at": "2025-10-15T07:14:27.050380+00:00",
      "message": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "sub_code": null
    }
  }
}

{
  "event": "bot.status_change",
  "data": {
    "bot_id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
    "status": {
      "code": "breakout_room_left",
      "created_at": "2025-10-15T07:14:27.050380+00:00",
      "message": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "sub_code": null
    }
  }
}

The coordinator: join_main_room

Use "mode": "join_main_room" in the "breakout_room" payload to Create Bot to dispatch a Recall.ai bot that stays in the meeting room and rejects all invites to join breakout rooms.

{
  "meeting_url": "https://zoom.us/j/...",
  "breakout_room": {
    "mode": "join_main_room"
  }
}

📘

A "join_main_room" bot can act as the coordinator for dispatching other bots to breakout rooms. It can receive "breakout_room_{opened,closed}" webhooks.

A "join_main_room" bot may be used in two ways:

1. Record the meeting happening in the main room.
2. Observe creation/closure of breakout rooms, deciding whether to dispatch additional bots.

When "Let participants choose room" is enabled (see below), a "join_main_room" bot emits "breakout_room_{opened,closed}" webhooks in the format shown below. You can use the returned data.data.breakout_room.id to join the specific breakout room

{
  "event": "bot.status_change",
  "data": {
    "bot_id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
    "status": {
      "code": "breakout_room_opened",
      "created_at": "2025-10-15T07:14:27.050380+00:00",
      "message": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "sub_code": null
    }
  }
}

{
  "event": "bot.status_change",
  "data": {
    "bot_id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
    "status": {
      "code": "breakout_room_closed",
      "created_at": "2025-10-15T07:14:27.050380+00:00",
      "message": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "sub_code": null
    }
  }
}

🚧

A "join_main_room" bot will only receive "breakout_room_{opened,closed}" webhooks if participants can choose breakout rooms to join. The following screenshot illustrates this setting.

Join a specific breakout room

Upon receipt of a breakout_room_opened, you may choose to dispatch a Recall.ai bot to a specific breakout room. Use the breakout room ID returned in the webhook to Create a Bot that joins that specific breakout room.

The following example payload demonstrates how to send a bot that joins the specific room_id:

{
  "meeting_url": "https://zoom.us/j/...",
  "breakout_room": {
    "mode": "join_specific_room",
		"room_id": "f82e1db1-f41b-466e-bdfa-38343436d434"
  }
}

Webhooks

📘

To preserve backwards compatibility, workspaces created before October 13th, 2025 don't currently receive breakout_room_entered / breakout_room_left webhooks. Please reach out to our support team at [email protected] to enable these for your account.

Limitations

• Single Room Focus: Each Recall.ai bot can only join and record one breakout room at a time, mirroring the experience of a human participant. Therefore, simultaneous recordings of multiple rooms require multiple bot instances.

• Participant Tracking:

  Participants are tracked uniquely across breakout rooms for Recall.ai workspaces created after February 24, 2025. If your workspace was created before this date, you may see duplicate participant entries for the same attendee when the bot enters breakout rooms. Please reach out to our support team at [email protected] to update your configuration. This switch ensures accurate participant tracking and an optimal breakout room experience.

Automating Bot Deployment

For teams that require automation in managing breakout rooms, a common solution is to pre-assign meeting participants to breakout rooms. This method allows you to automatically assign a specific bot (by email) to its designated breakout room.

For more details on pre-assigning breakout room participants, please refer to Zoom’s support documentation .

Best Practices

• Planning Ahead: Determine the number of breakout rooms and the corresponding number of bots required before the meeting begins. This ensures that every room is covered and no meeting data is missed.
• Consistent Naming Conventions: Use a clear naming convention for your bots (e.g., "BreakoutBot-1", "BreakoutBot-2", etc.) to easily identify which bot is assigned to which breakout room.

For further questions or support, please contact the Recall.ai team or visit our documentation portal.