Set Message Extensions for One-to-One and Group Chats

Set extension information for messages that have already been sent in one-to-one or group chats based on the Message ID. You can set up to 100 extension attributes at a time, with a maximum of 300 attributes per message.

When extending messages via the Server API, the extension information is not synchronized to the operator's client by default, which may lead to inconsistencies. If needed, it is recommended to set the isSyncSender parameter to 1 and understand the usage details.

Prerequisites

The original message that requires extension must have its extensible attributes enabled at the time of sending.

For example, when sending a message via the IM service's server API, you need to set expansion to true to allow the message to support extension information.

Client SDKs support this feature starting from specific versions (mobile SDK 4.0.3, Web SDK 3.0.7). For more details, refer to the message extension documentation for each client.

Request Method

POST https://data center domain/message/expansion/set.json

Rate Limit: 100 requests per second. Note: A maximum of 20 group chat message extensions can be set within these 100 requests. Also see Known Issue 1.

Signature Rule: All server API requests require signature verification. For more details, refer to API Request Signature.

Body Parameters

The HTTP request body is formatted as application/x-www-form-urlencoded and supports the following HTTP form parameters:

Parameter	Type	Required	Description
msgUID	String	Yes	The unique identifier of the message, which can be obtained via the Post-messaging Callback feature. See Post-messaging Callback.
userId	String	Yes	The user ID of the operator, i.e., the user ID that needs to set the extension information for the specified message (msgUID).
conversationType	String	Yes	The conversation type. Supported conversation types include: 1 (one-to-one chat), 3 (group chat).
targetId	String	Yes	The target ID, which could be a user ID or group ID depending on the conversationType.
extraKeyVal	Object	Yes	The content of the message extension, in JSON format, set as Key-Value pairs, e.g., {"type":"3"}. The Key can be up to 32 characters, supporting uppercase and lowercase letters, numbers, and special characters + = - _. Chinese characters are not supported. The Value can be up to 4096 characters. A single message can have up to 300 extension attributes, with a maximum of 100 attributes set at a time.
isSyncSender	Int	No	The deletion operation generates an "extension operation message." This field specifies whether to synchronize this "extension operation message" to the sender's (operator's) client. 1 means synchronize, with the default value being 0, i.e., no synchronization. Note: Setting this parameter alone does not guarantee that the sender's client will receive the sent message. You may need to enable additional services. See How to Sync Sent Messages to the Sender's Client.

Request Example

POST /message/expansion/set.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

msgUID=BRGM-DEN2-01E4-BN66&userId=WNYZbMqpH&targetId=tjw3zbMrU&conversationType=1&extraKeyVal=%7B%22type%22%3A%223%22%7D

Response

The HTTP response body contains a JSON object with the following structure:

Return Value	Type	Description
code	Number	The return code, 200 indicates success.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200}