Plain JS Introduction

LAST EDIT Oct 07 2024

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 Started

Copied!

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 Client

Copied!

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

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.12.0. 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.

Channels

Copied!

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:

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.

Messages

Copied!

Now that we have the channel set up, let's send our first chat 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.

Events

Copied!

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

You can receive the event and access the full channel state via channel.state.

Conclusion

Copied!

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.