Migration guide

Sendbird Chat SDK v4 for JavaScript has introduced major breaking changes to streamline the code structure and enhance its scalability.

This page explains the breaking changes and provides a step-by-step guide for migrating to v4.

Note: Sendbird Chat SDK v4 supports both TypeScript and JavaScript. In this page, the codes are provided in both languages.

The following table lists browsers and their versions that the Chat SDK v4 supports.

Note: The Sendbird server supports Transport Layer Security (TLS) from version 1.0 up to 1.3. For example, in the server regions where TLS 1.3 isn’t available, lower versions will be supported for secure data transmission, sequentially from 1.2 to 1.0.

The following breaking changes have been made to the Chat SDK v4 for JavaScript.

• Replace import pattern from v3 with modules from v4.

• Refactor import, initialization of Sendbird, classes, and parameters.

• Replace callback patterns with Promise.

• Move external params into constructors.

• Creation of Sendbird instances is no longer available in v4.

• Rename the main class from SendBird to SendbirdChat.

• Separate existing params such as UserMessageParams into UserMessageCreateParams and UserMessageUpdateParams.

• All public classes whose namespace ends with Params such as UserMessageCreateParams and GroupChannelCreateParams are now changed to interfaces.

• Replace parameters with params for sb.updateCurrentUserInfo() and sb.getUnreadItemCount().

• Change getters to functions in BaseMessage and BaseChannel.

• Move functions for unread items from SendbirdChat to GroupChannelModule.

• Add onConnected and onDisconnected to ConnectionHandler.

• Split ChannelHandler into GroupChannelHandler and OpenChannelHandler.

import { GroupChannelHandler } from '@sendbird/chat/groupChannel';
import { OpenChannelHandler } from '@sendbird/chat/openChannel';

const groupChannelHandler = new GroupChannelHandler({
  onMessageReceived: (channel, message) => {},
  onChannelChanged: (channel) => {},
});
sb.groupChannel.addGroupChannelHandler(UNIQUE_HANDLER_ID, groupChannelHandler);

const openChannelHandler = new OpenChannelHandler({
  onMessageReceived: (channel, message) => {},
  onChannelChanged: (channel) => {},
});
sb.openChannel.addOpenChannelHandler(UNIQUE_HANDLER_ID, openChannelHandler);

• SendbirdChat.instance, sb.appId, sb.connectionState, sb.lastConnectedAt, sb.options.useMemberInfoInMessage, channel.cachedMetaData, and message.isResendable are now read-only.

Note: A full list of name changes will be available soon.

• Remove MessageCollectionInitPolicy.API_ONLY.

• Remove ConnectionManager, which was deprecated in v3.

• Remove channel.getMessageByID().

• Internet Explorer is no longer supported.

• Local caching in the SDK v4 can facilitate the caching-related functionalities and more. SyncManager will soon be deprecated, so we highly recommend to use local caching instead.

The following guide covers the changes and key steps required during the migration from the Chat SDK v3 to v4.

Sendbird Chat SDK v4 will likely prevent your app from compiling until all migration tasks are complete and all errors are fixed. After fixing all the blocking errors, further work may be needed to remove warnings and align the SDK with your app again. We recommend you allow a generous timeline for the task.

Sendbird Chat SDK v4 for JavaScript introduces tree shaking and modularization. There are four modules, which include sendbird, groupChannelModule,openChannelModule, and messageModule.

Centralized classes and methods belong to the core sendbird module while other features are divided between groupChannelModule and openChannelModule. Also, messageModule contains classes concerning message objects such as a user message and a file message. Import modules based on the channel type and features your app needs.

Checklist

• Identify which class to use per file.
• Remove the previous import pattern and replace them with the SDK v4's modules.
• Import the new classes for methods you need. Scroll through each file to see which methods or class instances aren't defined.

Each module needs to be imported like the code below.

import SendbirdChat, { UserUpdateParams } from '@sendbird/chat';
import { GroupChannelModule } from '@sendbird/chat/groupChannel';

Note: You must initialize Sendbird before calling any SDK interfaces.

