Business Productivity

Building Breakout Room Experiences with the Amazon Chime SDK React Component Library

Over the past year, the Amazon Chime SDK has been helpful for customers that find themselves needing to move group programs that were originally done in-person to a virtual setting. Interactive group programs can take a number of forms across different industries. For example, healthcare customers want to help behavioral health professionals facilitate group therapy sessions, educational institutions want to help instructors use peer learning techniques in their online classrooms, and event organizers want to help speakers lead workshop-format sessions at virtual industry conferences and trade shows.

All of these applications need to support a workflow where: (1) a large group of attendees join an online meeting; (2) at some point during the meeting, all or some attendees splinter off to form two or more smaller groups; and finally, (3) all attendees reconvene in the larger group meeting. We generalize these use cases with the label “breakout rooms.”

Developers can add breakout room experiences to their application built with the Amazon Chime SDK by starting with SDK primitives and layering call control elements to support the desired experience.

The Amazon Chime SDK React Component Library includes reusable and extensible components based on the React framework and is designed to give you a head start on integrating common collaboration features into your application. In this blog, we will walk you through an application built on the Amazon Chime SDK React Component Library that extends existing components to provide a simple breakout room experience. The resulting application will:

  • manage a main room (an Amazon Chime SDK meeting)
  • manage many breakout rooms that are logically connected to the main room
  • provide meeting rosters for main and breakout rooms
  • allow meeting attendees to join breakouts room from the main room, and the main room from a breakout room

Solution Overview

The following sections walk through key steps to extend the Amazon Chime React Component Library to support breakout rooms. In a production application, you would want to integrate your application’s identity model to control access to main meetings and breakout rooms. With your application’s user model integrated, you could also add other role-based features that are beyond the scope of this demo. For example: Your application could require that users have a ‘facilitator’ role to create breakout rooms, facilitators could assign ‘attendees’ to individual breakout rooms (rather than giving everyone the option to join any available breakout room), and so on.

The code shown in this blog can be found in Amazon Chime SDK Meetings with Breakout Rooms on GitHub.

Note: Deploying this demo and receiving traffic from the demo created in this post can incur AWS charges.


  • You have a basic to intermediate understanding of AWS Lambda, Amazon Chime SDK, and React.
  • aws-cdk installed and bootstrapped
  • npm installed

Key Steps

  1. Extend Amazon Chime React Component Library UI components to create a breakout room experience
  2. Add additional Lambdas to the Amazon Chime SDK React demo app to control breakout room lifecycle
  3. Integrate back end and front end components
  4. Deploy
  5. Cleanup

Breakout Room Experience

You will need to create an experience for attendees of a meeting to create breakout rooms, view available breakout rooms, and move between breakout rooms and the main room. Starting with the Amazon Chime SDK React demo app, we will first add a button to create a new breakout room.

  1. In the MeetingControls container, a new button is added:
    create breakout room button
  2. Clicking this button opens the BreakoutModal in the BreakoutControls container:
    create breakout room modal
  3. Once the additional breakout room meeting is created, it will be listed for all attendees of the main meeting in a new Navigation container option that opens the BreakoutRoster. When someone clicks on a breakout room listed in this container, they join that breakout room meeting.breakout rooms list

Control Plane for Breakout Room Management

Before completing the rest of the steps to make this feature work, we will show you how to modify the Amazon Chime SDK React demo app to allow for hosting on Amazon Simple Storage Service (Amazon S3) through Amazon CloudFront. When adding a feature like breakout rooms, you need to make the following changes to the components in the react demo app:

Infrastructure Diagram-Breakout Rooms

  • Create two Lambda functions and associated Amazon API Gateway resources are created to support the additional API calls required to create breakout rooms and join users to them.
  • Add new functions to the Utils Layer associated with the Lambda functions.
  • Use additional attributes in the Amazon DynamoDB table for the meeting to track the parent meeting of each breakout room meeting and add a new Global Secondary Index to the table.
  • Add additional containers and API functions to the Amazon Chime SDK React demo app.


To complete the addition of the new features breakout room feature, you need to link the front end and back end resources together. To add the ability to create new Amazon Chime SDK meetings for breakout rooms, several resources are required. Breakout rooms are just one example of how to build an additions and how the front and back end work together to implement a complete feature. Other features can be customized and expanded to build a complete feature set.Infrastructure Diagram-API Call Flow

