Amazon Chime SDK for JavaScript

Build video calling, audio calling, messaging, and screen sharing applications powered by the Amazon Chime SDK

The Amazon Chime SDK is a set of real-time communications components that developers can use to quickly add messaging, audio, video, and screen sharing capabilities to their web or mobile applications.

Developers can build on AWS's global communications infrastructure to deliver engaging experiences in their applications. For example, they can add video to a health application so patients can consult remotely with doctors on health issues, or create customized audio prompts for integration with the public telephone network.

The Amazon Chime SDK for JavaScript works by connecting to meeting session resources that you create in your AWS account. The SDK has everything you need to build custom calling and collaboration experiences in your web application, including methods to configure meeting sessions, list and select audio and video devices, start and stop screen share and screen share viewing, receive callbacks when media events such as volume changes occur, and control meeting features such as audio mute and video tile bindings.

If you are building a React application, consider using the Amazon Chime SDK React Component Library that supplies client-side state management and reusable UI components for common web interfaces used in audio and video conferencing applications. Amazon Chime also offers Amazon Chime SDK for iOS and Amazon Chime SDK for Android for native mobile application development.

The Amazon Chime SDK Project Board captures the status of community feature requests across all our repositories. The descriptions of the columns on the board are captured in this guide.

Resources

Blog posts

In addition to the below, here is a list of all blog posts about the Amazon Chime SDK.

High level

Frontend

Full stack and PSTN

Messaging

Media Pipelines

Webinars and videos

Webinar: Creating Classroom Experiences Using the Amazon Chime SDK

JavaScript SDK Guides

The following developer guides cover specific topics for a technical audience.

Migration Guides

Developer Guides

The following developer guides cover the Amazon Chime SDK more broadly.

Examples

Amazon Chime SDK Samples — Amazon Chime SDK Samples repository
Meeting Demo — A browser meeting application with a local server
Serverless Meeting Demo — A self-contained serverless meeting application
Single JS — A script to bundle the SDK into a single .js file
Transcription and Media Capture Demo - A demo to demonstrate transcription and media capture capabilities
Virtual Classroom — An online classroom built with Electron and React
Live Events — Interactive live events solution
Amazon Chime SDK Smart Video Sending Demo — Demo showcasing how to dynamically display up to 25 video tiles from a pool of up to 250 meeting attendees
Amazon Chime SDK and Amazon Connect Integration — Build a video contact center with Amazon Connect and Amazon Chime SDK
Device Integration — Using the Amazon Chime SDK for 3rd party devices
Messaging — Build chat features into your application with Amazon Chime SDK messaging
Load Testing Applications — A tool to load test audio-video communication applications

PSTN Audio Examples

PSTN Dial In — Add PSTN dial-in capabilities to your Amazon Chime SDK Meeting using SIP media application
Outbound Call Notifications — Send meeting reminders with SIP media application and get real time results back
Update In-Progress Call - Update an in-progress SIP media application call via API call

Troubleshooting and Support

Review the resources given in the README and use our client documentation for guidance on how to develop on the Chime SDK for JavaScript. Additionally, search our issues database and FAQs to see if your issue is already addressed. If not please cut us an issue using the provided templates.

The blog post Monitoring and Troubleshooting With Amazon Chime SDK Meeting Events goes into detail about how to use meeting events to troubleshoot your application by logging to Amazon CloudWatch.

If you have more questions, or require support for your business, you can reach out to AWS Customer support. You can review our support plans here.

WebRTC Resources

The Amazon Chime SDK for JavaScript uses WebRTC, the real-time communication API supported in most modern browsers. Here are some general resources on WebRTC.

Installation

Make sure you have Node.js version 18 or higher. Node 20 is recommended and supported.

To add the Amazon Chime SDK for JavaScript into an existing application, install the package directly from npm:

npm install amazon-chime-sdk-js --save

Note that the Amazon Chime SDK for JavaScript targets ES2015, which is fully compatible with all supported browsers.

Setup

Meeting session

Create a meeting session in your client application.

import {
  ConsoleLogger,
  DefaultDeviceController,
  DefaultMeetingSession,
  LogLevel,
  MeetingSessionConfiguration
} from 'amazon-chime-sdk-js';

const logger = new ConsoleLogger('MyLogger', LogLevel.INFO);
const deviceController = new DefaultDeviceController(logger);

// You need responses from server-side Chime API. See below for details.
const meetingResponse = /* The response from the CreateMeeting API action */;
const attendeeResponse = /* The response from the CreateAttendee or BatchCreateAttendee API action */;
const configuration = new MeetingSessionConfiguration(meetingResponse, attendeeResponse);

// In the usage examples below, you will use this meetingSession object.
const meetingSession = new DefaultMeetingSession(
  configuration,
  logger,
  deviceController
);

Getting responses from your server application

You can use an AWS SDK, the AWS Command Line Interface (AWS CLI), or the REST API to make API calls. In this section, you will use the AWS SDK for JavaScript in your server application, e.g. Node.js. See Amazon Chime SDK API Reference for more information.

⚠️ The server application does not require the Amazon Chime SDK for JavaScript.

const AWS = require('aws-sdk');
const { v4: uuid } = require('uuid');

// You must use "us-east-1" as the region for Chime API and set the endpoint.
const chime = new AWS.ChimeSDKMeetings({ region: 'us-east-1' });

const meetingResponse = await chime
  .createMeeting({
    ClientRequestToken: uuid(),
    MediaRegion: 'us-west-2', // Specify the region in which to create the meeting.
  })
  .promise();

const attendeeResponse = await chime
  .createAttendee({
    MeetingId: meetingResponse.Meeting.MeetingId,
    ExternalUserId: uuid(), // Link the attendee to an identity managed by your application.
  })
  .promise();

Now securely transfer the meetingResponse and attendeeResponse objects to your client application. These objects contain all the information needed for a client application using the Amazon Chime SDK for JavaScript to join the meeting.

The value of the MediaRegion parameter in the createMeeting() should ideally be set to the one of the media regions which is closest to the user creating a meeting. An implementation can be found under the topic 'Choosing the nearest media Region' in the Amazon Chime SDK Media Regions documentation.

Messaging session

Create a messaging session in your client application to receive messages from Amazon Chime SDK for Messaging.

import { ChimeSDKMessagingClient } from '@aws-sdk/client-chime-sdk-messaging';

import {
  ConsoleLogger,
  DefaultMessagingSession,
  LogLevel,
  MessagingSessionConfiguration,
} from 'amazon-chime-sdk-js';

const logger = new ConsoleLogger('SDK', LogLevel.INFO);

// You will need AWS credentials configured before calling AWS or Amazon Chime APIs.
const chime = new ChimeSDKMessagingClient({ region: 'us-east-1'});

const userArn = /* The userArn */;
const sessionId = /* The sessionId */;
const configuration = new MessagingSessionConfiguration(userArn, sessionId, undefined, chime);
const messagingSession = new DefaultMessagingSession(configuration, logger);

If you would like to enable prefetch feature when connecting to a messaging session, you can follow the code below. Prefetch feature will