Events

Events allow the client to stay up to date with changes to the chat. For example, you get events when a new message was sent, a user's image was updated, a reaction was added, or a member joined the channel. Events are only received when the client is connected to the socket and the application is in the foreground.

Listening for Channel Events

As soon as you call ChannelClient::watch or ChatClient::queryChannels you’ll start to listen to these events. You can hook into specific events:

val channelClient = client.channel("messaging", "channelId") 
 
// Subscribe for new message events 
val disposable: Disposable = channelClient.subscribeFor<NewMessageEvent> { newMessageEvent -> 
    val message = newMessageEvent.message 
} 
 
// Dispose when you want to stop receiving events 
disposable.dispose()

You can also listen to all events at once:

val disposable: Disposable = channelClient.subscribe { event: ChatEvent -> 
    when (event) { 
        // Check for specific event types 
        is NewMessageEvent -> { 
            val message = event.message 
        } 
    } 
} 
 
// Dispose when you want to stop receiving events 
disposable.dispose()

Listening for Client Events

Not all events are specific to channels. Events such as the user's status has changed, the users' unread count has changed, and other notifications are sent as client events. These events can be listened to through the client directly:

// Subscribe for User presence events 
client.subscribeFor<UserPresenceChangedEvent> { event -> 
    // Handle change 
} 
 
// Subscribe for just the first ConnectedEvent 
client.subscribeForSingle<ConnectedEvent> { event -> 
    // Use event data 
    val unreadCount = event.me.totalUnreadCount 
    val unreadChannels = event.me.unreadChannels 
}

Listening for Connection Events

The official SDKs make sure that a connection to Stream is kept alive at all times and that chat state is recovered when the user's internet connection comes back online. Your application can subscribe to changes to the connection using client events.

client.subscribeFor( 
    ConnectedEvent::class, 
    ConnectingEvent::class, 
    DisconnectedEvent::class, 
) { event -> 
    when (event) { 
        is ConnectedEvent -> { 
            // Socket is connected 
        } 
        is ConnectingEvent -> { 
            // Socket is connecting 
        } 
        is DisconnectedEvent -> { 
            // Socket is disconnected 
        } 
    } 
}

Stop Listening for Events

It is a good practice to un-register event handlers once they are not in use anymore. Doing so will save you from performance degradations coming from memory leaks or even from errors and exceptions (for example null pointer exceptions)

val disposable: Disposable = client.subscribe { /* ... */ } 
disposable.dispose()

Custom events

Custom events allow you to build more complex interactions within a channel or with a user. 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.

You can send a custom event using the ChannelClient::sendEvent call:

val channelClient = client.channel("messaging", "general")

// Send a custom event to all users watching the channel
channelClient.sendEvent(
    eventType = "friendship_request",
    extraData = mapOf("text" to "Hey there, long time no see!")
).enqueue { result ->
    if (result.isSuccess) {
        val chatEvent: ChatEvent = result.data()
    } else {
        // Handle result.error()
    }
}

note

Custom events are enabled by default on all channel types. You can disable them using the Dashboard or the API.

You can listen to custom events by subscribing for UnknownEvent:

val channelClient = client.channel("messaging", "channelId") 
 
// Subscribe for custom events 
val disposable: Disposable = channelClient.subscribeFor<UnknownEvent> { customEvent ->
    val text = customEvent.rawData["text"]
} 
 
// Dispose when you want to stop receiving events 
disposable.dispose()