Set message metadata

The community channel message metadata feature allows you to add status indicators (key-value pairs) to messages. APIs are provided for adding, deleting, and querying metadata.

Use cases

Any scenario where you need to add status indicators to messages can use metadata. Examples:

• Message reactions/comments: Add comment information as metadata on the original message.
• Gift claiming / Order status changes: Change the display state of a message. For example, send a gift message with a default "unclaimed" state, then update the metadata to "claimed" when the user taps it.

Supported channel types

Community channel message metadata APIs are only available for community channel conversations.

Prerequisites

The original message must be sent with metadata enabled. Each message supports up to 300 metadata entries, with up to 100 entries set per request.

tip

When sending messages via the Server API, set hasMetadata to true to enable metadata on the message.

Request method

POST: https://Base URL/v4/community-channel/message/metadata/set

Rate limit: 100 requests per second

Signature required: All server API requests require signature verification. See API request signature.

Request body

The request body is in application/json format and contains a JSON object with the following structure:

tip

If the total metadata entries exceed 300, the set operation fails entirely. For example, if 290 entries already exist and you attempt to add 100 more, the entire request fails.

Parameter	Type	Required	Description
messageUID	String	Yes	The message UID. Obtainable via the message routing service. See Message routing.
userId	String	Yes	The operator's user ID — the user setting metadata on the specified message.
subchannelId	String	No	The subchannel ID. Required if the message was sent with a subchannel ID; must be omitted if the message was sent without one. On the client side, this corresponds to channelId.
channelId	String	Yes	The community channel ID.
metadata	Object	Yes	Metadata content as key-value pairs, e.g., {"type":"3"}. Key: max 32 characters, supports letters, numbers, and + = - _ (no Chinese characters). Value: max 4096 characters. Up to 20 entries per request, 300 entries per message.

Request example

HTTP

POST /v4/community-channel/message/metadata/set HTTP/1.1
Host: api.sg-light-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/json

{
    "messageUID": "BRGM-DEN2-01E4-BN66",
    "userId": "WNYZbMqpH",
    "channelId": "tjw3zbMrU",
    "subchannelId": "",
    "metadata": {"type": "3"}
}

Response

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

Field	Type	Description
code	Number	Status code. 0 indicates success. See status codes.

Response example

HTTP

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

{"code":0}