Code in the front end Amazon Chime SDK React demo app in the BreakoutModal file calls the createBreakOutRooms function when clicked:


This snippet shows a function that loops through meetingCount based on the number of breakout meetings requested in breakoutOutCount. For each loop, this function calls the createMeeting function in the utils\api.ts with three arguments:

  1. Parent Meeting ID
  2. Breakout Room Meeting ID
  3. Region
const createBreakOutRooms = async (e: React.FormEvent) => {

    const meetingCount = Number(breakOutCount.trim());

    for (let i=1; i<=meetingCount; i++)
        const roomIndex = i+appCurrentBreakoutIndex;
        await createMeeting(meetingId, `breakout-${meetingId}-${roomIndex}`, region)
      catch (error) {

    const currentBreakoutRooms = await getBreakouts(meetingId);

This snippet below from the api.ts file makes an API call through an API Gateway to a Lambda function to create the Amazon Chime SDK meetings for breakout rooms. It passes to the API Gateway via the URL the arguments that were originally sent from the createBreakOutRooms function. This function requires a response from the API Gateway and Lambda that contains the new meeting information.

 export async function createMeeting(
  meetingId: string,
  breakoutId: string,
  region: string
): Promise<MeetingResponse> {
  const response = await fetch(
      method: 'POST'
  const data = await response.json();

  if (data.error) {
    throw new Error(`Server error: ${data.error}`);

  return data;

In the following code snippet, the API Gateway is created via the AWS Cloud Development Kit (AWS CDK) (but could be created via the AWS Console as well). It is configured to support the POST method and send the request to the associated Lambda.

       const api = new apigateway.RestApi(this, 'meetingApi', {
            restApiName: 'Meeting BackEnd',
            endpointConfiguration: {
              types: [ apigateway.EndpointType.REGIONAL ]
        const create = api.root.addResource('create');
        const createIntegration = new apigateway.LambdaIntegration(createLambda);
        create.addMethod('POST', createIntegration);

In the snippet below from the createMeeting Lambda, the function has taken three arguments (Parent Meeting ID, Breakout Meeting ID, Region) from the Amazon Chime SDK React demo app through the API Gateway and makes a call to the Amazon Chime SDK (chime.createMeeting) to create a new meeting. It then returns the newly created meeting information to the API Gateway which returns it to the Amazon Chime SDK React demo app. This Lambda function also uses functions in the Utils Lambda Layer to query (utils.getMeeting) and store information (utils.putBreakoutMeeting) in the Meetings DynamoDB.

    let meetingInfo = await utils.getMeeting(breakout);
    if (!meetingInfo) {
      const request = {
        ClientRequestToken: utils.uuid(),
        MediaRegion: region
      };'Creating new meeting: ' + JSON.stringify(request));
      meetingInfo = await chime.createMeeting(request).promise();
      await utils.putBreakoutMeeting(meeting, breakout, meetingInfo);


This demo can be deployed via the AWS CDK so you can see how this works in your own AWS Account.

  1. Start by configuring the aws-cdk with: account credentials and AWS CDK account environment variables: export CDK_DEFAULT_ACCOUNT=<ACCOUNTID>
  2. Download the demo repo from GitHub
  3. Deploy the AWS CDK using the included script:
    chmod +x

    This script will complete a series of actions that includes building the AWS CDK deployment and the Amazon Chime SDK React demo app. The AWS CDK consists of two Stacks that are deployed sequentially so that the API Gateway URL that is created in the back end stack can be passed to and used in the front end.

  4. The console output from the AWS CDK deploy script will include the URL for the app running in your AWS account. Open the URL in your browser and type a create new meeting to try it out.


To remove deployed resources:

cdk destroy —all

S3 buckets may not be automatically removed and should be checked.


This blog is a guide for developers describing how to build breakout room experiences with the Amazon Chime SDK and React Component Library. You can find the demo application described in this blog on GitHub. To get learn more about adding audio, video, and screen sharing to your own applications with Amazon Chime SDK, read our developer guide or find the Amazon Chime SDK React Component Library on GitHub.