Chat / JavaScript
Chat JavaScript v4
Chat JavaScript
Chat
JavaScript
Home
/
Chat
/
JavaScript
/
Application
This is the new Docs for Chat SDK v4 for JavaScript. To see the previous Docs, click here.

Authentication

In order to use the features of the Chat SDK for JavaScript in your client apps, a SendbirdChat instance should be initiated in each client app through user authentication with the Sendbird server. The instance communicates and interacts with the server based on the authenticated user account and is allowed to use the Chat SDK's features. This page explains how to authenticate your user with the server.


Initialize the Chat SDK with APP_ID

To use our chat features, you must initialize the SendbirdChat instance by passing APP_ID of your Sendbird application as an argument to a parameter in SendbirdChat.init(). The SendbirdChat.init() method must be called once across your client app. Typically, initialization is implemented in the user login view.

With the implementation of local caching, a new optional parameter named localCacheEnabled has been added to the SendbirdChat.init() method. You can also determine whether to use local cache in SendbirdChatParams and pass it to the init() method.

The localCacheEnabled parameter determines whether the client app will use local storage through Sendbird Chat SDK or not. Since this is optional, the default value is set to false. If you want to build a client app with our local caching functionalities, set the localCacheEnabled parameter to true.

// Initialize the SendbirdChat instance to use APIs in your app.
const params: SendbirdChatParams<[]> = {
    appId: APP_ID,
    localCacheEnabled: true,    // `localCacheEnabled` is optional. The default value is false.
};
const sb: SendbirdChat = SendbirdChat.init(params);

When localCacheEnabled is set to true, different data stores are utilized depending on the app environment. It employs indexedDB in a browser environment while using AsyncStorage in a React Native environment. For those who are using local caching in React Native, put useAsyncStorageStore to the SendbirdChat.init() method as a parameter to set AsyncStorage as the database storage.

import AsyncStorage from '@react-native-async-storage/async-storage';

const params: SendbirdChatParams<[]> = {
    appId: APP_ID,
    localCacheEnabled: true,
    useAsyncStorageStore: AsyncStorage,
};
const sb: SendbirdChat = SendbirdChat.init(params);

Note: If indexedDBstore isn't available in the browser, the Chat SDK will fall back to use the device's memory, not the local cache, even if localCacheEnabled is set to true. When this happens, a warning will show in the logger to notify the situation.

Understanding modules

With the launch of Chat SDK v4.0.0., modules have been introduced to Sendbird Chat SDK to reduce the page loading time and allow users to choose Chat features they would like to import. You can import the @sendbird/chat package first, which adds SendbirdChat and MessageModule. Depending on which chat features you would like to use, you can provide GroupChannelModule or OpenChannelModule from the @sendbird/chat/groupChannel and @sendbird/chat/openChannel packages respectively as a parameter of the SendbirdChat.init() method. You can also set them in SendbirdChatParams and pass it to the init() method.

import SendbirdChat from '@sendbird/chat';
import { GroupChannelModule } from '@sendbird/chat/groupChannel';

const params: SendbirdChatParams<[GroupChannelModule]> = {
    appId: APP_ID,
    modules: [
        new GroupChannelModule(),
    ],
};
const sb: SendbirdChat = SendbirdChat.init(params);

With TypeScript, each module provides a wrapper type of the SendbirdChat instance which allows the module to access GroupChannelModule and OpenChannelModule with sb.groupChannel or sb.openChannel respectively. You can cast the SendbirdChat instance to SendbirdGroupChat or SendbirdOpenChat to access the modules.

const params: SendbirdChatParams<[GroupChannelModule]> = {
    appId: APP_ID,
    modules: [
        new GroupChannelModule(),
    ],
};
const sb: SendbirdChat = SendbirdChat.init(params);

// Only the SendbirdGroupChat type provides a groupChannel module interface.
await sb.groupChannel.createChannel(params);

// MessageModule is built into the SendbirdChat instance on init() so it could be accessed without casting.
await sb.message.getMessage(messageId);

Connect to the Sendbird server with a user ID

By default, the Sendbird server can authenticate a user just by using a unique user ID. Then, the server queries the database to check for a match upon connection request. If no matching user ID is found, the server creates a new user account with the user ID. The ID should be unique within a Sendbird application to be distinguished from others, such as a hashed email address or phone number in your service.

This authentication process is useful when developing a chat service or if your service doesn't require additional security.

If you are using local caching, the connection process will differ depending on the callback. When one of the error codes 400300, 400301, 400302, and 400310 returns, you should clear all user data cached in the local storage and then reconnect to the Sendbird server. Except when these errors occur, the client app can still draw a channel list view and a chat view in the offline mode using locally cached data. The SDK will receive a user object through a callback and try to reconnect later on.

