Custom Events

LAST EDIT Mar 05 2021

Custom events allow you to build more complex interactions within a channel. Users connected to a channel, either as a watcher or member, can send custom events and have them delivered to all users watching the channel.

1
2
3
4
5
6
7
8
9
10
11
12
// 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!" 
}); 
 
// 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, 
});
1
2
3
4
5
6
7
8
9
// sends an event for the current user to all connect clients on the channel  
await channel.sendEvent(  
    Event(  
      type: 'friendship_request',  
      extraData: {  
        'text': 'Hey there, long time no see!',  
      },  
    ),  
);
Custom events are enabled by default on all channel types, you can disable them using the Dashboard or the API the same way as you would manage other channel features (ie. replies, URL previews, ...)

Permissions

Copied!

Like every client-side API request, sending a custom event includes a permission check. By default users that can read messages on a channel can also send custom events. Check the Auth & Permission section to find out more about how permissions can be customized for your application.

Keep in mind a clever user can send their own custom events. We recommend using the type attribute or custom data on the event to limit the kinds of events that are displayed to the recipient to ones that are safe e.g. if a bad actor sends a "password reset" or other malicious events, your client app should just ignore it.