The first thing you need to do is to log in to the SendBird Dashboard and create a SendBird application. If you do not yet have an account, you can log in with Google, GitHub, or create a new account.

You should create one application per service, regardless of the platform. For example, an app released in both Android and iOS would require only one application to be created in the Dashboard.

All users within the same SendBird application are able to communicate with each other, across all platforms. This means users using iOS, Android, web clients, etc. can all chat with one another. However, users in different SendBird applications cannot talk to each other.

You will need a local server to run the sample project. In this example, we'll be using Python to run our local server.

1. Download and install Python if you do not have it installed in your system.
2. Clone the project.

   $ git clone https://github.com/smilefam/SendBird-JavaScript
   

3. Open a terminal and run a Python HTTP Server in your project path.

   $ cd web-sample
   # If you use Python 2
   $ python -m SimpleHTTPServer 8000
   # or Python 3
   $ python -m http.server 8000
   

4. Try connecting to http://localhost:8000 from a web browser to view the sample project.

Using Bower

$ bower install sendbird

Using Npm

$ npm install sendbird

Download the SendBird JavaScript SDK file and add it to your Project classpath (generally the libs/ directory).

Then include the JavaScript file on your page.

<script src="lib/SendBird.min.js"></script>

• MS IE 10+ (IE8/9 support should be available soon.)
• MS Edge 13+
• Chrome 16+
• Firefox 11+
• Safari 7+
• Opera 12.1+
• iOS 7+ Safari
• Android 4.4+ (Kitkat) Browser

1. Download and install node and npm.
2. Clone the sample project from GitHub.

   $ git clone https://github.com/smilefam/SendBird-JavaScript
   

3. Open a terminal and run the following commands in your project path.

   $ cd react-native-sample/SendBirdReactNativeSample
   $ npm install
   $ npm install -g react-native-cli
   

4. Run the sample app in an iOS simulator.

   $ react-native run-ios
   

5. Run the sample app in an Android simulator. You should run the simulator from Android Studio before running this command.

   $ react-native run-android
   

In a callback, the error parameter is passed last in order by default. For example, connect() below returns parameters in (user, error) order.

sb.connect(userId, function(user, error) {});

It is possible to configure SendBird to change this order by calling sb.setErrorFirstCallback(true). Once true is set, all callbacks will pass the error as the first parameter.

sb.setErrorFirstCallback(true);
sb.connect(userId, function(error, user) {});

sb.setErrorFirstCallback(false) will return callbacks to their original parameter ordering, with errors last.

To use its chat features, you must initialize SendBird using the APP_ID assigned to your SendBird application.
Typically, initialization would be implemented in the user login view.

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

By default, SendBird requires only a UserID to join a channel. Upon requesting connection, SendBird will query its user database for a matching UserID. If it finds that the UserID has not been registered yet, a new user account will be created. The UserID can be any unique string id, such as an email address or a UID from your database.

This simple authentication procedure might be useful when you are in development or if your service does not require additional security.

Explanation on SendBird's usage of Handlers and callbacks can be found under the Event Handler section.

sb.connect(userId, function(user, error) {});

You must connect to SendBird before calling any methods through the SDK (apart from initializing SendBird). If you attempt to call a method without connecting, you may receive an API-TOKEN is missing error.

With the SendBird Platform API, you can create a user with an access token, or you can issue an access token for an existing user. Once an access token is issued, you are required to provide the user's token in the login method.

1. Create a SendBird user account via the Platform API when your user signs up on your service.
2. Save the access token to your secured persistent store.
3. Load the access token in your client and pass it to the SendBird login method.
4. For security reasons, we recommend that you periodically update your access token by issuing a new token to replace the previous one.

You can set restrictions for users without access tokens in your Dashboard settings.
These settings can be found under Security - Access Token Policy.

sb.connect(userId, accessToken, function(user, error) {});

You should disconnect from SendBird when your user no longer needs to receive messages from an online state.

Users will still be able to receive Group Channel messages through Push Notificions in React Native.

Disconnecting removes all registered handlers and callbacks. That is, it removes all Event Handlers added through sb.addChannelHandler() or sb.addConnectionHandler(). It also flushes all internally cached data, such as the channels that are cached when sb.OpenChannel.getChannel() or sb.GroupChannel.getChannel() is called.

sb.disconnect(function(){
    // You are disconnected from SendBird.
});

You can update a user's nickname and profile image.

Call updateCurrentUserInfo(nickname, profileUrl, callbackFunction) to update a user's nickname, as well as their profile picture with a URL.

sb.updateCurrentUserInfo(nickname, profileUrl, function(response, error) {
  console.log(response, error);
});

Or, you can upload an image directly using updateCurrentUserInfoWithProfileImage(nickname, profileFile, callbackFunction).

sb.updateCurrentUserInfoWithProfileImage(nickname, profileFile, function(response, error) {
  console.log(response, error);
});

You should understand the following terminology before proceeding with the rest of this guide.

An Open Channel is a public chat. In this channel type, anyone can enter and participate in the chat without permission. A single channel can handle thousands of simultaneous users. i.e.) a Twitch-style public chat

A Group Channel is a private chat. A user may join the chat only through an invitation by another user who is already a member of the chatroom.

• Distinct property : A channel with the Distinct property enabled will always be reused for the same members. If a new member is invited, or if a member leaves the channel, then the Distinct property is disabled automatically.

• 1-on-1 messaging : 1-on-1 messaging is a private channel between two users. You can enable the Distinct property for the channel in order to reuse a channel for the same members. i.e.) Twitter Direct Messages-style 1-on-1 chatting

• Group messaging : Group messaging is a private channel among multiple users. You can invite up to hundreds of members into a group channel. i.e.) a WhatsApp-style closed group chat

An Open Channel is a public chat. In this channel type, anyone can enter and participate in the chat without permission. A single channel can handle thousands of simultaneous users. i.e.) a Twitch-style public chat

You can create an Open Channel from the SendBird Dashboard.

To create a channel, you must specify a Channel URL, which is a unique identifier. Additionally, you can set a Channel Topic, the name of the channel.

An open channel is ideal for use cases that require a small and static number of channels - for example, when you have a central "Lobby Chat" within a game.