Note: The user object can be passed in a callback only when the client app has succeeded in making the connection with the same user ID in the past. Since the sb.connect() method now requires a callback, use sb.currentUser to fetch the user data. Go to the event handler page to learn more about the usages of the Chat SDK's handlers and callbacks.

const user = await sb.connect(USER_ID);

Note: Apart from initializing the SendbirdChat instance, you should connect to the Sendbird server before calling almost every method through the Chat SDK. If you attempt to call a method without connecting, a CONNECTION_REQUIRED (800101) error would be returned.


Manage connections with the Sendbird server

Unlike the Chat SDKs for iOS and Android, the Chat SDK for JavaScript doesn't manage connections to the Sendbird server when the foreground and background states of your web app changes on different types of devices. In this situation, you should call the connect() or disconnect() methods explicitly depending on how you implement your use cases.

One user ID can make connections to up to 30 devices or browsers simultaneously. All connections from the single user ID are counted and reflected in your application’s concurrent connection number, which is used to calculate your service billing.


Connect to the Sendbird server with a user ID and a token

When a user logs in to a client app using the Chat SDK, you can choose how to authenticate a user. You can authenticate a user with just their unique user ID or also with either an access token or a session token. If any token is issued for a user, it must be provided to the Sendbird server each time the user logs in by using the sb.connect() method.

Using an access token

Through our Chat Platform API, an access token can be generated when creating a user. You can also issue an access token for an existing user. Once an access token is issued, a user is required to provide the access token in the sb.connect() method which is used for logging in.

  1. Using the Chat API, create a Sendbird user account with the information submitted when a user signs up or in to your service.

  2. Save the user ID along with the issued access token to your persistent storage which is securely managed.

  3. When the user attempts to log in to a client app, load the user ID and access token from the storage, and then pass them to the sb.connect() method.

  4. Periodically replacing the user's access token is recommended to protect the account.

Note: From Settings > Application > Security > Access token permission setting in your dashboard, you are able to prevent users without an access token from logging in to your Sendbird application or restrict their access to read and write messages.

const user = await sb.connect(USER_ID, ACCESS_TOKEN);

Using a session token

You can also use a session token instead of an access token to authenticate a user. It's a more secure option because session tokens expire after a certain period whereas access tokens don't. See Chat Platform API guides for further explanation about the difference between access token and session token, how to issue a session token, and how to revoke all session tokens.


Set a session handler

When a user logs in to a client app using the Chat SDK, a user can be authenticated with a session token. If a user is authenticated with a session token, the Chat SDK connects the user to the Sendbird server and can send data requests to it for ten minutes as long as the session token hasn't expired or hasn't been revoked.

Upon the user's session expiration, the Chat SDK will refresh the session internally. However, if the session token has expired or has been revoked, the Chat SDK can't do so. In that case, the client app needs to implement a SessionHandler instance to refresh the token and pass it back to the SDK so that it can refresh the session again.

Note: A SessionHandler instance must be set before the server connection is requested.

The following code shows how to implement the handler.

const sessionHandler = new SessionHandler();
sessionHandler.onSessionTokenRequired = (onSuccess, onError) => {
    // A new session token is required in the SDK to refresh the session.
    // Refresh the session token and pass it onto the SDK through onSuccess(NEW_TOKEN).
    // If you don't want to refresh the session, pass on a null value through onSuccess(null).
    // If any error occurs while refreshing the token, let the SDK know about it through onError().

};
sessionHandler.onSessionClosed = () => {
    // The session refresh has been denied from the app.
    // The client app should guide the user to a login page to log in again.
};
sessionHandler.onSessionRefreshed = () => {
    // OPTIONAL. No action is required.
    // This is called when the session is refreshed.
};
sessionHandler.onSessionError = (err: SendbirdError) => {
    // OPTIONAL. No action is required.
    // This is called when an error occurs during the session refresh.
};
sb.setSessionHandler(sessionHandler);

Disconnect from the Sendbird server

A user can be disconnected from the Sendbird server when they no longer need to receive messages from an online state. However, the user will still receive push notifications for new messages from group channels they've joined.

When disconnected, all types of event handlers in a user's client app registered by sb.groupChannel.addGroupChannelHandler(), sb.openChannel.addOpenChannelHandler, or sb.addConnectionHandler() stop receiving event callbacks from the server. Then, all internally cached data in the client app, such as the channels that are cached when sb.openChannel.getChannel() or sb.groupChannel.getChannel() is called, are also flushed.

Note: By default, most of the data related to users, channels, and messages are internally cached in the SendbirdChat instance of a user's client app, which are retrieved by the corresponding query instances or received through the event handlers.

await sb.disconnect();