Instant Messaging
Getting Started
Account Integration and Login
Multi-device Login
Group Chat
Chat Room
Chat Room Tags
Statistics Monitoring
Interface Overview
Integrate and Initialize SDK
Basic Messaging
Message History
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
Chat Room
Chat Extension
Miscellaneous Features
Best Practice
Traffic Control in Chat Rooms
API Reference
Status Codes

Online Status Subscription

Update time: 2021/12/03 15:12:00


Users may implement the design mode programming method of "Publish-Subscribe" by publishing and subscribing events. This can be used to subscribe to the online status of specified users, users' personalized information.
At present, only the "type = 1" event subscription is available. Users may define the value (a value corresponds to the status of an event; 1-9999 is the value pre-defined by CommsEase, which the developer cannot use) as required for their business.
Rough process: A subscribes B ——> B publishes a specific event ——> A monitors any change in the event status from B ——> handle it based on the business logic analysis.
Note: it is not required to actively publish the online status event (type=1, value=1/2/3) in CommsEase system. The work will be hosted to CommsEase server.

Subscribing to events

Specific events are subscribed by specific users. It is required to subscribe built-in online status event or custom event using the interface. The maximum number of effective subscription accounts cannot exceed 3000. We recommend keeping consistent subscription duration at each client by the developer, because multi-client subscription (subscription of the same account in other types of client) will cover the validity period of subscription. In addition, it is noted that target event is not published for the same event subscription in the same account within 30 seconds in consideration of performance, even it is set as "immediate synchronization service".

  • API prototype
* Subscription events.
* @param request - Information of subscription request. The event type, account of event publisher and period of validity of subscription must be filled in.
* @return InvocationFuture - Configurable callback feature. It will be invoked only after request. The set of accounts with failed subscription will be returned. If the array length is 0, all are successful. If an error occurs, detailed error code will be returned.
InvocationFuture<List<String>> subscribeEvent(EventSubscribeRequest request);
  • Parameters

EventSubscribeRequest attribute

Parameter Description
eventType Event type. Only 1 is input.
expiry Validity period of subscription, ranging from 60 seconds to 30 days. Unit: seconds.
syncCurrentValue Determine that event state value is synchronized immediately after subscription. It is "false" by default.
publishers Account set of event publisher.

For subscription events, fields like eventType, expiry, publishers must be filled in a subscription request.

  • Example
