{"id":10496,"library":"amazon-chime-sdk-js","title":"Amazon Chime SDK for JavaScript","description":"The Amazon Chime SDK for JavaScript, currently at version 3.30.0, provides a comprehensive set of real-time communication components for web applications. It enables developers to integrate features such as messaging, audio, video, and screen sharing, leveraging AWS's global communication infrastructure. The SDK operates by connecting to meeting session resources provisioned within an AWS account, offering a robust API for configuring sessions, managing audio/video devices, handling screen sharing, and controlling various meeting features. With a roughly monthly release cadence, the library is actively maintained and supports modern browser environments (Chrome 78+, Firefox 75+, Safari 13+). Key differentiators include its deep integration with AWS services for scalable backend provisioning and a modular design that allows for either custom UI development or integration with higher-level libraries like the Amazon Chime SDK React Component Library. It also offers native SDKs for iOS and Android, providing a consistent cross-platform development experience.","status":"active","version":"3.30.0","language":"javascript","source_language":"en","source_url":"git://github.com/aws/amazon-chime-sdk-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install amazon-chime-sdk-js","lang":"bash","label":"npm"},{"cmd":"yarn add amazon-chime-sdk-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add amazon-chime-sdk-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required on the server-side to provision Amazon Chime SDK meetings and attendees. Not a direct client-side dependency.","package":"aws-sdk","optional":false},{"reason":"Modern AWS SDK v3 client for Chime SDK Meetings, used on the server-side for provisioning. Replaces parts of 'aws-sdk'.","package":"@aws-sdk/client-chime-sdk-meetings","optional":false}],"imports":[{"note":"ESM imports are standard. CommonJS `require` is generally not recommended for modern usage with v3 and Node >=18.","wrong":"const { ConsoleLogger } = require('amazon-chime-sdk-js');","symbol":"ConsoleLogger","correct":"import { ConsoleLogger, LogLevel } from 'amazon-chime-sdk-js';"},{"note":"Most core classes are named exports, not default exports.","wrong":"import DefaultMeetingSession from 'amazon-chime-sdk-js';","symbol":"DefaultMeetingSession","correct":"import { DefaultMeetingSession } from 'amazon-chime-sdk-js';"},{"note":"Be careful not to confuse `MeetingSessionConfiguration` (for audio/video calls) with `MessagingSessionConfiguration` (for chat features).","wrong":"import { MessagingSessionConfiguration } from 'amazon-chime-sdk-js'; // for meeting config","symbol":"MeetingSessionConfiguration","correct":"import { MeetingSessionConfiguration } from 'amazon-chime-sdk-js';"},{"note":"The device controller was decoupled from the audio/video controller in v3 for improved workflow and explicit device management.","symbol":"DefaultDeviceController","correct":"import { DefaultDeviceController } from 'amazon-chime-sdk-js';"}],"quickstart":{"code":"import { \n  ConsoleLogger, \n  LogLevel, \n  DefaultDeviceController, \n  MeetingSessionConfiguration, \n  DefaultMeetingSession,\n  MeetingSessionStatus, \n  MeetingSessionStatusCode,\n  type AudioVideoFacade, \n  type MeetingSession,\n  type MeetingSessionDelegate\n} from 'amazon-chime-sdk-js';\n\n// --- Backend-provided meeting and attendee information (simulated) ---\n// In a real application, this data comes from your backend service\n// after calling Chime SDK CreateMeeting and CreateAttendee APIs.\nconst mockMeetingResponse = {\n  Meeting: {\n    MeetingId: 'mock-meeting-id',\n    MediaPlacement: {\n      AudioHostUrl: 'wss://chime.us-east-1.chime.aws/ws?X-Amz-ChannelID=...',\n      ScreenDataUrl: 'wss://chime.us-east-1.chime.aws/v2/screenshare/meetingId/...',\n      ScreenSharingUrl: 'wss://chime.us-east-1.chime.aws/v2/screenshare/meetingId/...',\n      ScreenViewingUrl: 'wss://chime.us-east-1.chime.aws/v2/screencapture/meetingId/...',\n      SignalingUrl: 'wss://signal.us-east-1.chime.aws/ws?X-Amz-ChannelID=...',\n      TurnControlUrl: 'https://global.turn.chime.aws/v1/turn?X-Amz-ChannelID=...',\n      EventIngestionUrl: 'https://events.chime.aws/v2/meetings/.../events'\n    },\n    MediaRegion: 'us-east-1'\n  }\n};\n\nconst mockAttendeeResponse = {\n  Attendee: {\n    AttendeeId: 'mock-attendee-id',\n    JoinToken: 'mock-join-token',\n    ExternalUserId: 'test-user-123'\n  }\n};\n\nasync function initializeMeetingSession() {\n  const logger = new ConsoleLogger('ChimeMeetingLogger', LogLevel.INFO);\n  const deviceController = new DefaultDeviceController(logger);\n\n  const configuration = new MeetingSessionConfiguration(\n    mockMeetingResponse,\n    mockAttendeeResponse\n  );\n\n  const meetingSession = new DefaultMeetingSession(\n    configuration,\n    logger,\n    deviceController\n  );\n\n  // Implement a delegate to receive meeting events\n  const meetingDelegate: MeetingSessionDelegate = {\n    audioVideoDidStart: () => {\n      logger.info('Audio/Video started!');\n    },\n    audioVideoDidStop: (sessionStatus: MeetingSessionStatus) => {\n      logger.warn(`Audio/Video stopped with code: ${MeetingSessionStatusCode[sessionStatus.statusCode]}`);\n    },\n    audioVideoDidStartConnecting: (reconnecting: boolean) => {\n      logger.info(reconnecting ? 'Reconnecting to meeting...' : 'Connecting to meeting...');\n    },\n    connectionDidSuggestStop: () => {\n        logger.info('Connection suggested stop. Leaving meeting...');\n        meetingSession.audioVideo.stop();\n    },\n    // ... other delegate methods as needed\n  };\n  \n  meetingSession.audioVideo.addObserver(meetingDelegate);\n\n  try {\n    // Ensure microphone and camera permissions are granted before starting\n    await navigator.mediaDevices.getUserMedia({ audio: true, video: true });\n    logger.info('Microphone and camera permissions granted.');\n\n    await meetingSession.audioVideo.start();\n    logger.info('Meeting session started successfully!');\n\n    // Example: List and select audio input devices\n    const audioInputDevices = await meetingSession.audioVideo.listAudioInputDevices();\n    if (audioInputDevices.length > 0) {\n      await meetingSession.audioVideo.chooseAudioInputDevice(audioInputDevices[0].deviceId);\n      logger.info(`Selected audio input device: ${audioInputDevices[0].label}`);\n    }\n\n    // Clean up after 30 seconds for demonstration\n    setTimeout(() => {\n      meetingSession.audioVideo.stop();\n      logger.info('Meeting session stopped after 30 seconds.');\n    }, 30000);\n\n  } catch (error) {\n    logger.error(`Error starting meeting session: ${error}`);\n  }\n}\n\ninitializeMeetingSession();","lang":"typescript","description":"This quickstart demonstrates how to initialize an Amazon Chime SDK meeting session, including setting up a logger, device controller, and handling basic audio/video events. It simulates backend responses for meeting and attendee information, which are crucial for client-side session configuration and connection. It also includes steps for requesting permissions and selecting audio input devices."},"warnings":[{"fix":"Review the v3 migration guide. Update device selection logic to use the `DefaultDeviceController` and methods like `chooseAudioInputDevice` and `startVideoInputDevice` explicitly. The `chooseVideoInputDevice` method was renamed to `startVideoInputDevice`, and `selectVideoInputDevice` was added for selection without immediate activation.","message":"Version 3.0.0 introduced significant breaking changes, primarily decoupling the device controller from the audio/video controller. This requires updates to how devices are managed and selected outside of an active meeting session.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure target browsers meet the minimum requirements (e.g., Chrome 78+, Firefox 75+, Safari 13+).","message":"Support for Safari 12 and WebRTC Plan B was deprecated and removed in version 3.0.0. This may affect older browser compatibility.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Develop or deploy a backend service (e.g., using AWS Lambda and API Gateway) that utilizes the AWS SDK (e.g., `@aws-sdk/client-chime-sdk-meetings` for JS v3) to create and manage meetings and attendees, passing the generated meeting and attendee responses to the client-side SDK.","message":"The Amazon Chime SDK for JavaScript is a client-side library and *requires* a custom backend service to provision meetings and attendees. It does not directly interact with AWS Chime API endpoints from the client.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Implement robust error handling for `audioVideoDidStop` and other delegate methods to identify `MeetingSessionStatusCode` (e.g., `AudioCallAtCapacity`, `MeetingEnded`). Monitor meeting usage on the backend using Chime SDK event notifications and AWS quotas.","message":"Meeting sessions have capacity limits (e.g., 250 attendees) and can automatically end due to inactivity or if deleted via the API. Client-side errors like 'AudioCallAtCapacity' or 'MeetingEnded' indicate these server-side conditions.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Always prompt for and verify microphone and camera permissions (`navigator.mediaDevices.getUserMedia`) before attempting to start audio/video. Provide clear UI feedback to the user if permissions are denied or fail to be acquired.","message":"Browser permissions for microphone and camera are critical. Failure to grant these can lead to `deviceLabelTriggerFailed`, `audioInputFailed`, or `videoInputFailed` events, preventing users from participating in audio/video.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For selecting a video input without immediately starting it, use `meetingSession.audioVideo.selectVideoInputDevice(device)`. To select and start video input, use `meetingSession.audioVideo.startVideoInputDevice(device)`.","cause":"The method name `chooseVideoInputDevice` was changed in version 3.0.0 of the SDK.","error":"TypeError: meetingSession.audioVideo.chooseVideoInputDevice is not a function"},{"fix":"This is a server-side limit. Ensure that the number of attendees does not exceed the maximum limit. Track attendee counts in your server application using Amazon Chime SDK event notifications to prevent exceeding capacity.","cause":"The meeting has reached its maximum attendee limit, typically 250.","error":"Meeting failed: AudioCallAtCapacity"},{"fix":"Verify that the `DeleteMeeting` API action was not called prematurely on your server application. Implement logic to handle meeting inactivity detection and inform users if a meeting is ending.","cause":"The meeting was terminated by a backend API call or automatically ended due to inactivity.","error":"Meeting failed: MeetingEnded"},{"fix":"Review your AWS IAM policy associated with the credentials used by your backend. Ensure it grants sufficient permissions for the specific Amazon Chime SDK API actions being invoked.","cause":"The IAM credentials used by your backend service lack the necessary permissions to call Amazon Chime SDK APIs (e.g., `CreateMeeting`, `CreateAttendee`).","error":"AccessDeniedException: User is not authorized to perform this operation."}],"ecosystem":"npm"}