Quick Start

SendBird helps you to implement real-time chat to any application 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 required because our reliable infra management service is delivered with the SDK. This section presents a brief overview of the SDK’s functionalities and logic, then let you go through the preliminary steps of implementing SendBird in your own application


First, try out the sample app!

Our sample app is a fully functional messaging app. Download and build the sample from GitHub to chat freely with other people. The app gives you a picture of what you can build using SendBird, although it is by no means the limit of its capabilities.

The sample app is a useful reference when developing your own project using SendBird. In fact, a simple way to implement chat is to build your app on top of the sample. Note that you must change the App ID to your own in this case - reference to the Create a new SendBird application from our dashboard section.

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

$ git clone https://github.com/smilefam/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 you don't have it installed in your system.
  2. Open a terminal and move to project path.
    $ cd web-basic-sample
  3. Install package which use in sample project.
    $ npm install
  4. Run the sample project.
    $ npm start

Run the React Native sample project

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

  1. Download and install node and npm.
  2. Setup the React Native environment in your system.
  3. Open a terminal and enter the commands below in your project path.
    $ cd react-native-redux-sample/ReactNativeWithSendBird
    $ npm install
  4. Run the sample app by entering the commands below.
    $ react-native run-ios
    $ react-native run-android

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

Supported Browsers

Brower Supported 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 type of string data without restriction through SendBird. 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 a messaging with the SendBird SDK is simple: a user connects, enters a channel, send a message to the channel, and receives the messages from all other users within the channel. There are two types of channels: Open and Group Channel. Open Channel is a public channel which anyone can enter and chat freely. Group Channel is basically a private channel that a user can join as a new member through an invitation. But it has various properties for its functionalities, so you can make a public group channel working like Open Channel.

When using the SDK, messages are automatically delivered to channel event handler. As long as an app instance is connected to our server, it receives callbacks to onMessageReceived(), onUserJoined(), and so on, with the message or channel objects containing the latest information, in case of a message incoming or other relevant events happened.


Install and configure Android SDK

Step 1: Create a new SendBird application from our dashboard

A SendBird application comprises everything that goes in a chatting service such as users, messages, and channels. Create a new SendBird application by singing in to our dashboard. Either that, you can sign up with Google, GitHub, or create a new account with the dashboard.

Once you create an application, all users within can communicate with each other, across all platforms. This means users using iOS, Android, and web clients can all chat with one another without any additional setup. However, all data is limited to the scope of one application, meaning users in different SendBird applications cannot 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 install sendbird
$ bower install sendbird

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

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

Send your first message

The JavaScript SDK abstracts messaging into a simple and straightforward process. To send your first message, do the following steps:

Note: The following methods, excluding new SendBird(), are asynchronous. This means you must ensure that you've received a success callback to proceed to the next step. A simple way to do this is the nest methods - see the example in Step 4: Enter the channel when openChannel.enter() is called after receiving an OpenChannel.getChannel() callback.

Step 1: Initialize the SDK

Initialization binds the SDK to Android’s context, thereby allowing it to respond to connection and state changes. Pass in the App ID of the SendBird application you created earlier in our dashboard to initialize the SDK.

Note: The new SendBird() should be called once across a web app. We recommend that you perform the SDK initialization at the top of your JavaScript file.

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

Step 2: Connect to SendBird server

Connect a user to a SendBird server using their User ID. Any untaken user ID creates a new user in the SendBird application before connecting, while an existing ID makes the user log in directly. Authentication with Access Tokens are discussed in the Authentication section.

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 the SendBird application can freely enter the channel to converse.

Note: A group channel can be created in a similar manner. However, to have other users join the channel, an existing member of the channel (for example, the creator) must invite them first.

sb.OpenChannel.createChannel(function(openChannel, error) {
    if (error) {
        return;
    }
});

Step 4: Enter the channel

Enter the channel to view and send messages.

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 of messages: a User Message is a plain text message, a File Message is a binary file, such as an image or PDF, and an Admin Message is a special type of message sent through our dashboard or Platform API.

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, connect() below returns parameters in (user, error) order.

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

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

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

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


Use functions of SendBird object with Immutable-js

If you're using Immutable-js in your products, instead of Immutable.Map(), use Immutable.fromJS() which converts deeply nested objects to an Immutable Map.
You can call functions in the SendBird object, Because fromJS() returns internal objects. But if you use Map function, you can't call SendBird function.

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);
});