Skip to main content

Subscription User Status

Subscription User Status is a callback service provided by the IM server, utilizing the Webhook mechanism. You need to register your callback URL in the Console in advance. After registration, the IM server will notify your server in real-time whenever a user's status changes (online, offline, logout).

This Webhook can be used to modify user status in real-time when your application needs to display user online/offline status. If you need to directly query a user's online status, you can actively call the Server API interface Check User Online Status.

Enable the Service​

Before using the Subscription User Status feature, you need to enable the service for your application and the App Key in the current environment. For details, refer to User Service Configuration.

When enabling the service, configure a callback URL that is accessible. If your network has IP access restrictions, make sure to configure the IP Allowlist; otherwise, you won’t be able to receive server callbacks.

Callback Method​

Request Method: POST

Data Format: application/json

The IM server will add signature parameters to the POST request URL. You can verify the caller's identity and data validity through the signature. For details, refer to Server Callback Signature.

Callback Body Parameters​

The HTTP request body of this callback service is in application/json format, containing a JSON object with the following structure:

ParameterTypeDescription
useridStringUser ID.
statusStringUser status change event. 0 - User is online. 1 - User is offline. 2: User has logged out.
osStringOperating system: iOS, Android, HarmonyOS, Websocket, PC, MiniProgram (WeChat Mini Program), synchronized when the user goes online.
timelongTimestamp of the event.
clientIpStringThe user's current IP address and port.
sessionIdStringA unique ID for a connection. If the same user is online on multiple devices simultaneously, this ID can be used to distinguish between connections.

User status change event (status) parameter description:

  • 0 - User is online. This event indicates that the client has successfully connected to the IM service, meaning the application has called the connect method and the connection was successful.
  • 1 - User is offline. This event indicates that the client has disconnected from the IM service, meaning the application has called the disconnect method or the connection was lost due to an exception. In some extreme cases, the offline status may be synchronized with a delay of up to 5 minutes. For example, if the application is connected through a proxy network and the app loses connection abnormally, but the proxy service still maintains a connection cache with the IM service, this can cause a delay in synchronizing the user's offline status.
  • 2 - User has logged out. This event indicates that the client has logged out, meaning the application has actively called the logout method (logout). After logging out, the IM service will not trigger remote push notifications for this user.

The user offline event (1) also covers the following scenarios by default:

  • Multi-device mutual kick scenario: If an app user logs in on device A and then logs in on device B, device B will kick device A offline. The offline status of the user on device A will also trigger the server to synchronize the user offline event (1).
  • Multi-platform login scenario: If an app user logs in on different platforms, disconnecting on any platform will trigger the server to synchronize the user offline event (1).

Important

  • The status parameter in the callback body represents the user status change event. Its value differs from the status value returned by the Check User Online Status API interface, which represents the user's current status (online or offline). Please note the distinction.
  • Some early adopters of the Subscription User Status service may find that the synchronization behavior is inconsistent with the description above. If needed, please submit a ticket to adjust the Subscription User Status - Offline Status Full Notification switch.

Callback Request Example​

Assume the callback URL configured in the service enablement page is: http://example.com/online_status.php

POST /online_status.php?appKey=someappKey&timestamp=1408710653491&nonce=14314&signature=45beb7cc7307889a8e711219a47b7cf6a5b000e8 HTTP/1.1
Host: example.com
Content-Type: application/json

[
  {
    "userid": "apert60541",
    "status": "1",
    "os": "iOS",
    "time": 1437982625625,
    "clientIp":"172.20.10.94:41748",
    "sessionId":"0O6Bvfvik_L9R_NxR6GqQb"
  },
  {
    "userid": "apert60592",
    "status": "1",
    "os": "Android",
    "time": 1437982625625,
    "clientIp":"172.20.10.94:41748",
    "sessionId":"0O9Fvfvik_L9R_NaR3GqYz"
  },
  {
    "userid": "apert60533",
    "status": "2",
    "os": "Android",
    "time": 1437982625625,
    "clientIp":"172.20.10.94:41748",
    "sessionId":"0O4Hvfvik_L3B_XaR7GxAf"
  }
]

Responding to Callback Requests​

tip
  • As long as an HTTP 200 OK response is received, the server will consider the status synchronized.
  • If the response times out after 5 seconds, the server will retry twice. If it still fails, the status will no longer be synchronized.
  • If there is a large-scale timeout in a short period, the server will temporarily stop requesting your server and will resume sending callback requests after 1 minute. In cases of abnormal network disconnection, synchronization may be delayed by up to 5 minutes.
Last updated on