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

$3

``bash
npm install stream-chat
`

$3

`bash
yarn add stream-chat
`

✨ Getting Started

`ts
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:

`ts
// 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

$3

Run in the root of this repository:

`sh
yarn link
`

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

`sh
yarn link stream-chat
yarn start
`

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

`js
const streamChatRoot = '/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 with the correct path for the stream-chat-js folder as per your directory structure.

Run in the root of this repository:

`sh
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.