Official JavaScript SDK for Stream Chat

Official JavaScript API client for Stream Chat, a service for building chat applications.
Explore the docs »

Report Bug · Request Feature

📝 About Stream

You can sign up for a Stream account at our Get Started page.

This library can be used by both frontend and backend applications. For frontend, we have frameworks that are based on this library such as the Flutter, React and Angular SDKs. For more information, check out our documentation.

⚙️ Installation

NPM

npm install stream-chat

Yarn

yarn add stream-chat

✨ Getting Started

import { StreamChat } from 'stream-chat';
// or if you are using CommonJS
const { StreamChat } = require('stream-chat');

const client = new StreamChat('API_KEY', 'API_SECRET', {
  disableCache: true, // recommended option for server-side use
  // ...other options like `baseURL`...
});

// create a user
await client.upsertUser({
  id: 'vishal-1',
  name: 'Vishal',
});

// create a channel
const channel = client.channel('messaging', 'test-channel', {
  created_by_id: 'vishal-1',
});
await channel.create();

// send message
const { message } = await channel.sendMessage({ text: 'This is a test message' });

// send reaction
await channel.sendReaction(message.id, { type: 'love', user: { id: 'vishal-1' } });

The StreamChat client is set up to allow extension of the base types through use of module augmentation, custom types will carry through to all client returns and provide code-completion to queries (if supported). To extend Stream's entities with custom data you'll have to create a declaration file and make sure it's loaded by TypeScript, see the list of extendable interfaces and the example bellow using two of the most common ones:

// stream-custom-data.d.ts

import 'stream-chat';

declare module 'stream-chat' {
  interface CustomMessageData {
    custom_property?: number;
  }
  interface CustomUserData {
    profile_picture?: string;
  }
}

// index.ts

// property `profile_picture` is code-completed and expects type `string | undefined`
await client.partialUpdateUser({
  id: 'vishal-1',
  set: { profile_picture: 'https://random.picture/1.jpg' },
});

// property `custom_property` is code-completed and expects type `number | undefined`
const { message } = await channel.sendMessage({
  text: 'This is another test message',
  custom_property: 255,
});

message.custom_property; // in the response object as well

Warning

Generics mechanism has been removed in version 9.0.0 in favour of the module augmentation, please see the release guide on how to migrate.

🔗 (Optional) Development Setup in Combination With Our SDKs

Connect to Stream Chat React Native SDK

Run in the root of this repository:

yarn link

Run in the root of one of the example applications (SampleApp/TypeScriptMessaging) in the stream-chat-react-native repository:

yarn link stream-chat
yarn start

Open metro.config.js file and set value for watchFolders as:

const streamChatRoot = '<PATH TO YOUR PROJECT>/stream-chat-js'

module.exports = {
  // the rest of the metro configuration goes here
  ...
  watchFolders: [projectRoot].concat(alternateRoots).concat([streamChatRoot]),
  resolver: {
    // the other resolver configurations go here
    ...
    extraNodeModules: {
      // the other extra node modules go here
      ...
      'stream-chat': streamChatRoot
    }
  }
};

Make sure to replace <PATH TO YOUR PROJECT> with the correct path for the stream-chat-js folder as per your directory structure.

Run in the root of this repository:

yarn start

📚 More Code Examples

Read up more on Logging and User Token or visit our documentation for more examples.

✍️ Contributing

We welcome code changes that improve this library or fix a problem, please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github. We are very happy to merge your code in the official repository. Make sure to sign our Contributor License Agreement (CLA) first. See our license file for more details.

Head over to CONTRIBUTING.md for some development tips.

🧑‍💻 We Are Hiring!

We've recently closed a $38 million Series B funding round and we keep actively growing. Our APIs are used by more than a billion end-users, and you'll have a chance to make a huge impact on the product within a team of the strongest engineers all over the world.

Check out our current openings and apply via Stream's website.