Zoom Breakout Rooms (Beta)

🚧

Feature is in beta

Although this feature is public, we are also still working on polishing parts of this feature. 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. A single bot instance can only monitor one breakout room at a time. To record every breakout room in a meeting concurrently, you will need to deploy one bot per room.

How It Works

No special setup or configuration is required to use Zoom breakout rooms. Use the regular Zoom meeting URL 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 bot's 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

There are three options to control how Recall.ai bots behave in breakout rooms:

1. Accept any invite (default behavior)
2. Always stay in the main meeting room
3. Join a specific room

Accept any invite (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 bot.breakout_room_entered webhook when joining a breakout room and a bot.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.breakout_room_entered",
  "data": {
    "bot": {
      "id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
      "metadata": {}
    },
    "data": {
      "breakout_room": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "updated_at": "2025-10-15T07:13:05.146920+00:00"
    }
  }
}

{
  "event": "bot.breakout_room_left",
  "data": {
    "bot": {
      "id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
      "metadata": {}
    },
    "data": {
      "breakout_room": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "updated_at": "2025-10-15T07:13:05.146920+00:00"
    }
  }
}

Always stay in the main room (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 "bot.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 "bot.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.breakout_room_opened",
  "data": {
    "bot": {
      "id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
      "metadata": {}
    },
    "data": {
      "breakout_room": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "updated_at": "2025-10-15T07:14:27.050380+00:00"
    }
  }
}

{
  "event": "bot.breakout_room_closed",
  "data": {
    "bot": {
      "id": "ef5ab1ff-16fa-490d-8e6a-eb8450efe643",
      "metadata": {}
    },
    "data": {
      "breakout_room": {
        "id": "f82e1db1-f41b-466e-bdfa-38343436d434",
        "name": "Room 5"
      },
      "updated_at": "2025-10-15T07:14:27.050380+00:00"
    }
  }
}

❗️

Important: A "join_main_room" bot will only receive "bot.breakout_room_{opened,closed}" webhooks if the breakout room join setting is set to Let participants choose room:

This is because Zoom only exposes information about what breakout rooms are available if the Let participants choose room option is enabled.

Join a specific breakout room (join_specific_room)

Upon receipt of a bot.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.

Breakout room bots will emit different types of webhooks depending on which mode they have been configured with. See the table below for information about which webhooks are associated with the different modes.

You can subscribe to these webhooks from the Recall.ai webhook dashboard.

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.

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.

FAQ

Why am I not receiving the bot.breakout_room_opened and bot.breakout_room_closed webhooks?

You will only receive bot.breakout_room_opened and bot.breakout_room_closed webhooks if you have sent a coordinator bot to the zoom meeting with the "mode": "join_main_room". Other types of bot will not receive these webhooks.

I've configured my bot to join a specific breakout room, but it's not joining. Why is this happening?

For bots to be able to join breakout rooms automatically, you must ensure that you select "Let participants choose room" when creating the breakout rooms. Otherwise, the bots will not be able to change breakout rooms on their own and will be stuck in the main room.

If you're changing any advanced breakout room settings, you should also ensure that the "Allow participants to return to the main session at any time" setting is not checked. This setting also prevents bots from moving freely into breakout rooms.

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