You can also create a channel via the SDK or the SendBird Platform API. You should do so when your channel needs to be created on demand or dynamically.

sb.OpenChannel.createChannel(name, coverUrl, data, function(createdChannel, error) {
    if (error) {
        console.error(error);
        return;
    }

    // onCreated
    console.log(createdChannel);
});

You can obtain a list of all Open Channels by creating a OpenChannelListQuery.
The next() method returns a list of OpenChannel objects.

You must be connected to SendBird before requesting an Open Channel List.

var openChannelListQuery = sb.OpenChannel.createOpenChannelListQuery();

openChannelListQuery.next(function (channels, error) {
    if (error) {
        console.log(error);
        return;
    }

    console.log(channels);
});

Since a channel URL is a unique identifier of an Open Channel, you can use a URL to retrieve a channel instance. It is important to remember that a user must enter the channel before being able to send or receive messages within it.

Store channel URLs to handle lifecycle or state changes in your app. For example, if a user disconnects from SendBird by temporarily switching to another app, you can provide a smooth restoration of the user's state using a stored URL to fetch the appropriate channel instance, then re-entering the user into the channel.

sb.OpenChannel.getChannel(channelUrl, function(channel, error) {
    if(error) {
        console.error(error);
        return;
    }

    // Successfully fetched the channel.
    console.log(channel);
});

A user must enter an Open Channel in order to receive messages.

You may enter up to 10 Open Channels at once.

Entered Open Channels are valid only within the current connection. If you disconnect or reconnect to SendBird, you must re-enter channels in order to continue receiving messages.

sb.OpenChannel.getChannel(channelUrl, function (channel, error) {
    if (error) {
        console.error(error);
        return;
    }

    channel.enter(function(response, error){
        if (error) {
            console.error(error);
            return;
        }
    });
});

To stop receiving messages from an Open Channel, you must exit the channel.

sb.OpenChannel.getChannel(channelUrl, function (channel, error) {
    if (error) {
        console.error(error);
        return;
    }

    channel.exit(function(response, error){
        if (error) {
            console.error(error);
            return;
        }
    });
});

Upon entering a channel, a user will be able to send messages of the following types:

• UserMessage : a User text message.
• FileMessage : a User binary message.

You can additionally specify a customType to further subclassify a message.

When you send a text message, you can additionally attach arbitrary strings via a data field. You can utilize this field to send structured data such as font sizes, font types, or custom JSON objects.

Delivery failures (e.g., due to network issues) will return an exception. By implementing the callback below, it is possible to display only the messages that are successfully sent.

channel.sendUserMessage(message, data, customType, function(message, error){
    if (error) {
        console.error(error);
        return;
    }

    // onSent
    console.log(message);
});

A user can also send any binary file through SendBird. There are two ways in which you can send a binary file: by sending the file itself, or by sending a URL.

By sending a raw file, you are uploading it to the SendBird servers. Alternatively, you can choose to send a file hosted in your own servers by passing in a URL that points to the file. In this case, your file will not be hosted in the SendBird servers, and downloads of the file will occur through your own servers instead.

Note that if you upload your file directly, a size limit is imposed per file. This limit depends on your plan, and can be viewed from your Dashboard.

No file size limit is imposed if you send a File Message via a URL. Your file will not be uploaded to the SendBird servers.

// Sending File Message with raw file

channel.sendFileMessage(file, data, customType, function(fileMessage, error){
    if (error) {
        console.error(error);
        return;
    }

    // onSent
    console.log(fileMessage);
});

// Sending File Message with file URL

channel.sendFileMessage(fileUrl, name, type, size, data, customType, function(fileMessage, error){
    if (error) {
        console.error(error);
        return;
    }

    // onSent
    console.log(fileMessage);
});

To send metadata along with a file, you can populate the data field.

Messages can be received by adding a ChannelHandler.
A received BaseMessage object can be of one of three different types of messages.

• UserMessage : a User text message.
• FileMessage : a User binary message.
• AdminMessage : an Admin message which can be sent by an admin through the Platform API.

UNIQUE_HANDLER_ID is a unique identifier to register multiple concurrent handlers.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageReceived = function(channel, message){
    console.log(channel, message);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

You can load previous messages by creating a query using createPreviousMessageListQuery() and calling load().
You will be able to display past messages in your UI once they have loaded.

var messageListQuery = channel.createPreviousMessageListQuery();

messageListQuery.load(30, true, function(messageList, error){
    if (error) {
        console.error(error);
        return;
    }
    console.log(messageList);
});

Past messages are queried in fixed numbers (30 in the above code). A new PreviousMessageListQuery instance will load the most recent n messages. Calling load() on the same query instance will load n messages before that. Therefore, you should store your query instance as a member variable in order to traverse through your entire message history.

An important note is that you must ensure that you have received a callback before calling load() again.

You can query a set number of previous messages starting from the timestamp of the earliest message.

Note that the number of results may be larger than the set limit when there are multiple messages with the same timestamp as the earliest message.

var messageListQuery = channel.createMessageListQuery();

messageListQuery.prev(earliestMessageTimestamp, limit, reverseOrder, function(messageList, error){
    if (error) {
        console.error(error);
        return;
    }
    console.log(messageList);
});

Participants are online users who are currently receiving all messages from the open channel.

var participantListQuery = channel.createParticipantListQuery();

participantListQuery.next(function (participantList, error) {
    if (error) {
        console.error(error);
        return;
    }
    console.log(participantList);
});

To stay updated on each participant's connection status, you must obtain a new UserListQuery, which contains the lastest information on each user. To get a UserListQuery for a specific channel, call channel.createParticipantListQuery(). If you wish to get the list of all users of your service (application), call sb.createUserListQuery().

You can then check each of the users' connection statuses by making calls to user.connectionStatus.

If your application needs to keep track of users' connection statuses in real time, we recommend that you receive a new UserListQuery periodically, perhaps in intervals of one minute or more.

connectionStatus can return one of three values:

• nonavailable : User's status information cannot be reached.
• offline : User is disconnected from SendBird.
• online : User is connected to SendBird.

var participantListQuery = openChannel.createParticipantListQuery();

participantListQuery.next(function (participantList, error) {
    if (error) {
        console.error(error);
        return;
    }
    console.log(participantList);
});

You can also create a query to get a list of muted or banned users in an open channel.

This query is only available for users who are registered as operators of the open channel.

var UserListQuery = openChannel.createBannedUserListQuery();  //or createMutedUserListQuery()

UserListQuery.next(function (userList, error) {
    if (error) {
        console.error(error);
        return;
    }

    console.log(userList);
});

Users are able to delete messages. An error is returned if a user tries to delete messages sent by someone else.
Channel Operators are able to delete any message in the channel, including those by other users.

Deleting a message fires a onMessageDeleted event to all other users in the channel.

channel.deleteMessage(message, function(response, error){
    if (error) {
        console.error(error);
        return;
    }
});

You can receive a onMessageDeleted event in the channel handler.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageDeleted = function (channel, messageId) {
    console.log('ChannelHandler.onMessageDeleted: ', channel, messageId);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

You can send Admin messages to users in a channel using the SendBird Dashboard or the Platform API.

To do so using the Dashboard, navigate to the Open Channels tab. Inside the message box, you should see an option to send an Admin message. Admin messages should not be longer than 1000 characters.

If you are currently developing under the Free Plan and therefore cannot access the Moderation Tools from the Dashboard, you must send Admin messages through the Platform API.

When creating a channel, you can add a cover image by specifying an image URL or file.

sb.OpenChannel.createChannel(name, coverUrl, data, function(createdChannel, error){
    if (error) {
        console.error(error);
        return;
    }
    // onCreated
});

You can retrieve the cover image URL with channel.coverUrl. You can also update a channel's cover image by calling update().

When creating a channel, you can additionally specify a Custom Type to further subclassify your channels. This custom type takes on the form of a String, and can be handy in searching or filtering channels.

data and customType are both String fields that allow you to append information to your channels. The intended use case is for customType to contain information that can subclassify the channel (e.g., distinguishing "School" and "Work" channels). However, both these fields can be flexibly utilized.

sb.OpenChannel.createChannel(name, coverUrl, data, operatorUserIds, customType, function(createdChannel, error){
    if (error) {
        console.error(error);
        return;
    }

    // onCreated
});

channel.customType returns a channel's Custom Type.

Likewise, you can specify a Custom Type for messages in order to categorize them into more specific groups. This custom type takes on the form of a String, and can be useful in searching or filtering messages.

data and customType are both String fields that allow you to append information to your messages. The intended use case is for customType to contain information that can subclassify the message (e.g., distinguishing "FILE_IMAGE" and "FILE_AUDIO" type messages). However, both these fields can be flexibly utilized.

To embed a Custom Type into a message, simply pass a String parameter to channel.sendUserMessage() or channel.sendFileMessage().

channel.sendUserMessage(message, data, customType, function(message, error){
    if (error) {
        console.error(error);
        return;
    }

    // onSent
});

message.customType returns a message's Custom Type.

This feature is not available under the Free plan. Contact sales@sendbird.com if you wish to implement this functionality.

SendBird makes it possible for messages to be sent in different languages through its auto-translation feature.
Pass in a List of language codes to sendUserMessage() to request translated messages in the corresponding languages.

var targetLangList = ["es", "ko"];

channel.sendUserMessage(message, data, customType, targetLangList, function(message, error){
    if (error) {
        console.error(error);
        return;
    }

    // onSent
});

You can obtain translations of a message with userMessage.translations. This returns an Object containing the language codes and translations.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageReceived = function (channel, message) {
    var esTranslation = message.translations["es"];

    // Display translation in UI.
};

sb.addChannelHandler(UNIQUE_CHANNEL_ID, ChannelHandler);

Reference the table below for supported languages and their language codes.

You can search for specific channels by adding a keyword to your OpenChannelListQuery.
There are two types of keywords: a Name Keyword and a URL Keyword.

Adding a Name Keyword to a query will return the list of Open Channels that have the keyword included in their names.

var openChannelListQuery = sb.OpenChannel.createOpenChannelListQuery();
openChannelListQuery.nameKeyword = "NameKeyword";

openChannelListQuery.next(function (channels, error) {
    if (error) {
        console.log(error);
        return;
    }

    // Returns a Array of channels that have "NameKeyword" in their names.
    console.log(channels);
});

Adding a URL Keyword to a query will return the Open Channel whose URL exactly matches the given keyword.

var openChannelListQuery = sb.OpenChannel.createOpenChannelListQuery();
openChannelListQuery.urlKeyword = "UrlKeyword";

openChannelListQuery.next(function (channels, error) {
    if (error) {
        console.log(error);
        return;
    }

    // Returns a List containing a single channel with the URL that matches the URL Keyword.
    console.log(channels);
});

This feature is not available under the Free plan. Contact sales@sendbird.com if you wish to implement this functionality.

When sending an image file, you can choose to create thumbnails of the image, which you can fetch and render into your UI. You can specify up to 3 different dimensions to generate thumbnail images in, which can be convenient for supporting various display densities.

Supported file types are files whose MIME type is image/* or video/*.

The SDK does not support creating thumbnails when sending a File Message via a file URL.

Create a List of FileMessage.ThumbnailSize objects to pass to channel.sendFileMessage(). A ThumbnailSize can be created with the constructor ThumbnailSize(int maxWidth, int maxHeight), where the values specify pixels. The onSent() callback will subsequently return a List of Thumbnail objects that each contain the URL of the generated thumbnail image file.

var thumbnailSizes = [];

// Create and add ThumbnailSizes (Max: 3 ThumbnailSizes).
thumbnailSizes.push({'maxWidth': 100,'maxHeight': 100});
thumbnailSizes.push({'maxWidth': 200,'maxHeight': 200});

channel.sendFileMessage(file, data, customType, thumbnailSizes, function(fileMessage, error){
    if (error) {
        console.error(error);
        return;
    }

    var thumbnailFirst = fileMessage.thumbnails[0];
    var thumbnailSecond = fileMessage.thumbnails[1];

    var maxHeightFirst = thumbnailFirst.maxHeight; // 100
    var maxHeightSecond = thumbnailSecond.maxHeight; // 200

    var urlFirst = thumbnailFirst.url; // URL of first thumbnail file.
    var urlSecond = thumbnailSecond.url; // URL of second thumbnail file.
});

maxWidth and maxHeight specify the maximum dimensions of the thumbnail. Your image will be scaled down evenly to fit within the bounds of (maxWidth, maxHeight). Note that if the original image is smaller than the specified dimensions, the thumbnail will not be scaled. url returns the location of the generated thumbnail file within the SendBird servers.

It is possible to modify a UserMessage that has already been sent. In order to do so, you must know the messageId, which is a unique ID assigned to all messages within a channel.

channel.updateUserMessage(messageId, message, data, customType, function(userMessage, error) {
  if (error) {
    console.error(error);
    return;
  }

  // do something...
  console.log(userMessage);
});

It is possible to modify a FileMessage that has already been sent. In order to do so, you must know the messageId, which is a unique ID assigned to all messages within a channel.

channel.updateFileMessage(messageId, data, customType, function(fileMessage, error) {
  if (error) {
    console.error(error);
    return;
  }

  // do something...
  console.log(fileMessage);
});

You can receive an updated message through a ChannelHandler.
UNIQUE_HANDLER_ID is a unique identifier to register multiple concurrent handlers.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageUpdated = function(channel, message){
  // do something...
  console.log(channel, message);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

You should remove the channel handler when the UI is no longer valid.

sb.removeChannelHandler(UNIQUE_HANDLER_ID);

You can check the progress of a file upload by passing a progressHandler as a parameter when calling sendFileMessage().

var sentFileMessage = channel.sendFileMessage(file, '', '', 
  function(event) { // check progress of upload request
    // do something...
    console.log(parseInt(Math.floor(e.loaded/e.total * 100)) + '%');
  },
  function(fileMessage, error) { // callback
    // do something...
    console.log(fileMessage, error);
  }
);

You can cancel a file upload while it is not yet complete. If this function is successful, true will be passed back as the first parameter.

Note that if the upload is complete, has already been cancelled, or has returned an error, attempting to cancel it will return an error.

var sentFileMessage = channel.sendFileMessage(file, '', '', function(fileMessage, error) {
  // do something...
  console.log(fileMessage, error);
});

channel.cancelUploadingFileMessage(sentFileMessage.reqId, function(isSuccess, error) {
  if (error) {
    console.error(error);
    return;
  }

  // do something...
  console.log(isSuccess);
});

A Group Channel is a private chat. A user may join the chat only through an invitation by another user who is already a member of the chatroom. A Group Channel can consist of one to hundreds of members. Creating a channel with two members allows 1-to-1 messaging.

A user will automatically receive all messages from the group channels that they are a member of.

A Group Channel can be created on demand by a user through the SendBird SDK.

Distinct property : A channel with the Distinct property enabled will always be reused for the same members. If a new member is invited, or if a member leaves the channel, then the distinct property is disabled automatically. For example, in the case that a Group Channel with 3 members, A, B, and C, already exists, attempting to create a new channel with the same members will just return a reference to the existing channel.

Consequently, we recommend that you enable the Distinct property in 1-to-1 messaging channels in order to reuse the same channel when a user chooses to directly message a friend. If the property is disabled, the user will create a new channel even if they have had previous conversations with the friend, and therefore will not be able to see or access previously sent messages or data.

var userIds = ['unique_user_id1', 'unique_user_id2'];
// distinct is false 
sb.GroupChannel.createChannelWithUserIds(userIds, false, name, cover_url, data, function(createdChannel, error) {
    if (error) {
        console.error(error);
        return;
    }

    console.log(createdChannel);
});

You can also append information by passing additional arguments.

var userIds = ['unique_user_id1', 'unique_user_id2'];

sb.GroupChannel.createChannelWithUserIds(userIds, distinct, name, coverUrl, data, customType, function(createdChannel, error) {
    if (error) {
        console.error(error);
        return;
    }

    console.log(createdChannel);
});

• name : the name of the channel, or the Channel Topic.
• distinct : whether the channel should be Distinct.
• coverUrl : the file or URL of the cover image, which you can fetch to render into the UI.
• data : a String field to store structured information, such as a JSON String.
• customType : a String field that allows you to subclassify your channel.

See the Advanced section for more information on cover images and Custom Types.

You can also create channels via the SendBird Platform API.
You should utilize the Platform API when you wish to control channel creations and member invitations on the server-side.

Since a channel URL is a unique identifier of a Group Channel, you can use a URL to retrieve a channel instance.

Store channel URLs to handle lifecycle or state changes in your app. For example, if a user disconnects from SendBird by temporarily switching to another app, you can provide a smooth restoration of the user's state using a stored URL to fetch the appropriate channel instance, then re-entering the user into the channel.

sb.GroupChannel.getChannel(channelUrl, function(channel, error) {
    if (error) {
        console.error(error);
        return;
    }

    // Successfully fetched the channel.
    console.log(channel);
});

Only members of the channel are able to invite new users into the channel.

You can choose whether the newly invited user is able to access past messages in the channel. In your Dashboard Settings - Messages section, there is an option to show channel history. If this option is enabled, new users will be able to view all messages sent before they have joined the channel. If not, new users will only be able to see messages sent after they had been invited.

Show channel history is enabled by default.

groupChannel.inviteWithUserIds(userIds, function(response, error) {
    if (error) {
        console.error(error);
        return;
    }
});

Users will no longer receive messages from channels they have left.

groupChannel.leave(function(response, error) {
    if (error) {
        console.error(error);
        return;
    }
});

You can obtain a list of all Group Channels by creating a createMyGroupChannelListQuery().
The next() method returns a list of GroupChannel objects. You can also set an option to include empty channels.

You can also set an option to include empty channels by setting includeEmpty = true. Empty channels are channels that have been created but contain no sent messages. By default, empty channels are not shown.

var channelListQuery = sb.GroupChannel.createMyGroupChannelListQuery();
channelListQuery.includeEmpty = true;
channelListQuery.limit = 20; // pagination limit could be set up to 100

if (channelListQuery.hasNext) {
    channelListQuery.next(function(channelList, error){
        if (error) {
            console.error(error);
            return;
        }

        console.log(channelList);
    });
}

It is possible to filter a channel search by user IDs. This can be done by creating a userIdsFilter.

Given an example where a user (with the ID "User") is part of two Group Channels:

• channelA: [ "User", "John", "Jay" ]
• channelB: [ "User", "John", "Jay", "Jin" ]

An ExactFilter returns the list of channels containing exactly the queried userIDs.

var channelListQuery = sb.GroupChannel.createMyGroupChannelListQuery();
var userIds = [];
userIds.push("John");
userIds.push("Jay");

channelListQuery.userIdsFilter = userIds;

if (channelListQuery.hasNext) {
    channelListQuery.next(function(channelList, error){
        if (error) {
            console.error(error);
            return;
        }

        // returns channelA only.
        console.log(channelList);
    });
}

An IncludeFilter returns channels where the userIDs are included. This method can return one of two different results, based on the paramater queryType.

var channelListQuery = sb.GroupChannel.createMyGroupChannelListQuery();
var userIds = [];
userIds.push("John");
userIds.push("Jay");
userIds.push("Jin");

channelListQuery.userIdsFilter = userIds;
channelListQuery.queryType = "AND";

if (channelListQuery.hasNext) {
    channelListQuery.next(function(channelList, error){
        if (error) {
            console.error(error);
            return;
        }

        // returns channels that include the ids { John, Jay, Jin } as a subset.

        // i.e. returns channelB only.
        console.log(channelList);
    });
}

channelListQuery.queryType = "OR";

if (channelListQuery.hasNext) {
    channelListQuery.next(function(channelList, error){
        if (error) {
            console.error(error);
            return;
        }

        // returns channels that include { John }, plus channels that include { Jay },
        // plus channels that include { Jin }.

        // i.e. returns both channelA, channelB.
        console.log(channelList);
    });
}

Upon entering a channel, a user will be able to send messages of the following types:

• UserMessage : a User text message.
• FileMessage : a User binary message.

You can additionally specify a customType to further subclassify a message.

When you send a text message, you can additionally attach arbitrary strings via a data field. You can utilize this field to send structured data such as font size, font type, or a custom JSON object.

Delivery failures (e.g., due to network issues) will return an exception. By receiving a callback within an implementation of sendUserMessage(), it is possible to display only the messages that are successfully sent.

channel.sendUserMessage(message, data, customType, function(message, error){
    if (error) {
        console.error(error);
        return;
    }

    console.log(message);
});

A user can also send any binary file through SendBird. There are two ways in which you can send a binary file: by sending the file itself, or by sending a URL.

By sending a raw file, you are uploading it to the SendBird servers. Alternatively, you can choose to send a file hosted in your own servers by passing in a URL that points to the file. In this case, your file will not be hosted in the SendBird servers, and downloads of the file will occur through your own servers instead.

Note that if you upload your file directly, a size limit is imposed per file. This limit depends on your plan, and can be viewed from your Dashboard.

No file size limit is imposed if you send a File Message via a URL. Your file will not be uploaded to the SendBird servers.

// Sending File Message with raw file

channel.sendFileMessage(file, name, type, size, data, customType, function(fileMessage, error){
    if (error) {
        console.error(error);
        return;
    }
    console.log(fileMessage);
});

// Sending File Message with file URL

channel.sendFileMessage(fileUrl, data, customType, function(fileMessage, error){
    if (error) {
        console.error(error);
        return;
    }
    console.log(fileMessage);
});

channel.sendFileMessage(fileUrl, name, type, size, data, customType, function(fileMessage, error){
    if (error) {
        console.error(error);
        return;
    }
    console.log(fileMessage);
});

To send metadata along with a file, you can populate the data field.

Messages can be received by adding a ChannelHandler.
A received BaseMessage object can be of one of three different types of messages.

• UserMessage : a User text message.
• FileMessage : a User binary message.
• AdminMessage : an Admin message which can be sent by an admin through the Platform API.

UNIQUE_HANDLER_ID is a unique identifier to register multiple concurrent handlers.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageReceived = function(channel, message){
    console.log(channel, message);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

You should remove the channel handler when the UI is no longer valid.

sb.removeChannelHandler(UNIQUE_HANDLER_ID);

You can load previous messages by creating a query using createPreviousMessageListQuery() calling load(). You will be able to display these messages in your UI once they have loaded.

Whether a user can load messages prior to joining the channel depends on your settings. In your Dashboard Settings - Messages section, there is an option to show channel history. If this option is enabled, new users will be able to view all messages sent before they have joined the channel. If not, new users will only be able to see messages sent after they had been invited.

var messageListQuery = channel.createPreviousMessageListQuery();

messageListQuery.load(30, true, function(messageList, error){
    if (error) {
        console.error(error);
        return;
    }
    console.log(messageList);
});

Past messages are queried in fixed numbers (30 in the above code). A new PreviousMessageListQuery instance will load the most recent n messages. Calling load() on the same query instance will load n messages before that. Therefore, you should store your query instance as a member variable in order to traverse through your entire message history.

An important note is that you must ensure that you have received a callback before calling load() again.

Users are able to delete messages. An error is returned if a user tries to delete messages sent by someone else.
Channel Operators are able to delete any message in the channel, including those by other users.

Deleting a message fires a onMessageDeleted event to all other users in the channel.

channel.deleteMessage(message, function(response, error){
    if (error) {
        console.error(error);
        return;
    }

});

You can receive a onMessageDeleted event using a ChannelHandler.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageDeleted = function (channel, messageId) {
    console.log('ChannelHandler.onMessageDeleted: ', channel, messageId);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

A 1-to-1 chat is just a Group Channel with two members.

A Group Channel can be created on demand by a user through the client SDK. Pass in two user IDs to create a 1-to-1 chat between two users.

You would typically want a 1-to-1 chat to be Distinct. If the Distinct property is not enabled, the user will be able to create a new channel with the same opponent, even if they have had previous conversations. In this case, multiple 1-to-1 chats between the same two users might exist, each with its own chat history and data.

// For typical 1-to-1 chat which is unique between two users
sb.GroupChannel.createChannelWithUserIds(['another_user_id'], true, name, coverFile, data, customType, function(createdChannel, error){
    if (error) {
        console.error(error);
        return;
    }

});

• name : the name of the channel, or the Channel Topic.
• distinct : whether the channel should be Distinct. This should be true for 1-to-1 chats.
• coverFile : the file or URL of the cover image, which you can fetch to render into the UI.
• data : a String field to store structured information, such as a JSON String.
• customType : a String field that allows you to subclassify your channel.

See the Advanced section for more information on cover images and Custom Types.

You can also create channels via the SendBird Platform API.
You should utilize the Platform API when you wish to control channel creations and member invitations on the server-side.

You can obtain a list of members in a Group Channel by referencing members.

var members = groupChannel.members;

Members are automatically updated when you are online. If you disconnect from SendBird and reconnect, you should refresh() the channel to be updated with the latest information.

groupChannel.refresh(function(response, error){
    if (error) {
        console.error(error);
        return;
    }

    // onRefresh
});

To stay updated on each member's connection status, call channel.refresh() before accessing channel.members.
You can then check each of the users' connection statuses by getting user.connectionStatus.

If your application needs to keep track of users' connection statuses in real time, we recommend that you refresh() your channel instance periodically, perhaps in intervals of one minute or more.

connectionStatus can return one of three values:

• nonavailable : User's status information cannot be reached.
• offline : User is disconnected from SendBird.
• online : User is connected to SendBird.

You can send typing events by invoking startTyping and endTyping.

groupChannel.startTyping();
groupChannel.endTyping();

You can receive a onTypingStatusUpdated event in the channel handler.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onTypingStatusUpdated = function(channel){
    console.log(channel);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

A user can indicate that they have read a message by calling markAsRead().

groupChannel.markAsRead();

This broadcasts a onReadReceiptUpdated event, which can be handled with a ChannelHandler.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onReadReceiptUpdated = function(channel){
    console.log(channel);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

getReadReceipt(BaseMessage) returns the number of members in the channel who have not read the message.

var unreadCount = channel.getReadReceipt(message);

You can send Admin messages to users in a channel using the SendBird Dashboard or the Platform API.

To do so using the Dashboard, navigate to the Group Channels tab. Inside the message box, you should see an option to send an Admin message. Admin messages should not be longer than 1000 characters.

If you are currently developing under the Free Plan and therefore cannot access the Moderation Tools from the Dashboard, you must send Admin messages through the Platform API.

When creating a channel, you can add a cover image by specifying an image URL or file.

sb.GroupChannel.createChannel(name, coverUrl, data, function(channel, error){
    if (error) {
        console.error(error);
        return;
    }
});

You can retrieve the cover image URL with channel.coverUrl. You can also update a channel's cover image by calling update().

When creating a channel, you can additionally specify a Custom Type to further subclassify your channels. This custom type takes on the form of a String, and can be handy in searching or filtering channels.

data and customType are both String fields that allow you to append information to your channels. The intended use case is for customType to contain information that can subclassify the channel (e.g., distinguishing "School" and "Work" channels). However, both these fields can be flexibly utilized.

// distinct is false
sb.GroupChannel.createChannel(users, false, name, coverUrl, data, customType, function(channel, error){
    if (error) {
        console.error(error);
        return;
    }

    console.log(channel);
});

To get a channel's Custom Type, access channel.customType.

Likewise, you can specify a Custom Type for messages in order to categorize them into more specific groups. This custom type takes on the form of a String, and can be useful in searching or filtering messages.

DATA and CUSTOM_TYPE are both String fields that allow you to append information to your messages. The intended use case is for CUSTOM_TYPE to contain information that can subclassify the message (e.g., distinguishing "FILE_IMAGE" and "FILE_AUDIO" type messages). However, both these fields can be flexibly utilized.

To embed a Custom Type into a message, simply pass a String parameter to channel.sendUserMessage() or channel.sendFileMessage().

channel.sendUserMessage(message, data, customType, function(response, error){
    if (error) {
        console.error(error);
        return;
    }
});

To get a message's Custom Type, call message.customType.

This feature is not available under the Free plan. Contact sales@sendbird.com if you wish to implement this functionality.

SendBird makes it possible for messages to be sent in different languages through its auto-translation feature.
Pass in a List of language codes to sendUserMessage() to request translated messages in the corresponding languages.

var targetLanguages = ["es", "ko"];

channel.sendUserMessage(message, data, customType, targetLanguages, function(response, error){
    if (error) {
        console.error(error);
        return;
    }

    // onSent
});

You can obtain translations of a message using userMessage.translations. This method returns a Object containing the language codes and translations.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageReceived = function (channel, message) {
    var esTranslation = message.translations["es"];

    // Display translation in UI.
};

sb.addChannelHandler(UNIQUE_CHANNEL_ID, ChannelHandler);

Reference the table below for supported languages and their language codes.

This feature is not available under the Free plan. Contact sales@sendbird.com if you wish to implement this functionality.

When sending an image file, you can choose to create thumbnails of the image, which you can fetch and render into your UI. You can specify up to 3 different dimensions to generate thumbnail images in, which can be convenient for supporting various display densities.

Supported file types are files whose MIME type is image/* or video/*.

The SDK does not support creating thumbnails when sending a File Message via a file URL.

Create ThumbnailSize object to pass to channel.sendFileMessage(). A ThumbnailSize can be created with object {'maxWidth', 'maxHeight'}, where the values specify pixels. The callback will subsequently return a Array of Thumbnail objects that each contain the URL of the generated thumbnail image file.

var thumbnailSizes = [];

// Create and add ThumbnailSizes (Max: 3 ThumbnailSizes).
thumbnailSizes.push({'maxWidth': 100,'maxHeight': 100});
thumbnailSizes.push({'maxWidth': 200,'maxHeight': 200});

channel.sendFileMessage(file, data, customType, thumbnailSizes, function(message, error){
    if (error) {
        console.error(error);
        return;
    }

    var thumbnailFirst = message.thumbnails[0];
    var thumbnailSecond = message.thumbnails[1];

    var maxHeightFirst = thumbnailFirst.maxHeight; // 100
    var maxHeightSecond = thumbnailSecond.maxHeight; // 200

    var urlFirst = thumbnailFirst.url; // URL of first thumbnail file.
    var urlSecond = thumbnailSecond.url; // URL of second thumbnail file.
});

maxWidth and maxHeight specify the maximum dimensions of the thumbnail. Your image will be scaled down evenly to fit within the bounds of (maxWidth, maxHeight). Note that if the original image is smaller than the specified dimensions, the thumbnail will not be scaled. url stores the location of the generated thumbnail file within the SendBird servers.

It is possible to modify a UserMessage that has already been sent. In order to do so, you must know the messageId, which is a unique ID assigned to all messages within a channel.

channel.updateUserMessage(messageId, message, data, customType, function(userMessage, error) {
  if (error) {
    console.error(error);
    return;
  }

  // do something...
  console.log(userMessage);
});

It is possible to modify a FileMessage that has already been sent. In order to do so, you must know the messageId, which is a unique ID assigned to all messages within a channel.

channel.updateFileMessage(messageId, data, customType, function(fileMessage, error) {
  if (error) {
    console.error(error);
    return;
  }

  // do something...
  console.log(fileMessage);
});

You can receive an updated message through a ChannelHandler.
UNIQUE_HANDLER_ID is a unique identifier to register multiple concurrent handlers.

var ChannelHandler = new sb.ChannelHandler();

ChannelHandler.onMessageUpdated = function(channel, message){
  // do something...
  console.log(channel, message);
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

You should remove the channel handler when the UI is no longer valid.

sb.removeChannelHandler(UNIQUE_HANDLER_ID);

You can check the progress of a file upload by passing a progressHandler as a parameter when calling sendFileMessage().

var sentFileMessage = channel.sendFileMessage(file, '', '', 
  function(event) { // check progress of upload request
    // do something...
    console.log(parseInt(Math.floor(e.loaded/e.total * 100)) + '%');
  },
  function(fileMessage, error) { // callback
    // do something...
    console.log(fileMessage, error);
  }
);

You can cancel a file upload while it is not yet complete. If this function is successful, true will be passed back as the first parameter.

Note that if the upload is complete, has already been cancelled, or has returned an error, attempting to cancel it will return an error.

var sentFileMessage = channel.sendFileMessage(file, '', '', function(fileMessage, error) {
  // do something...
  console.log(fileMessage, error);
});

channel.cancelUploadingFileMessage(sentFileMessage.reqId, function(isSuccess, error) {
  if (error) {
    console.error(error);
    return;
  }

  // do something...
  console.log(isSuccess);
});

With MetaData and MetaCounter, you can store additional information within a channel.

MetaData allows you to store a Dictionary of String key-value pairs in a channel instance.
If your aim is to store an integer with atomic increasing/decreasing operations, you should use a MetaCounter instead.

Use cases for MetaData/Counters could include tracking the number of likes, the background color, or a long description of the channel, which can each be fetched and rendered into the UI.

MetaData is a Dictionary that is stored within a channel. Its uses are very flexible, allowing you to customize a channel to fit you and your users' needs.

Storing MetaData into a channel simply requires creation of a Dictionary, then passing it as an argument when calling createMetaData(). You can store multiple key-value pairs in the map.

channel.createMetaData({ testData1: 'StringA', testData2: 'StringB' }, function(response, error){
    if (error) {
        console.log(error);
        return;
    }
});

The process for updating MetaData is identical to creation. Values will be updated for existing keys, while new key-value pairs will be added.

channel.updateMetaData({ testData1: 'String1', testData2: 'String2', testData3: 'String3' }, function(response, error){
    if (error) {
        console.log(error);
        return;
    }
});

Getting stored MetaData requires creating a Collection of keys to pass as an argument to getMetaData(). The callback returns a Dictionary containing the corresponding key-value pairs.

channel.getMetaData(['testData1', 'testData2'], function(response, error){
        if (error) {
            console.log(error);
            return;
        }
});

A MetaCounter is a Map that is stored within a channel instance. Its primary uses are to track and update discrete indicators within a channel.

Storing a MetaCounter into a channel simply requires creation of a Map, then passing it as an argument when calling createMetaCounter(). You can store multiple key-value pairs in the map.

channel.createMetaCounters({ testData1: 1, testData2: 2 }, function(response, error){
    if (error) {
        console.log(error);
        return;
    }
});

Retrieving stored MetaCounters requires creating a Collection of keys to pass as an argument to getMetaCounters(). The callback returns a Dictionary containing the corresponding key-value pairs.

channel.getMetaCounters(['testData1', 'testData2'], function(response, error){
    if (error) {
        console.log(error);
        return;
    }
});

The increase and decrease operations work similarly to getting MetaCounters, as described above. Create a Dictionary of keys to pass to increaseMetaCounters(), which increments the corresponding MetaCounters by 1.

var counters = {};
counters["key1"] = 2 ; // Increases by 2.
counters["key2"] = 3 ;  // Increases by 3.
channel.increaseMetaCounters(counters, function(response, error){
    if (error) {
        console.log(error);
        return;
    }
});

Likewise, pass a Dictionary of keys to decreaseMetaCounters(), which decrements the MetaCounters by 1.

var counters = {};
counters["key1"] = 3 ; // Decreases by 2.
counters["key2"] = 4 ;  // Decreases by 3.
channel.decreaseMetaCounters(counters, function(response, error){
    if (error) {
        console.log(error);
        return;
    }
});

Event Handlers are crucial components of the SendBird SDK that allow a client to react to server-side events. These handlers contain callback methods that can be overridden to respond to specific chat-related events passed from the server. For example, ChannelHandler.onMessageReceived(BaseChannel, BaseMessage) is triggered whenever a message is received. The specifics of each received message is contained within the BaseChannel and BaseMessage arguments passed in the triggering callback.

By providing its own Event Handlers, the SendBird SDK allows a client to respond to asynchronous events without worrying about the plethora of issues surrounding client-server communication and multithreading. A chat application especially involves rapid exchanges of data that must take place in near real-time across potentially thousands of users. Therefore, the SDK optimizes communication and threading to ensure data integrity between users and servers. Add Event Handlers and implement the necessary callback methods to track events occuring within channels or a user's own device.

Register a ChannelHandler to receive information whenever events occur within a channel.

You can register multiple Channel Handlers. UNIQUE_HANDLER_ID is a unique identifier that should be given to each handler. Typically, Event Handlers would be registered in each activity in order to stay up to date with changes in the channel, as well as notify the channel of the user's own activity.

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

ChannelHandler.onMessageReceived = function (channel, message) { }; // Received a chat message.
ChannelHandler.onMessageUpdated = function (channel, message) { }; // Received an updated chat message.
ChannelHandler.onMessageDeleted = function (channel, msgId) { };  // When a message has been deleted.
ChannelHandler.onChannelChanged = function (channel) { }; // When a channel property has been changed. More information on the properties can be found below.
ChannelHandler.onChannelDeleted = function (channelUrl, channelType) { };  // When a channel has been deleted.
ChannelHandler.onReadReceiptUpdated = function (groupChannel) { }; // When read receipt has been updated.
ChannelHandler.onTypingStatusUpdated = function (groupChannel) { }; // When typing status has been updated.
ChannelHandler.onUserJoined = function (groupChannel, user) { }; // When a new member joined the group channel.
ChannelHandler.onUserLeft = function (groupChannel, user) { }; // When a member left the group channel.
ChannelHandler.onUserEntered = function (openChannel, user) { }; // When a new user entered the open channel.
ChannelHandler.onUserExited = function (openChannel, user) { }; // When a new user left the open channel.
ChannelHandler.onUserMuted = function (openChannel, user) { }; // When a user is muted on the open channel.
ChannelHandler.onUserMuted = function (openChannel, user) { }; // When a user is unmuted on the open channel.
ChannelHandler.onUserBanned = function (openChannel, user) { }; // When a user is banned on the open channel.
ChannelHandler.onUserUnbanned = function (openChannel, user) { };  // When a user is unbanned on the open channel.
ChannelHandler.onChannelFrozen = function (openChannel) { }; // When the open channel is frozen.
ChannelHandler.onChannelUnfrozen = function (openChannel) { }; // When the open channel is unfrozen.

// You should add this channel handler to SendBird object.
sb.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler);

onChannelChanged() is called whenever a one of the following channel properties have been changed :

• Push preference
• Last message (except in cases where the message is a silent Admin message)
• Unread message count
• Name, cover image, data, Custom Type
• Operators (only applicable to Open Channels)
• Distinct property (only applicable to Group Channels)

You should remove the ChannelHandler where the activity is no longer valid.

sb.removeChannelHandler(UNIQUE_HANDLER_ID);

Register a ConnectionHandler to detect changes in the user's own connection status.

You can register multiple Connection Handlers. UNIQUE_HANDLER_ID is a unique identifier that should be given to each handler. Typically, Connection Handlers would be registered in each activity in order to monitor the state of the user's connection with the SendBird servers.

var sb = new SendBird({ appId: appId })
var ConnectionHandler = new sb.ConnectionHandler();

ConnectionHandler.onReconnectStarted = function(){}; // Network has been disconnected. Auto reconnecting starts.
ConnectionHandler.onReconnectSucceeded = function(){}; // Auto reconnecting succeeded.
ConnectionHandler.onReconnectFailed = function(){}; // Auto reconnecting failed. You should call `connect` to reconnect to SendBird.

sb.addConnectionHandler(UNIQUE_HANDLER_ID, ConnectionHandler);

You should remove the Connection Handler when the activity is no longer valid.

sb.removeConnectionHandler(UNIQUE_HANDLER_ID);

These errors are not defined in the js file.

SendBirdException now inherits from the JavaScript Error object.
You can now decide the error parameter order in callback functions using sb.setErrorFirstCallback(True|False).

Now GroupChannelList returns correct readstatus as well.
Member nickname/profile get updated when new messages arrived.
Return more consistent errors when connection() is not made before calling methods.
Now we don't count senders in readreceipt.

Now it supports IE8/9 with some Flash libraries
Fixed a bug regarding disableStateChange/enableStateChange

Fixed a file uploading bug in React Native.
Fixed minor bugs related to null check.

Fixed a bug in calling markAsRead().
Added supports for video/image thumbnail generations and file encryption/access control.

connect()/disconnect() doesn't clear out connection/channel handlers anymore. Instead you should use removeAllConnectionHandlers() and removeAllChannelHandlers().
Fixed a bug in removing ios push tokens.
Now reconnect() method has been added which you can use when you want to manually trigger reconnect logic when network condition gets better.

Added "getMessages" series of methods with timestamp and messageId filter.
Fixed a callback handling bug.

Finally push notifications feature is officially supported in V3 JS SDK.
Added "setBackgroundState()" and "setForegroundState()".
Added "messageType" filter to PreviousMessageQueryList.

InItial connection speed has been improved a lot!.
Auto-Reconnection is now more robust.
Auto-Translation support has been added.

Fixed a bug that created non-integer file size field.

Fixed a reconnection bug happening after calling disconnect() and connect() in serial.
Added "custom_type" field to message/file object.
Added "user_id"/"nickname" filters to GroupChannelList.
Fixed wrong message_id, data field of FileMessage object.

Fixed a Keep-Alive bug now and it should be much faster in React Native/NodeJS.
Now calling "connect()" multiple times in a row triggers "disconnect()" internally to avoid having multiple websocket connections
New License File

Fixed a bug that increases unread message counts even when a user gets its own messages
Clear out old ws object's event handlers after disconnect to prevent a user from getting messages from another user who logged in on the same device.

Minor bugfix for IE, Safari, Opera.

sendFileMessage bugfix.

Added features like filtered user list, open channel keyword search, push preference setting, etc.
messageListQuery bugfix.

npm dependencies bugfix.

NodeJS Keepalive bugfix.
React Native android bugfix.

createPreviousMessageListQuery bugfix.
npm bundle bugfix.

npm release. (only for React Native)

Reconnect bugfix.
getMetaCounters, getMetaData bugfix.

blockUserWithUserId bugfix.

First release.