JavaScript
Quick Start

Quick Start

The SendBird SDKs help you to implement real-time chat to any types of your client apps with speed and efficiency. Our JavaScript SDK provides you with various methods to initialize, configure, and build the chat from the client side - no server side implementation is required because our reliable infra management service is delivered with the SDK. This page presents a brief overview of the SDK’s structure and abilities, then lets you go through the preliminary steps of implementing the SDK in your app.


First, try out the sample app!

Our sample app is a basic representation of the abilites of the SDK. You can download the app from our repository on GitHub and build it in your workplace. The app gives you a simple picture of what you can build with the SDK, although without the many more capabilities of the actual SDK.

Download Sample App

In fact, a simple way to build your messaging app is to do so on top of our sample app. Note that you should change the application ID of the sample app to your own in this case - see the Create a new SendBird application from your dashboard section for reference.

You can also download the sample using a git command like the following:

Light Color Skin
Copy
$ git clone https://github.com/sendbird/SendBird-JavaScript

Run the web sample projects

There are three web sample project: basic sample, live chat sample, and widget sample. To run the sample projects, do the following to use NodeJS for your local server:

  1. Download and install NodeJS if your system doesn't have it yet.
  2. Open a terminal and move to the project path.
Light Color Skin
Copy
$ cd web-basic-sample
  1. Install packages which are used in the sample project.
Light Color Skin
Copy
$ npm install
  1. Run the sample project.
Light Color Skin
Copy
$ npm start

Run the React Native sample project

Our React Native sample project is built on the Redux pattern of React Native. To run the sample, do the following:

  1. Download and install NodeJS if your system doesn't have it yet.
  2. Setup the React Native environment in your system.
  3. Open a terminal and enter the commands below in your project path.
Light Color Skin
Copy
$ cd react-native-redux-sample/ReactNativeWithSendBird
$ npm install
  1. Run the sample app by entering the commands below.
Light Color Skin
Copy
$ react-native run-ios
$ react-native run-android

Before entering two commands above, you should run the simulator from the Android Studio in advance. The command for iOS works without further action.

Supported Browsers

BrowserSupported versions

Internet Explorer

10 or later

Edge

13 or later

Chrome

16 or later

Firefox

11 or later

Safari

7 or later

Opera

12.1 or later

iOS Safari

7 or later

Android Browser

4.4 (Kitkat) or later

XSS (Cross Site Scripting) Prevention

Cross-site scripting (XSS) is a type of computer security vulnerability. XSS helps attackers inject client-side scripts into web pages viewed by other users.

Users can send any types of string data without restriction through SendBird SDKs. Please keep in mind to check safety of received data from other users before rendering it into your DOM.

Note: For more about the XSS prevention, visit the OWASP's XSS Prevention Cheat Sheet page.


How SendBird works with messaging

To build your messaging with the JavaScript SDK is simple: a user connects, sees a list of channels, selects or creates a channel, then sends a message to the channel, and receives messages from all other users within the channel.

We provide two types: an open channel and a group channel. An open channel is a public channel which anyone can easily participate and chat with others. A group channel is basically a private channel which a user can join as a new member through an invitation. Compared with an open channel, it has distinctive abilities of various properties and features. There are a variety of the subtypes of a group channel such as a public group channel working like an open channel.

All sent messages within your SendBird application are automatically delivered to channel event handlers which are registered to your app. As long as the SendBird instance in your user's client app is connected to our server, the event handlers receive callbacks from the server through their onMessageReceived(), onUserJoined() methods, and so on. These callbacks contain message or channel objects, with the latest information of an incoming message or other events related to the objects.


Install and configure JavaScript SDK

Step 1: Create a new SendBird application from your dashboard

A SendBird application comprises everything that goes in a chatting service such as users, messages, and channels. To create a SendBird application, do the following:

  1. In the SendBird Dashboard, type your email and password to create a new account. You can also sign in or sign up with Google or GitHub accounts.
  2. In the Setup wizard that appears, specify information of your organization to manage SendBird applications.
  3. In your dashboard home that appears after completing the setup, click Create App at the top-right corner for a new application (you can also create via the Platform API).

