/ SDKs / JavaScript
SDKs
Chat SDKs JavaScript v4
Chat SDKs JavaScript
Chat SDKs
JavaScript
Version 4

Migration guide

Copy link

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.


Supported browsers

Copy link

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

BrowserVersions

Edge

13 or higher

Chrome

16 or higher

Firefox

11 or higher

Safari

7 or higher

Opera

12.1 or higher

Android browsers

4.4 (Kitkat) or higher

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.


Breaking changes

Copy link

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

Structural changes

Copy link
  • 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.

From v3To v4

GroupChannelParams

GroupChannelCreateParams
GroupChannelUpdateParams

OpenChannelParams

OpenChannelCreateParams
OpenChannelUpdateParams

UserMessageParams

UserMessageCreateParams
UserMessageUpdateParams

FileMessageParams

FileMessageCreateParams
FileMessageUpdateParams

  • 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().

From v3To v4

nickname and profileImage in sb.updateCurrentUserInfoWithProfileImage()

nickname and profileUrl in sb.updateCurrentUserInfo()

UserUpdateParams in sb.updateCurrentUserInfo()

keys in sb.getUnreadItemCount()

UnreadItemCountParams in sb.getUnreadItemCount()

channelCustomTypesFilter in sb.getTotalUnreadMessageCount()

TotalUnreadMessageCountParams in sb.getTotalUnreadMessageCount()

  • Change getters to functions in BaseMessage and BaseChannel.
From v3To v4

isUserMessage,
isFileMessage, and
isAdminMessage

isUserMessage(),
isFileMessage(), and
isAdminMessage()

isGroupChannel and
isOpenChannel

isGroupChannel() and
isGroupChannel()

  • Move functions for unread items from SendbirdChat to GroupChannelModule.
From v3To v4

SendbirdChat.getUnreadItemCount()

SendbirdChat.groupChannel.getUnreadItemCount()

SendbirdChat.getTotalUnreadChannelCount()

SendbirdChat.groupChannel.getTotalUnreadChannelCount()

SendbirdChat.getTotalUnreadMessageCount()

SendbirdChat.groupChannel.getTotalUnreadMessageCount()

  • Add onConnected and onDisconnected to ConnectionHandler.

  • Split ChannelHandler into GroupChannelHandler and OpenChannelHandler.

JavaScriptTypeScript
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.

Name changes

Copy link
From v3To v4

SendBird

SendbirdChat

All SendBird references

Sendbird with a lowercase b

SendbirdException

SendbirdError

onReadReceiptUpdated

onUnreadMemberStatusUpdated

onDeliveryReceiptUpdated

onUndeliveredMemberStatusUpdated

SendbirdChat.Options.useMemberAsMessageSender

SendbirdChat.Options.useMemberInfoInMessage

SendbirdChat.clearCache()

SendbirdChat.clearCachedData()

requestedMentionUserIds in BaseChannel

mentionedUserIds in BaseChannel

useMemberAsMessageSender

useMemberInfoInMessage

MemberStateFilter in GroupChannelListQueryParams

MyMemberStateFilter in GroupChannelListQueryParams

MemberStateFilter in GroupChannelCountParams

MyMemberStateFilter in GroupChannelCountParams

MemberStateFilter in GroupChannelFilter

MyMemberStateFilter in GroupChannelFilter

groupChannel.cachedReadReceiptStatus

groupChannel.cachedUnreadMemberState

groupChannel.cachedDeliveryReceiptStatus

groupChannel.cachedUndeliveredMemberState

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

Deprecated

Copy link
  • 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.


Migrating to v4

Copy link

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.

Step 1 Import Sendbird Chat SDK v4

Copy link

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';

Step 2 Initialize and connect to Sendbird

Copy link

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().

From v3

Copy link
import SendBird from 'sendbird'
var sb = new SendBird({ appId: APP_ID });
JavaScriptTypeScript
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.

Step 3 Update callback patterns

Copy link

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.

From v3

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

groupChannel.sendUserMessage(params, function(userMessage, error) {
  if (error) {
    // Handle error.
  }
});
JavaScriptTypeScript
// 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.
  });
});

Step 4 Update query parameters

Copy link

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.

Get a list of group channels joined by a user

Copy link

From v3

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

Send a user message

Copy link

From v3

Copy link
const params = new sb.UserMessageParams();
params.message = 'A message';
groupChannel.sendUserMessage(params, function(userMessage, error) {});
JavaScriptTypeScript
channel.sendUserMessage({
  message: 'A message',
}).onSucceeded(message => {});

Step 5 Divide channel event handlers

Copy link

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.

From v3

Copy link
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);
JavaScriptTypeScript
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);