When initializing the Sendbird instance in the Chat SDK v4, it needs to be aware of which channel module will be used. If you aren't sure which type of channel or feature to use, include both GroupChannelModule and OpenChannelModule for the purpose of the migration task. Once decided, remove the module you won't use before production in order to reduce the bundle size.

In the Chat SDK v4, use a lowercase "b" in all Sendbird references.

Checklist

• Refactor import and init().

import SendBird from 'sendbird'
var sb = new SendBird({ appId: APP_ID });

import SendbirdChat from '@sendbird/chat'
import { OpenChannelModule } from '@sendbird/chat/openChannel';

const params = {
  appId: APP_ID,
  modules: [
    new OpenChannelModule(),
  ],
};
const sb = SendbirdChat.init(params);

The sb.connect() method should work from this point on. Check if the user is online in your Sendbird Dashboard or through a websocket instance.

Unlike the previous v3 that took a params instance and a callback function, the Chat SDK v4 employs three different patterns for handling async operations: async/await, then/catch, and a success handler. The codes below show the new callback patterns.

Checklist

• Review the callback patterns in your code and replace them with the new patterns in v4. The TypeScript autocomplete can help you identify the patterns.
• As for versions prior to v3.1.0, they use raw arguments and defunct callback patterns instead. Depending on the SDK version you are currently using, the timeline for updating callback patterns can vary.

const params = new sb.UserMessageParams();
params.message = TEXT_MESSAGE;

groupChannel.sendUserMessage(params, function(userMessage, error) {
  if (error) {
    // Handle error.
  }
});

// Use async/await. The operation needs to be wrapped in an async function.
(async () => {
  try {
    const channel = await sb.groupChannel.getChannel(CHANNEL_URL);
  } catch (error) {
    console.log(error);
  }
})();

// Use .then .catch.
sb.groupChannel.getChannel(CHANNEL_URL).then(channel => {
}).catch(error => {});

// Use a success handler.
channel.sendUserMessage({ message: 'A message' })
  .onPending(message => {
    //A message hasn't sent yet.
  })
  .onSucceeded(message => {
    //A message has been sent.
  })
  .onFailed(message => {
    //A message wasn't sent.
  });
});

Sendbird Chat SDK v4 now takes the list query parameters directly. The following codes show some of the examples.

Checklist

• Move parameters into constructors in order to comply with the new v4 params pattern.

this.groupChannelQuery = this.sb.groupChannel.createMyGroupChannelListQuery();
this.groupChannelQuery.limit = 50;
this.groupChannelQuery.includeEmpty = false;
this.groupChannelQuery.order = 'latest_last_message';

this.groupChannelQuery = this.sb.groupChannel.createMyGroupChannelListQuery({
  limit: 50,
  includeEmpty: true,
  order: 'latest_last_message',
});

const params = new sb.UserMessageParams();
params.message = 'A message';
groupChannel.sendUserMessage(params, function(userMessage, error) {});

channel.sendUserMessage({
  message: 'A message',
}).onSucceeded(message => {});

The SDK v4 reduces code size by dividing a single channel event handler into two. One handler is for group channels and the other for open channels.

Checklist

• Rename channel event handler instances and methods.
• Import the associated classes.
• Refactor your channel event handler into two different handlers.

var sb = new SendBird({appId: APP_ID});
var channelHandler = new sb.ChannelHandler();

channelHandler.onMessageReceived = function(channel, message) {};
//Identify the channel type then take action.
channelHandler.onChannelChanged = function(channel) {};
channelHandler.onChannelDeleted = function(channelUrl, channelType) {};
//Identify the channel type then take action.

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

import { GroupChannelHandler } from '@sendbird/chat/groupChannel';
import { OpenChannelHandler } from '@sendbird/chat/openChannel';


const groupChannelHandler = new GroupChannelHandler({
  onMessageReceived: (channel, message) => {},
  onChannelChanged: (channel) => {},
})
sb.groupChannel.addGroupChannelHandler(UNIQUE_HANDLER_ID, groupChannelHandler);

const openChannelHandler = new OpenChannelHandler({
  onMessageReceived: (channel, message) => {},
  onChannelChanged: (channel) => {},
});
sb.openChannel.addOpenChannelHandler(UNIQUE_HANDLER_ID, openChannelHandler);