Skip to main content

Chatroom Status Update Callback

The Chatroom Status Update Callback is a service provided by the IM Service that allows real-time synchronization of chatroom status changes to a designated application server address. Currently, it supports the following status updates:

  • Chatroom creation
  • Chatroom destruction
  • Member joining a chatroom
  • Member leaving a chatroom
tip

The Chatroom Status Update Callback does not support synchronization for scenarios where the same user is online across multiple devices simultaneously.

Enabling the Service​

Before using the Chatroom Status Update Callback feature, ensure that the service has been enabled for the current App Key. For details, refer to Chatroom 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 properly.

Callback Method​

Request Method: POST

Data Format: application/json

The IM server will append 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.

Body Parameters​

The HTTP request body for this callback service is in application/json format and contains a JSON object with the following structure:

ParameterTypeDescription
chatRoomIdStringThe chatroom ID.
userIdsString[]User ID data.
statusIntThe operation status, with the following values:
  • 0: The operator actively called the client or server API corresponding to the chatroom event type (see the type field).
  • 1: The chatroom auto-exit mechanism was triggered, causing the user to leave the chatroom (kicked out).
    • Chatroom members will be automatically exited if they are offline for 30 seconds and new messages are generated, or if 30 messages are generated while they are offline.
    • Status synchronization for this state is triggered only when new messages are generated in the chatroom.
  • 2: The user was banned.
  • 3: The chatroom auto-destruction mechanism was triggered.
typeIntThe chatroom event type, with the following values: 0 for chatroom creation, 1 for joining a chatroom, 2 for leaving a chatroom, and 3 for chatroom destruction.
timeNumberThe timestamp of the event.

Callback Code Example​

The following example assumes that the callback URL configured in the service enablement page is http://example.com/chatroom_status_sync.php.

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

[
  {
    "chatRoomId":"destory_11",
    "userIds":["gggg"],
    "status":0,
    "type":1,
    "time":1574476797772
  },
  {
    "chatRoomId":"destory_12",
    "userIds":[],
    "status":0,
    "type":0,
    "time":1574476797772
  }
]

Responding to Callback Requests​

tip
  • The server will consider the status synchronized as long as an HTTP 200 OK response is received.
  • 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 sending requests to your server and resume after 1 minute. In case of abnormal network disconnection, synchronization will be delayed by 5 minutes.
Last updated on