Sendbird Chat SDK v3 for JavaScript

Common errors

• TypeError: Cannot read properties of undefined (reading 'localStorage')

  cause The Sendbird SDK v3.1.31 or earlier attempted to access `localStorage` in a non-browser environment like React Native, where it is not available.
  fix Upgrade the `sendbird` package to v3.1.32 or later to resolve the `localStorage` access issue in React Native.

• Uncaught (in promise) TypeError: Cannot read property 'finally' of undefined

  cause The Sendbird SDK v3 was used in an environment (e.g., older browser) that lacks native `Promise.finally()` support, and no polyfill was provided.
  fix Update the `sendbird` package to v3.1.24 or higher, which bundles a `Promise.finally()` polyfill, or include a separate `Promise.finally()` polyfill in your application.

• QuotaExceededError: Failed to execute 'setItem' on 'Storage': Setting the value of 'sendbird_message_collection_key' exceeded the quota.

  cause The Sendbird `MessageCollection` is attempting to store more data in `localStorage` than the browser's allocated quota allows.
  fix While v3.1.30 had stability improvements related to this, managing `localStorage` size is key. Consider reducing the number of messages cached, clearing old data, or migrating to SDK v4 which has more robust local caching strategies.

• Error: channel.sendFileMessage() failed in web worker context

  cause In Sendbird SDK v3 versions prior to v3.1.28, calling `channel.sendFileMessage()` within a Web Worker environment could lead to failures.
  fix Upgrade the `sendbird` package to v3.1.28 or later. If unable to upgrade, consider performing file message sending operations outside of Web Workers.

Warnings

• breaking Sendbird Chat SDK v3 is officially deprecated as of July 2023, with v3.1.33 being its final release in August 2023. No further updates, bug fixes, or security patches will be provided for this version. Users are strongly advised to migrate to Sendbird Chat SDK v4.
  Fix: Plan and execute migration to Sendbird Chat SDK v4. Refer to the official Sendbird documentation for migration guides and breaking changes.
• breaking Migration from Sendbird Chat SDK v3 to v4 involves significant breaking changes. The API surface, initialization patterns, and underlying architecture have evolved. Direct drop-in replacement is not possible.
  Fix: Consult the Sendbird Chat SDK v4 documentation and migration guides carefully. Prioritize testing and refactor code incrementally to adapt to the new API paradigms.
• gotcha Older versions of Sendbird SDK v3 (prior to v3.1.32) could cause `sb.connect()` to fail in React Native environments due to an unexpected attempt to access the browser's `localStorage` API, which is unavailable in React Native.
  Fix: Update the `sendbird` package to v3.1.32 or higher. If sticking with an older version, ensure a `localStorage` polyfill is provided for the React Native environment, though upgrading is strongly recommended due to deprecation.
• gotcha When `localCacheEnabled` was set to `false`, `MessageCollection` in SDK versions prior to v3.1.31 would incorrectly call `onMessagesUpdated()` with old messages upon connection or reconnection, leading to stale UI data.
  Fix: Update the `sendbird` package to v3.1.31 or higher. Review your `MessageCollection` event handlers to ensure they gracefully handle potential duplicate or out-of-order message updates if using older versions.
• gotcha Applications targeting older browsers or environments that do not natively support `Promise.finally()` (e.g., Internet Explorer 11) would encounter runtime errors if using Sendbird SDK v3 versions prior to v3.1.24, as the SDK lacked an internal polyfill.
  Fix: Update the `sendbird` package to v3.1.24 or higher, which includes a Promise.finally() polyfill. Alternatively, ensure your build toolchain or application code provides a polyfill for `Promise.finally()` if targeting legacy environments.

Install

• npm install sendbird npm
• yarn add sendbird yarn
• pnpm add sendbird pnpm

Imports

• SendBird
  wrong:

  import { SendBird } from 'sendbird'

  correct:

  import SendBird from 'sendbird'

  The primary SendBird class is a default export in v3. It also acts as a namespace for many static methods and types.
• UserMessageParams

  import type { UserMessageParams } from 'sendbird'

  Type imports are crucial for TypeScript projects, ensuring correct parameter definitions for message creation.
• GroupChannel
  wrong:

  const SendBird = require('sendbird'); const channel = new SendBird.GroupChannel();

  correct:

  import { GroupChannel } from 'sendbird'

  While `SendBird` is a default export, certain classes and interfaces are available as named exports or accessed via the `SendBird` instance/namespace. The CommonJS `require` pattern is a common anti-pattern for modern JavaScript/TypeScript projects targeting v3 or later.

Quickstart

This quickstart demonstrates initializing the Sendbird SDK, connecting a user, entering an open channel, and sending a basic user message, including handling environment variables for credentials.

import SendBird from 'sendbird';

const APP_ID = process.env.SENDBIRD_APP_ID ?? 'YOUR_SENDBIRD_APP_ID';
const USER_ID = process.env.SENDBIRD_USER_ID ?? 'testuser123';
const NICKNAME = process.env.SENDBIRD_USER_NICKNAME ?? 'Test User';

const sb = new SendBird({
  appId: APP_ID,
  modules: [new SendBird.ChannelModule(), new SendBird.MessageModule()]
});

async function initializeAndConnect() {
  try {
    console.log('Connecting to Sendbird...');
    const user = await sb.connect(USER_ID);
    console.log(`Connected as ${user.nickname} (${user.userId})`);

    // Create or get a channel
    const channelUrl = process.env.SENDBIRD_CHANNEL_URL ?? 'sendbird_open_channel_28653_373c38c116d90a78627e7f77a880949216065548';
    const channel = await sb.OpenChannel.getChannel(channelUrl);
    await channel.enter();
    console.log(`Entered channel: ${channel.name}`);

    // Send a message
    const messageText = `Hello from SDK v3! Current time: ${new Date().toLocaleTimeString()}`;
    const params = new sb.UserMessageParams();
    params.message = messageText;
    const message = await channel.sendUserMessage(params);
    console.log('Message sent:', message.message);

    // Disconnect (optional, for cleanup)
    // await sb.disconnect();
    // console.log('Disconnected from Sendbird.');
  } catch (error) {
    console.error('Sendbird operation failed:', error);
  }
}

initializeAndConnect();