Zoom Breakout Rooms

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.

When breakout_room.mode is the default value of auto_accept_all_invites, it will automatically return to the main room once the breakout room has closed.

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.

{
  "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 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"
    }
  }
}

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.

Set room_id to the Recall breakout-room ID returned in bot.breakout_room_opened (Recall room IDs are different from Zoom’s internal room IDs; do not substitute a Zoom room ID or room name).

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"
  }
}

When breakout_room.mode is set to join_specific_room:

• When the configured room closes, the bot ends its call with the call_ended status. It does not return to the main meeting.
• The bot only accepts invitations or move requests for the configured room_id. Host and co-host requests to join a different breakout room are ignored, even before the bot has entered its configured room.
  • If your application needs the host or co-host to move a bot between breakout rooms, create the bot with breakout_room.mode set to auto_accept_all_invites instead.

Webhooks

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?

These webhooks require a coordinator bot configured with breakout_room.mode: "join_main_room" and Zoom’s “Let participants choose room” setting enabled. Other bot modes do not emit these events.

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?

Before sending a join_specific_room bot that the host will not assign, enable Let participants choose room in Zoom.

If the requested room is missing from the room list Zoom sends to that bot, the bot leaves with breakout_room_not_open. This can happen even if the main bot already generated an opened webhook for that room.

Can bots join breakout rooms when “Let participants choose room” is disabled?

Yes, a bot configured with auto_accept_all_invites can accept room assignments or invitations delivered by Zoom. This mode does not discover rooms or distribute bots across them; Zoom or the host must assign each bot.