JavaScript
Quick Start

Quick Start

Integrate real-time chat in your JavaScript client apps with speed and efficiency. Our JavaScript SDK helps you to focus on the client side implementation of initializing, configuring and building the chat. On the server side, SendBird ensures reliable infra management services with the SDK. This quick start shows a brief overview of the SDK’s structure and features, then goes through the preliminary steps of implementing the SDK in your own project.


Try the sample app

Our sample app has the core features of the SDK. Download the app from our GitHub repository to get an idea of what you can build with the actual SDK and start building in your project.

Download Sample App

Note: The fastest way to see our SDK in action is to build your messaging app on top of our sample app. Make sure to change the application ID of the sample app to your own. Go to the Create a new SendBird application from your dashboard section to learn more.

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 your app

It is simple to implement messaging in your client app with the JavaScript SDK: a user logs in, sees a list of channels, selects or creates a channel, and sends a message to the channel while receiving messages from other users within the channel.

We provide two types of channels: open and group. An open channel is a public channel anyone can participate in and chat with others. A group channel is a private channel that users can join as new members through invitation only, and has numerous distinctive properties and features compared to an open channel. There are a variety of group channel subtypes such as a public group channel working like an open channel.

All sent messages within channels are automatically delivered to channel event handlers registered to your app. While the SendBird instance in your user's client app is connected to SendBird server, the event handlers receive callbacks from the server through onMessageReceived(), onUserJoined(), and other methods. 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 the SDK

If you are ready to integrate chat to your app, follow the step-by-step instructions below.

Step 1: Create a SendBird application from your dashboard

First, create your SendBird application which comprises everything required in a chat service such as users, messages, and channels.

  1. In the SendBird Dashboard, type your email and password to create a new account. You can also sign in with or sign up for a Google or GitHub account.
  2. When prompted by the setup wizard, enter your organization information to manage SendBird applications.
  3. Lastly, when your dashboard home appears after completing setup, click Create App at the top-right corner for a new application. You can also create via the Platform API.

You can only integrate 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 iOS, Android, web, .NET, and Unity client app users 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 using asynchronous methods, your client app must receive success callbacks from SendBird server through callback functions in order to proceed to the next step. A good way to do this is the nesting of methods: Go to Step 4: Enter the channel to learn more about how to 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 being connected, while an existing ID is allowed to log in directly.

Note: Go to the Authentication page to learn more about authenticating with an access token.

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 in the channel.

Note: In a similar fashion, you can create a group channel with inviting 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 send and receive 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);
});