Android
Event Handler

Event Handler

SendBird Chat SDK for Android provides three types of event handlers for various events on client apps: channel event handler, user event handler, and connection event handler. Through the channel event handler and user event handler, SendBird server notifies client apps of events that happen on the channels and users of your app. In cases where the client app gets disconnected from the server and tries to reconnect at the SDK level, the server notifies the client app through the connection event handler.

Using the event callbacks provided by two types of handlers, you can write the event-related processing code you want to execute. For example, the onMessageReceived() method of the channel event handler in client apps is called when a message has been received in a channel. This callback receives BaseChannel and BaseMessage objects which contain new information on the channel and message as parameters.

The Chat SDKs interact with our server through persistent WebSocket connections and multi-thread processing, and receives callbacks of asynchronous events which happen on the channels, users, and reconnect process of client apps in real-time through the handlers. This allows you to track the events and implement your own chat features associated with them.


Add and remove a channel event handler

To receive and retrieve information about certain events happening in the channels from SendBird server, you need to add a channel event handler with its unique user-defined ID by calling the SendBird.addChannelHandler(). If you want to keep informed of changes related to the channels and notify other users' client apps of those changes, define and register multiple channel event handlers to each Activity instance.

Supported event callbacks for open channels
MethodInvoked whenNotified devices

onMessageReceived()

A message has been received in an open channel.

All devices where client apps with the channel are in the foreground, except the device that sent the message.

onMessageUpdated()

A message has been updated in an open channel.

All devices where client apps with the channel are in the foreground, except the device where the message was updated.

onMessageDeleted()

A message has been deleted in an open channel.

All devices where client apps with the channel are in the foreground, including the device where the message was deleted.

onMentionReceived()

A user has been mentioned in a message sent in an open channel.

All devices of mentioned users (up to 10) in the channel, including the device that was used to mention other users.

onChannelChanged()

One of the following open channel properties has been changed: name, cover image, data, custom type, or operators.

All devices that are connected to the changed channel, including the device where the channel was changed.

onChannelDeleted()

An open channel has been deleted.

All devices where client apps with the channel are in the foreground, including the device where the channel was deleted.

onChannelFrozen()

An open channel has got frozen.

All devices where client apps with the channel are in the foreground, including the device where the channel got frozen.

onChannelUnfrozen()

An open channel has got unfrozen.

All devices where client apps with the channel are in the foreground, including the device where the channel got unfrozen.

onMetaDataCreated()

A metadata for an open channel has been created.

All devices where client apps with the channel are in the foreground, including the device where the metadata was created.

onMetaDataUpdated()

A metadata for an open channel has been updated.

All devices where client apps with the channel are in the foreground, including the device where the metadata was updated.

onMetaDataDeleted()

A metadata for an open channel has been deleted.

All devices where client apps with the channel are in the foreground, including the device where the metadata was deleted.

onMetaCounterCreated()

A metacounter for an open channel has been created.

All devices where client apps with the channel are in the foreground, including the device where the metacounter was created.

onMetaCounterUpdated()

A metacounter for an open channel has been updated.

All devices where client apps with the channel are in the foreground, including the device where the metacounter was updated.

onMetaCounterDeleted()

A metacounter for an open channel has been deleted.

All devices where client apps with the channel are in the foreground, including the device where the metacounter was deleted.

onUserEntered()

A user has entered an open channel.

All devices where client apps with the channel are in the foreground, including the device that the user entered that channel.

onUserExited()

A user has exited an open channel.

All devices where client apps with the channel are in the foreground, except the device that the user exited that channel.

onUserMuted()

A user has been muted in an open channel.

All devices where client apps with the channel are in the foreground, including the device where the user was muted.

onUserUnmuted()

A user has been unmuted in an open channel.

All devices where client apps with the channel are in the foreground, including the device where the user was unmuted.

onUserBanned()

A user has been banned from an open channel.

All devices where client apps with the channel are in the foreground, including the device where the user was banned.

onUserUnbanned()

A user has been unbanned from an open channel.

All devices where client apps with the channel are in the foreground, including the device where the user was unbanned.

Supported event callbacks for group channels
MethodInvoked whenNotified devices

onMessageReceived()

A message has been received in a group channel.

All devices where client apps with the channel are in the foreground, except the device that sent the message.

onMessageUpdated()

A message has been updated in a group channel.

All devices where client apps with the channel are in the foreground, except the device where the message was updated.

onMessageDeleted()

A message has been deleted in a group channel.

All devices where client apps with the channel are in the foreground, including the device where the message was deleted.

onMentionReceived()

A user has been mentioned in a message sent in a group channel.

All devices of mentioned users (up to 10) in the channel, except the device that was used to mention other users.

onReactionUpdated()

A message reaction has been updated in a group channel.

All devices where client apps with the channel are in the foreground, including the device that reacted to the message.

onChannelChanged()

One of the following group channel properties has been changed: distinct, push notification preferences, last message (except when the silent admin message), unread message count, name, cover image, data, or custom type.

All devices that are connected to the changed channel, including the device where the channel was changed.

onChannelDeleted()

A group channel has been deleted.

All devices where client apps with the channel are in the foreground, including the device where the channel was deleted.

onChannelFrozen()

A group channel has got frozen.

All devices where client apps with the channel are in the foreground, including the device where the channel got frozen.

onChannelUnfrozen()

A group channel has got unfrozen.

All devices where client apps with the channel are in the foreground, including the device where the channel got unfrozen.

onMetaDataCreated()

A metadata for a group channel has been created.

All devices where client apps with the channel are in the foreground, including the device where the metadata was created.

onMetaDataUpdated()

A metadata for a group channel has been updated.

All devices where client apps with the channel are in the foreground, including the device where the metadata was updated.

onMetaDataDeleted()

A metadata for a group channel has been deleted.

All devices where client apps with the channel are in the foreground, including the device where the metadata was deleted.

onMetaCounterCreated()

A metacounter for a group channel has been created.

All devices where client apps with the channel are in the foreground, including the device where the metacounter was created.

onMetaCounterUpdated()

A metacounter for a group channel has been updated.

All devices where client apps with the channel are in the foreground, including the device where the metacounter was updated.

onMetaCounterDeleted()

A metacounter for a group channel has been deleted.

All devices where client apps with the channel are in the foreground, including the device where the metacounter was deleted.

onChannelHidden()

A group channel has been hidden from the list.

All devices of a user who hided the channel.

onUserReceivedInvitation()

A user has been invited to a group channel.

All devices where client apps with the channel are in the foreground, including the device of a user who received an invitation.

onUserDeclinedInvitation()

A user has declined an invitation to a group channel.

All devices where client apps with the channel are in the foreground, including the device of a user who declined an invitation.

onUserJoined()

A user has joined a group channel.

All devices where client apps with the channel are in the foreground, including all devices of the user who joined the channel, and except the devices of users who haven't accepted invitations.

onUserLeft()

A user has left a group channel.

All devices where client apps with the channel are in the foreground, including all devices of the user who left the channel, and except the devices of users who haven't accepted invitations.

onReadReceiptUpdated()

A user has read a specific unread message in a group channel.

All devices where client apps with the channel are in the foreground, including all devices of the users who are invited to the channel, and except the device of the user who read the unread message.

onTypingStatusUpdated()

A user starts typing a message to a group channel.

All devices where client apps with the channel are in the foreground, except the devices of the users who are invited to the channel, and except all devices of the user who typed a message.

onUserMuted()

A user has been muted in a group channel.

All devices where client apps with the channel are in the foreground, including the device where the user was muted.

onUserUnmuted()

A user has been unmuted in a group channel.

All devices where client apps with the channel are in the foreground, including the device where the user was unmuted.

onUserBanned()

A user has been banned from a group channel.

All devices where client apps with the channel are in the foreground, including the device where the user was banned.

onUserUnbanned()

A user has been unbanned from a group channel.

All devices where client apps with the channel are in the foreground, including the device where the user was unbanned.

The following code shows a full set of supported event callbacks with their parameters and how to add a channel event handler to the unique SendBird instance.

Light Color Skin
Copy
SendBird.addChannelHandler(UNIQUE_HANDLER_ID, new SendBird.ChannelHandler() {
    
    @Override
    public void onMessageReceived(BaseChannel baseChannel, BaseMessage baseMessage) {
    }

    @Override
    public void onMessageUpdated(BaseChannel baseChannel, BaseMessage baseMessage) {
    }
    
    @Override
    public void onMessageDeleted(BaseChannel baseChannel, long messageId) {
    }

    @Override
    public void onMentionReceived(BaseChannel baseChannel, BaseMessage baseMessage) {
    }

    @Override
    public void onReactionUpdated(BaseChannel baseChannel, ReactionEvent reactionEvent) {
    }
    
    @Override
    public void onChannelChanged(BaseChannel baseChannel) {
    }

    @Override
    public void onChannelDeleted(String channelUrl, BaseChannel.ChannelType channelType) {
    }

    @Override
    public void onChannelFrozen(BaseChannel baseChannel) {
    }
  
    @Override
    public void onChannelUnfrozen(BaseChannel baseChannel) {
    }

    @Override
    public void onMetaDataCreated(BaseChannel baseChannel, Map map) {
    }

    @Override
    public void onMetaDataUpdated(BaseChannel baseChannel, Map map) {
    }

    @Override
    public void onMetaDataDeleted(BaseChannel baseChannel, List<String> keys) {
    }

    @Override
    public void onMetaCouterCreated(BaseChannel baseChannel, Map map) {
    }

    @Override
    public void onMetaCounterUpdated(BaseChannel baseChannel, Map map) {
    }

    @Override
    public void onMetaCounterDeleted(BaseChannel baseChannel, List<String> keys) {
    }

    @Override
    public void onChannelHidden(GroupChannel groupChannel) {
    }
 
    @Override
    public void onUserReceivedInvitation(GroupChannel groupChannel, User inviter, List<User> invitees) {
    }

    @Override
    public void onUserDeclinedInvitation(GroupChannel groupChannel, User inviter, User invitee) {
    }

    @Override
    public void onUserJoined(GroupChannel groupChannel, User user) {
    }

    @Override
    public void onUserLeft(GroupChannel groupChannel, User user) {
    }

    @Override
    public void onReadReceiptUpdated(GroupChannel groupChannel) {
    }

    @Override
    public void onTypingStatusUpdated(GroupChannel groupChannel) {
    }

    @Override
    public void onUserEntered(OpenChannel openChannel, User user) {
    }

    @Override
    public void onUserExited(OpenChannel openChannel, User user) {
    }

    @Override
    public void onUserMuted(BaseChannel baseChannel, User user) {
    }

    @Override
    public void onUserUnmuted(BaseChannel baseChannel, User user) {
    }

    @Override
    public void onUserBanned(BaseChannel baseChannel, User user) {
    }

    @Override
    public void onUserUnbanned(BaseChannel baseChannel, User user) {
    }

});

The following code shows how to remove the channel event handler.

Light Color Skin
Copy
SendBird.removeChannelHandler(UNIQUE_HANDLER_ID);

Add and remove a user event handler

To receive information about events related to users connected to SendBird server, you need to add a user event handler with its unique user-defined ID by calling the SendBird.addUserEventHandler(). If you want to keep informed of changes related to the users, define and register multiple user event handlers to each Activity instance.

Supported event callbacks
MethodInvoked whenNotified devices

onFriendsDiscovered()

A user has uploaded other users' unique keys to SendBird server for discovering friends and then the server identifies and matches the corresponding users based on the uploaded keys.

All devices of the corresponding users, including the device where the unique keys were uploaded.

onTotalUnreadMessageCountChanged()

A user has read messages in the joined group channels and there is an update on the total number of the user's unread messages.

The user's devices with running client apps. The devices will be notified with the total number of unread messages along with a collection of the number of unread messages by custom channel type.

The following code shows a full set of supported event callbacks with their parameters and how to add a user event handler to the unique SendBird instance.

Light Color Skin
Copy
SendBird.addUserEventHandler(UNIQUE_HANDLER_ID, new SendBird.UserEventHandler() {
    
    @Override
    public void onFriendsDiscovered(List<User> users) {
    }
    
    @Override
    public void onTotalUnreadMessageCountChanged(int totalCount, Map<String, Integer> totalCountByCustomType) {
    }
});

The following code shows how to remove the user event handler.

Light Color Skin
Copy
SendBird.removeUserEventHandler(UNIQUE_HANDLER_ID);

Add and remove a connection event handler

To detect changes in the connection status of a client app, you need to add a connection event handler with its unique user-defined ID by calling the SendBird.addConnectionHandler(). If you want to keep informed of changes related to the SendBird server connection, define and register multiple connection event handlers to each Activity instance.

Supported event callbacks
MethodInvoked whenNotified devices

onReconnectStarted()

SDK has started reconnecting to SendBird server.

The device where reconnect() was automatically called by the Chat SDK, or manually by the client app.

onReconnectSucceeded()

SDK has succeeded in reconnecting to SendBird server.

The device that successfully reconnected to the server.

onReconnectFailed()

SDK has failed to reconnect to SendBird server.

The device that failed to reconnect to the server.

The following code shows a full set of supported event callbacks and how to add a connection event handler to the unique SendBird instance.

Light Color Skin
Copy
SendBird.addConnectionHandler(UNIQUE_HANDLER_ID, new SendBird.ConnectionHandler() {
    
    @Override
    public void onReconnectStarted() {
    }

    @Override
    public void onReconnectSucceeded() {
    }

    @Override
    public void onReconnectFailed() {
    }

});

The following code shows how to remove the connection event handler.

Light Color Skin
Copy
SendBird.removeConnectionHandler(UNIQUE_HANDLER_ID);