Feature Announcement: Custom Events

Matheus C.
Matheus C.
Published November 25, 2020

Not all chat apps are the same. Some may need interactions other than the regular sending of messages, reactions, typing indicators, etc. Delivery apps, for example, may require a "delivery completed" event. Dating apps, a "match" event. That is why you must use an underlying chat technology that is flexible enough and lets you build custom interactions. Stream Chat is heavily customizable to fit the requirements that make your app unique.

To assist you in making your app stand out, we've built a new feature called custom events, which lets you send and listen to events that are not built initially into Stream Chat.

By default, when sending a custom event, a user must either be a member or a watcher of the channel. When the event is dispatched, all users watching the channel will receive it. Custom events are enabled by default in all channel types. You can change these permissions in the dashboard or via the API.

Make sure to validate your custom events properly via their types and additional fields since malicious users could try to take advantage of them.

Send Custom Event

To send a custom event, you should call the channel.sendEvent method with a type and any additional field you may need.

// sends an event for the current user to all connect clients on the channel
await channel.sendEvent({
    type: "friendship_request",
    text: "Hey there, long time no see!"

Send From Server

To send a custom event from the server, you call the same method (channel.sendEvent), but you also need to include a user field.

// custom events can also be sent server-side, in that case a user must be included in the event payload
await channel.sendEvent({
    type: "friendship_request",
   text: "Hey there, long time no see!",
   user: user,

We're excited to bring yet another feature to help your app stand out from the rest. For more information about this new feature, see the documentation on custom events. If you need help or have specific feedback about this feature, please leave a comment on the documentation page.

decorative lines
Integrating Video with your App?
We've built a Video and Audio solution just for you. Check out our APIs and SDKs.
Learn more ->