Chatroom Attribute Synchronization (KV)

"Chatroom Attribute Synchronization" is a server-side callback service provided by the IM Service.

Once this callback service is enabled, any changes to the chatroom attributes (KV) within the application (such as setting, deleting, or clearing all attributes) will be synchronized in real-time to the developer's application server, facilitating business logic processing for chatrooms under the application.

Enabling the Service

Before using the Chatroom Attribute Synchronization (KV) 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, the server-side callback will not be received properly. The IM Service will synchronize any changes to the chatroom attributes (setting, deleting, or clearing all attributes) under the application to the specified callback URL.

Callback Method

Request Method: POST

Data Format: application/json

The IM Service will add a signature parameter to the POST request URL. You can verify the caller's identity and data validity through this 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:

Parameter	Type	Description
chatroomId	String	The chatroom ID.
key	String	The attribute Key.
value	String	The attribute Value.
optType	int	The operation type: 1 for set, 2 for delete, 3 for delete all attributes (KV).
userId	String	The user ID of the operator.
status	int	This field is currently unavailable. Do not use it.
timestamp	long	The timestamp recorded by the server.
version	long	The attribute version number (used for operation sequencing).

When synchronizing status, the service requires a 200 response. As long as an HTTP 200 response is received, the server will consider the status synchronized. If the response times out after 5 seconds, the server will attempt to push the status 2 more times. If it still fails, the status will no longer be synchronized. If there is a large-scale timeout in a short period, the push will be paused and resumed after 1 minute. In case of abnormal network disconnection, the synchronization will be delayed by 5 minutes.

Callback Request Example

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

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

[
  {
    "chatroomId":"kvchatroom2",
    "optType":1,
    "userId":"1DBrZTGCI",
    "key":"testKey",
    "value":"testValue",
    "status":"2",
    "timestamp":1645437940739,
    "version":1645437940738
  },
  {
    "chatroomId":"kvchatroom3",
    "optType":2,
    "userId":"testUser",
    "key":"testKey1",
    "status":"2",
    "value":"testValue",
    "timestamp":1645437940740,
    "version":1645437940740
  }
]