You can implement only one SendBird application per app for your service, regardless of the platforms. All users within your SendBird application can communicate with each other, across all platforms. This means that your users using iOS, Android, web, .NET, and Unity client apps, can all chat with one another without any further setup. Note that all data are limited to the scope of a single application, and users in different SendBird applications can't talk to each other.

Step 2: Install the SDK

Installing the JavaScript SDK is simple if you’re familiar with using external libraries or SDK’s in your projects. You can install the JavaScript SDK with npm or Bower by entering the command below on the command line.

To use npm to install the SDK, Node.js must be first installed on your system.

npm
Bower
Light Color Skin
Copy
$ npm install sendbird
Light Color Skin
Copy
$ bower install sendbird

Or download the latest JavaScript SDK from the following link, copy the SDK to your project classpath (most commonly the libs/ directory), and then include the JavaScript SDK file to your working file.

Download Latest SDK

Light Color Skin
Copy
<script src="lib/SendBird.min.js"></script>

Send your first message

The JavaScript SDK simplifies messaging into an effortless and straightforward process. To send your first message, do the following steps:

Note: The methods in the following steps are all asynchronous, excluding the new SendBird(). This means that when you use the asynchronous methods, make sure that they receive a success callback from SendBird server through their callback functions to proceed to the next step. A good way to do this is the nesting of methods - see the example in the Step 4: Enter the channel below which shows how you can nest the openChannel.enter() in the OpenChannel.getChannel() method.

Step 1: Initialize the SDK

Pass in the App ID of the SendBird application you created earlier in the dashboard to initialize the SDK.

Note: The new SendBird() must be called once across your client web app. We recommend that you initialize the JavaScript SDK at the top of your JavaScript file.

Light Color Skin
Copy
var sb = new SendBird({appId: APP_ID});

Step 2: Connect to SendBird server

Connect a user to SendBird server using their unique user ID. Any untaken user ID is automatically registered as a new user to the SendBird system before connecting, while an existing ID makes the user log in directly.

Note: Authenticating with an access token is discussed in the Authentication section.

Light Color Skin
Copy
sb.connect(USER_ID, function(user, error) {
    if (error) {
        return;
    }
});

Step 3: Create a new open channel

Create an open channel. Once created, all users in your SendBird application can easily participate the channel to converse.

Note: In a similar way, you can create a group channel with inviting any other users as new members to the channel.

Light Color Skin
Copy
sb.OpenChannel.createChannel(function(openChannel, error) {
    if (error) {
        return;
    }
});

Step 4: Enter the channel

Enter the channel to view and send messages.

Light Color Skin
Copy
sb.OpenChannel.getChannel(CHANNEL_URL, function(openChannel, error) {
    if (error) {
        return;
    }

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

Step 5: Send a message to the channel

And finally, send a message to the channel! There are three types: a user message is a plain text, a file message is a binary file, such as an image or PDF, and an admin message is a plain text sent through the dashboard or Platform API for special purpose.

Light Color Skin
Copy
openChannel.sendUserMessage(MESSAGE, DATA, CUSTOM_TYPE, function(message, error) {
    if (error) {
        return;
    }
});

Parameter ordering in callbacks

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

Light Color Skin
Copy
sb.connect(USER_ID, function(user, error) {});

You can configure your SendBird application to change the order by calling the sb.setErrorFirstCallback(true). Once true is set, all callbacks pass the error as the first parameter.

Light Color Skin
Copy
sb.setErrorFirstCallback(true);
sb.connect(USER_ID, function(error, user) {});

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


Use functions of SendBird objects with Immutable-js

If you are using the Immutable-js in your web app, instead of the Immutable.Map(), call the Immutable.fromJS() which converts deeply nested objects to an Immutable Map.

So you can call the functions of SendBird objects because the fromJS() method returns internal objects. But if you use a Map function, you can't call any functions of a SendBird object.

Light Color Skin
Copy
var userIds = ['John', 'Harry']; 

sb.GroupChannel.createChannelWithUserIds(userIds, false, NAME, COVER_URL, DATA, function(groupChannel, error) {
    if (error) {
        return;
    }

    var immutableObject = Immutable.fromJS(groupChannel);
    console.log(immutableObject);
});