NIMClient.getService(EventSubscribeService.class).subscribeEvent(eventSubscribeRequest).setCallback(new RequestCallbackWrapper<List<String>>() {
    public void onResult(int code, List<String> result, Throwable exception) {
        if (code == ResponseCode.RES_SUCCESS) {
            if (result != null) {
                // Some accounts with failed subscription.
        } else {


Unsubscribing from events

Unsubscribing from events by accounts

Users can unsubscribe from any specified type of event for a specified account. Fields eventType and publishers are required in the subscription request.

  • API prototype
 * Cancel subscription relationship of specified event by account.
 * @param request - Cancel subscription. Only the event type and the set of accounts of event publishers (set of publishers) must be filled in.
 * @return InvocationFuture - Configurable callback features. It will be invoked only after request. The set of accounts with failed operation in canceling subscription will be returned. If the array length is 0, all are successful. If an error occurs, detailed error codes will be returned.
InvocationFuture<List<String>> unSubscribeEvent(EventSubscribeRequest request);
  • Example

Unsubscribing from events by events

Unsubscribe from specified events.

  • API prototype
 * Cancel all subscriptions of specified events.
 * @param request - Cancel subscription. Only the event type must be filled in.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only after request. If an error occurs, detailed error code will be returned.
InvocationFuture<Void> batchUnSubscribeEvent(EventSubscribeRequest request);
  • Example

Publishing events

Publish an event to subscribers. If built-in online status of CommsEase system cannot accommodate application demands or the developer requires some independent custom events, event can be published using the interface.

  • API prototype
 * Publish an event.
 * @param event - Event
 * @return InvocationFuture - Configurable callback feature. It can be invoked only after request. If an error occurs, detailed error codes will be returned.
InvocationFuture<Event> publishEvent(Event event);

When event is published, Event object must be created independently and required fields include:

  • eventType: Input 1.
  • eventValue: value is 10000 and above (1-9999 are the values pre-defined by CommsEase and cannot be used by developers).

Event interfaces:

Return Event interface Description
void setEventType(int eventType) Set event type for publishing event.
void setEventValue(int eventValue) Set event value for publishing event.
void setConfig(String config) Set extension field of event. It is configured when an event is published at client.
void setBroadcastOnlineOnly(boolean only) Broadcast to online subscribers only after event publication.
void setExpiry(long expiry) Set validity period of event. Unit: second. Range: 60 seconds to 7days.
void setSyncSelfEnable(boolean syncSelfEnable) Set that events supports multi-client synchronization.
int getEventType() Get event type.
int getEventValue() Get event value.
String getConfig() Get the extension field of event.
long getExpiry() Get expiry date of event.
boolean isBroadcastOnlineOnly() Determine that event is broadcast to online subscribers only.
String getPublisherAccount() Get event publisher.
int getPublisherClientType() Get client type for event publication (See ClientType).
long getPublishTime() Get event publishing time.
String getConfigByClient(int client) Get event extension information published at a certain type of client.
String getNimConfig() Get configuration information in reserved event, filled in from the server.



Listening from subscribed events

The subscribed events are monitored using EventSubscribeServiceObserver interface. Developers must keep the monitoring life cycle consistent with Application.

  • API prototype
 * Listen changes of event status.
 * @param observer - Observer. The parameter is the latest event status.
 * @param register - "true" indicates to register monitoring, "false" is to cancel monitoring.
void observeEventChanged(Observer<List<Event>> observer, boolean register);
  • Example
NIMClient.getService(EventSubscribeServiceObserver.class).observeEventChanged(new Observer<List<Event>>() {
    public void onEvent(List<Event> events) {
        // Processing.
}, true);

Querying event subscription

Support to query event subscription and query subscription relations of a certain event.

  • API prototype
 * Query subscription relationship of specified type of event.
 * @param request - Query subscription information. The event type and account of event publisher must be filled in, and then subscription relationship of specified publisher will be queried.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only after request. If an error occurs, detailed error code will be returned.
InvocationFuture<List<EventSubscribeResult>> querySubscribeEvent(EventSubscribeRequest request);
  • Parameters

EventSubscribeResult Description

Parameter Description
eventType Event type, input 1.
expiry Validity period of subscription, ranging from 60 seconds to 30 days, unit: second.
time Time of event subcription.
publisherAccount Account set of event publisher.
  • Example

Online status events

Online status (online, abnormal disconnection, logout) is a built-in event of CommsEase system. Before the use, it is only required to make an application to the sales department and obtain the approval for the application. It is not required to actively publish event status. Typically, if A has subscribed an online status event from B, A may obtain B's online status after login: online, abnormal disconnection or logout.


  • By calling the interface each time, up to 100 accounts can be subscribed. The interface should be called frequently for a larger number of accounts. In relation to online status event subscription, the maximum number of valid subscription accounts is no more than 3,000 for each accid.
  • The subscription remains valid in 60 - 2,592,000 s (i.e. 60 s-30 days), and another subscription is required after expiry. In the event of repeated subscription within the validity term, the new validity term will replace the previous one.
  • Online status events will be affected by push: if the application is cleared, but the vendor pushes (APNS, Xiaomi, Huawei, OPPO, VIVO, Meizu, FCM) are reachable, the disconnection event will not be triggered in default. If the offline status is required in such event, the developer should make modifications using CommsEase Console>Select Application>IM Professional>Feature Configuration>Online Status Configuration; if no integrated push is available or the push is unreachable, user disconnection will trigger the disconnection event.
  • Default value of online state event in system: 1 - login; 2 - logout; 3 - offline. If it is required to set the custom status, such as busy, please publish event.
  • At login, the subscriber will receive the callback of the online event if the subscribed is online; but if the subscribed is offline, the subscriber will be unable to receive the callback of the offline event (subsequent login of the subscribed will trigger the online status event). We recommend setting the status of all accounts from online to offline at login, so that callback will be normally triggered no matter whether the other is online or the status is changed from offline to online.
  • Friendship and online status are two different features of IM. When a friend is added, his/her online status will not be displayed.
  • One-way subscription applies to online status event, to which both parties should subscribe respectively.

As mentioned above, online status event is a built-in event of CommsEase system, which the developer is not required to actively publish. After subscribing to the "type -1" event from B, A will receive the corresponding event at login if B is online; if B logs in to the account again and both B and A are online, A still can monitor the event.

Was this topic helpful?
  • Overview
  • Subscribing to events
  • Unsubscribing from events
  • Unsubscribing from events by accounts
  • Unsubscribing from events by events
  • Publishing events
  • Listening from subscribed events
  • Querying event subscription
  • Online status events