Plain JS Introduction

LAST EDIT Feb 16 2021

JS client is an npm package, which acts as an interface for chat rest APIs, for integrating chat into your application. It makes it easy to communicate with chat APIs e.g., sending a message, connecting to chat, creating channel etc. It's written using vanilla javascript, which makes it framework (vuejs, react, react-native, angular etc) agnostic.

Before reviewing the Chat API docs, we recommend having a look at the tutorials and sample apps.

With Stream Chat you can add a feature rich experience to your app. Leverage our front end components and APIs to build the type of chat you want.

The interactive API tour is the fastest way to learn how Stream’s Chat API works. Be sure to check that out if you haven’t done so already.

Chat API Tour

Getting StartedCopied!

This guide quickly brings you up to speed on Stream’s Chat API. The API is flexible and allows you to build any type of chat or messaging.

You're currently not logged in. Create an account to automatically add your API key and secret to these code examples.

Chat ClientCopied!

Let's get started by initializing the client and setting the current user:

1
2
3
4
5
6
7
8
9
10
11
const client = StreamChat.getInstance("YOUR_API_KEY"); 
// you can still use new StreamChat("api_key"); 
 
await client.connectUser( 
    { 
        id: 'jlahey', 
        name: 'Jim Lahey', 
        image: 'https://i.imgur.com/fR9Jz14.png', 
    }, 
    "CHAT_USER_TOKEN", 
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
String apiKey = "YOUR_API_KEY"; 
String token = "CHAT_USER_TOKEN"; 
Context context = getApplicationContext(); 
ChatClient client = new ChatClient.Builder(apiKey, context).build(); 
 
 
User user = new User(); 
user.setId("jlahey"); 
user.putExtraValue("image", "https://bit.ly/321RmWb"); 
user.putExtraValue("name", "Jim Lahey"); 
 
client.setUser(user, token, new InitConnectionListener() { 
    @Override 
    public void onSuccess(@NotNull ConnectionData data) { 
        final User user = data.getUser(); 
        final String connectionId = data.getConnectionId(); 
 
        Toast.makeText(context, "Logged in successfully as " + user.getExtraValue("name", ""), Toast.LENGTH_SHORT).show(); 
    } 
 
    @Override 
    public void onError(@NotNull ChatError error) { 
        error.getCause().printStackTrace(); 
    } 
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Import StreamChatClient framework. 
import StreamChatClient 
 
// Setup the Stream Chat Client with your API key  
// Preferably in `application(_ application:didFinishLaunchingWithOptions:)` 
// This needs to be called only once, since a singleton cannot be configured multiple times! 
// During development we advice to set log to INFO level 
Client.configureShared(.init(apiKey: "YOUR_API_KEY", logOptions: .info)) 
 
// Create a user, when they login. 
let userExtraData = UserExtraData(name: "Jim Lahey", avatarURL: URL(string: "https://bit.ly/321RmWb")!) 
let user = User(id: "jlahey", extraData: userExtraData) 
 
// Tokens must be generated server-side 
// For development, you can use the token generator (see later in the docs) 
let token = "CHAT_USER_TOKEN" 
 
// Setup the current user with its token 
// You can also pass a tokenProvider closure 
Client.shared.set(user: user, token: token)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
val apiKey = "YOUR_API_KEY" 
val token = "CHAT_USER_TOKEN" 
val context = getApplicationContext() 
val client = ChatClient.Builder(apiKey, context).build() 
 
 
val user = User("jlahey") 
user.extraData["image"] = "https://bit.ly/321RmWb" 
user.extraData["name"] = "Jim Lahey" 
 
client.setUser(user, token, object : InitConnectionListener() { 
    override fun onSuccess(data: ConnectionData) { 
        val user = data.user 
        val connectionId = data.connectionId 
        Toast.makeText(context, "Logged in successfully as ${user.name}", Toast.LENGTH_SHORT).show() 
    } 
 
    override fun onError(error: ChatError) { 
        error.cause?.printStackTrace() 
    } 
})
1
2
3
4
5
6
7
8
9
10
11
12
13
import 'package:stream_chat/stream_chat.dart'; 
 
// create a client with log-level INFO 
final client = Client("YOUR_API_KEY", logLevel: Level.INFO); 
 
// init the user object, note how you can specify custom fields as well 
final user = User(id: "jlahey", extraData: { 
  'name': 'Jim Lahey', 
  'image': 'https://i.imgur.com/fR9Jz14.png', 
}); 
 
// sets the current user, from now on the client can be used to query channels and receive events 
await client.setUser(user, "CHAT_USER_TOKEN");

The above snippet is for an in-browser or mobile integration. Server-side API calls are a little different, but this is covered in detail later in the documentation.

Please also note here the usage of StreamChat.getInstance() available since stream-chat-js@2.1.2. This new Singleton pattern allows you to instantiate a unique StreamChat client, i.e create a StreamChat instance and retrieve it wherever you need it on your app to perform API calls. After calling it once, any following getInstance() call will return the initial StreamChat instance. This should prevent from accidentally creating multiple StreamChat instances.

This new Chat client version is backward compatible. That means users can continue using new StreamChat() if they use an older version of the library or for any other reason.

ChannelsCopied!

Let’s continue by initializing your first channel. A channel contains messages, a list of people that are watching the channel, and optionally a list of members (for private conversations). The example below shows how to set up a channel to support chat for a group conversation:

1
2
3
4
5
6
7
const client = StreamChat.getInstance("YOUR_API_KEY"); 
const channel = client.channel('messaging', 'travel', { 
    name: 'Awesome channel about traveling', 
}); 
 
// fetch the channel state, subscribe to future updates 
const state = await channel.watch();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
ChannelClient channelClient = client.channel("messaging", "travel"); 
HashMap extraData = new HashMap<String, Object>(); 
extraData.put("name", "Awesome channel about traveling"); 
 
// Watching a channel"s state 
QueryChannelRequest request = new QueryChannelRequest() 
        .withData(extraData) 
        .withMessages(20) 
        .withWatch(); // Ensures that we are watching the channel for any changes/new messages 
 
channelClient.query(request).enqueue(new Call.Callback<Channel>() { 
    @Override 
    public void onResult(@NotNull Result<Channel> result) { 
        if (result.isSuccess()) { 
            Channel channel = result.data(); 
            // Use channel 
        } else { 
            result.error().getCause().printStackTrace(); 
        } 
    } 
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Create an extra data for a channel. 
// ChannelExtraDataCodable is an extension of Codable that makes sure you have common fields  
// used by the UI library (name and imageURL) 
struct MyChannelData: ChannelExtraDataCodable { 
    var name: String? 
    var imageURL: URL? 
    let info: String // this is our custom field :) 
} 
 
// Register once your channel extra data type, we'll need it for decoding 
Channel.extraDataType = MyChannelData.self 
 
let data = MyChannelData(name: "Travel", imageURL: nil, info: "Awesome channel about traveling") 
let channel = Client.shared.channel(type: .messaging, id: "travel", extraData: data) 
 
// Watching a channel 
channel.watch { (result) in 
    // handle result 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
val channelClient: ChannelClient = client.channel( 
        channelType = "messaging", 
        channelId = "travel" 
) 
val extraData = mutableMapOf<String, Any>( 
        "name" to "Awesome channel about traveling" 
) 
 
// Watching a channel"s state 
val request = QueryChannelRequest() 
        .withData(extraData) 
        .withMessages(limit = 20) 
        .withWatch() // Ensures that we are watching the channel for any changes/new messages 
 
channelClient.query(request).enqueue { result -> 
    if (result.isSuccess) { 
        val channel: Channel = result.data() 
        // Use channel 
    } else { 
        result.error().cause?.printStackTrace() 
    } 
}
1
2
3
4
5
6
final channel = client.channel("messaging", id: "travel", extraData: { 
  "name": "Awesome channel about traveling", 
}); 
 
// fetch the channel state and subscribe to future updates 
final state = await channel.watch();

The first two arguments are the Channel Type and the Channel ID (messaging and travel in this case). The Channel ID is optional; if you leave it out, the ID is determined based on the list of members. The channel type controls the settings we’re using for this channel.

There are 5 default types of channels:

  • livestream
  • messaging
  • team
  • gaming
  • commerce

These five options above provide you with the most sensible defaults for those use cases. You can also define custom channel types if Stream Chat defaults don’t work for your use-case.

The third argument is an object containing the channel data. You can add as many custom fields as you would like as long as the total size of the object is less than 5KB.

MessagesCopied!

Now that we have the channel set up, let's send our first chat message:

1
2
3
4
5
6
const text = 'I’m mowing the air Rand, I’m mowing the air.'; 
 
const response = await channel.sendMessage({ 
    text, 
    customField: '123', 
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Message message = new Message(); 
message.setText("I’m mowing the air Rand, I’m mowing the air."); 
message.putExtraValue("customField", "123"); 
 
channelClient.sendMessage(message).enqueue(new Call.Callback<Message>() { 
    @Override 
    public void onResult(@NotNull Result<Message> result) { 
        if (result.isSuccess()) { 
            Message message = result.data(); 
        } else { 
            result.error().getCause().printStackTrace(); 
        } 
    } 
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
let channelExtraData = ChannelExtraData(name: "General", imageURL: nil) 
let channel = Client.shared.channel(type: .messaging, id: "general", extraData: channelExtraData) 
 
// Create a message 
let message = Message(text: "Hello") 
 
// Send the message 
channel.send(message: message) { result in 
    do { 
        let response = try result.get() 
	      print(response) 
    } catch { 
        print("Error when sending message: \(error)") 
    } 
}
1
2
3
4
5
6
7
8
9
10
11
12
val message = Message(text = "I’m mowing the air Rand, I’m mowing the air.") 
message.extraData["customField"] = "123" 
 
channelClient.sendMessage(message).enqueue(object : Call.Callback<Message> { 
    override fun onResult(result: Result<Message>) { 
        if (result.isSuccess) { 
            val message = result.data() 
        } else { 
            result.error().cause?.printStackTrace() 
        } 
    } 
})
1
2
3
4
5
6
final message = Message( 
  text: 'I’m mowing the air Rand, I’m mowing the air.', 
  extraData: {'customField': '123'}, 
); 
 
final response = await channel.sendMessage(message);

Similar to users and channels, the sendMessage method allows you to add custom fields. When you send a message to a channel, Stream Chat automatically broadcasts to all the people that are watching this channel and updates in real-time.

EventsCopied!

This is how you can listen to events on the clients-side:

1
2
3
4
channel.on('message.new', event => { 
    console.log('received a new message', event.message.text); 
    console.log(`Now have ${channel.state.messages.length} stored in local state`); 
});
1
2
3
4
5
6
7
8
9
final Disposable disposable = client.subscribe((event) -> { 
    if (event instanceof NewMessageEvent) { 
        Message message = ((NewMessageEvent) event).getMessage(); 
    } 
    return Unit.INSTANCE; 
}); 
 
// Dispose to stop receiving events 
disposable.dispose();
1
2
3
4
5
6
7
8
let channel = Client.shared.channel(type: .messaging, id: "general") 
 
let subscription = channel.subscribe(forEvents: [.messageNew]) { event in 
	// handle new message event 
} 
 
// Cancel subscription when you want to stop receiving events 
subscription.cancel()
1
2
3
4
5
6
7
val disposable = client.subscribe { event: ChatEvent -> 
    if (event is NewMessageEvent) { 
        val message = event.message 
    } 
} 
// Dispose to stop receiving events 
disposable.dispose()
1
2
3
channel.on("message.new").listen((Event event) { 
  print("received a new message: ${event.message.text}"); 
};
You can receive the event and access the full channel state via channel.state.

ConclusionCopied!

Now that you understand the building blocks of a fully functional chat integration, let’s move on to the next sections of the documentation, where we dive deeper into details on each API endpoint.