Plain JS Introduction

Learn how to build in-app chat with the stream-chat npm package. It is written in vanilla JavaScript and works with any framework or none. This quickstart covers plain JavaScript.

Start here

How the pieces fit together

The stream-chat client manages the connection, local state and API calls for your app, whatever framework it uses. Your backend doesn't render any chat, but it signs the token your app connects with and owns app-level configuration.

flowchart LR
  app[Your app] --> client[stream-chat client]
  client <--> api[Stream API]
  server[Your backend] --> api
  server -. user token .-> client

Build with Stream CLI and Agent Skills

The Stream CLI and Agent Skills give AI coding agents the tools and knowledge to work with Stream. There is no dedicated skill pack for JavaScript yet, but the default skills still help with live documentation and CLI-driven API work.

Install the CLI and the default skills:

curl -fsSL https://getstream.io/cli.sh | bash
getstream skills

Once installed, invoke /stream from your agent. It routes documentation lookups and API operations for you.

Stream Agent Skills can also be installed from skills.sh.

Getting started

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.

Chat client

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

const client = StreamChat.getInstance("{{ 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 }}",
);

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.

Channels

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:

const client = StreamChat.getInstance("{{ 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();

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

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

const text = "I’m mowing the air Rand, I’m mowing the air.";

const response = await channel.sendMessage({
  text,
  customField: "123",
});

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

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

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

What's next

Now that you understand the building blocks of a fully functional chat integration, these are good places to go deeper: