Send System Notification Template Message

App users can send system notification template messages to other users. A maximum of 100 users can receive the message in a single send. This falls under the category of Message-bearing Notification.

• Supports sending predefined message types from the IM Service (see Message Type Overview). The message type (objectName field) determines whether the message supports offline push notification, and whether the client displays the message in the chat UI, conversation list, or stores it in the local database.
• Supports sending custom message types. Whether the client displays the custom message in the chat UI, conversation list, or stores it in the local database depends on the custom message type definition registered by the client.
• System notification messages can only be sent via the IM Service server API, with the conversation type set to SYSTEM. This type of conversation does not support replies from end users.
• The content, pushContent, and pushData fields of the message can be controlled via templates.

For example, for a general App business notification, assuming a text message (objectName is RC:TxtMsg, which is a built-in message type stored by the client SDK and can trigger offline push), the effect is as follows:

• If the client is online, it will immediately receive a message with the Target ID of the session set to the fromUserId passed in the API call, and the session type is system conversation (type SYSTEM).
• If the client is offline, the message will trigger a remote push from the server. If the client has integrated and enabled the push notification service, it will receive the push notification.

How to Configure and Use Message Templates

Message templates use content templates with placeholders and definitions provided by the recipient to achieve the effect of sending different content to multiple recipients in a single send.

Define Content Templates

When sending a message, you can pass placeholder fields in the content, pushContent, and pushData fields, for example:

"toUserId":["21","22","23"],
"content":"{\"content\":\"{c}{d}\",\"extra\":\"bb\"}",
"pushContent":["hello {c}","hello {c}","hello {c}"],

In the above example, {c} and {d} are custom placeholders.

• Currently supported fields for defining templates include: content, pushContent, pushData.
• The message content (content) field only supports inserting one template, which is shared by all recipients.
• The push notification content (pushContent) and push notification data (pushData) fields are arrays and must define templates for each user ID in the toUserId list. Even if placeholders are not used in pushContent or pushData, or if all recipients receive the same content, you must define pushContent and pushData for each user ID in the toUserId list.

Specify Values for Placeholders

Provide definitions for the placeholders in the values field according to the recipient list (toUserId), i.e., specify the personalized content each recipient should receive.

"values":[
    {
    "{c}":"Tom",
    "{d}":"：2"
    },
    {
    "{c}":"Jerry",
    "{d}":"：5"},
    {
    "{c}":"Rose",
    "{d}":"：10"}
    ],

In the above example, the content received by each recipient when online is as follows:

• User ID 21 receives: Tom：2
• User ID 22 receives: Jerry：5
• User ID 23 receives: Rose：10

If the recipient is offline, the content of the push notification (pushContent) they receive will also differ, being Hello Tom, Hello Jerry, and Hello Rose respectively.

tip

If the content field defines a placeholder {d}, then the values field must set a value for {d}, otherwise {d} will be sent to the user as text with the message.

Request Method

POST: https://data center domain/message/system/publish_template.json

Rate Limit: 100 requests per second. Note that sending a message to 100 users at the same time counts as 100 messages.

Signature Rule: All server API requests require signature verification. For details, see API Request Signature.

Body Parameters

The HTTP request body data format is application/json, containing a JSON object with the following structure:

Parameter	Type	Required	Description
fromUserId	String	Yes	The sender's user ID. Note: The user ID used to send the message must have already obtained a user Token, otherwise, if the message triggers an offline push, the sender's user information will not be correctly displayed in the notification.
toUserId	String[]	Yes	The recipient user ID(s). Providing multiple parameters allows sending messages to multiple users, with a maximum of 100 users.
objectName	String	Yes	Accepts predefined message types (see Message Type Overview) or custom message type values. Note: For custom messages, the message type cannot start with "RC:" to avoid conflicts with system-defined message types; the message type length cannot exceed 32 characters. The SDK must have registered this custom message type, otherwise the SDK will not be able to parse the message upon receipt.
values	Array of objects	Yes	Provides corresponding values for placeholders (e.g., {d}) in the message content (content), push notification content (pushContent), and push notification data (pushData).
content	String	Yes	The content of the message being sent, with a maximum size of 128k. Predefined message types: Serialize the message content JSON object into a JSON string and pass it in. The message content JSON structure is detailed in the Message Type Overview for each predefined message type. For example, the text message content JSON structure contains a content field (this is the key value within the JSON structure, note the distinction), then the serialized result of {"content":"Hello world!"} should be passed as the value of the content field here. Custom message types (objectName field must specify a custom message type): If sending a custom message, this parameter can be customized in any format, not limited to JSON.
pushContent	String[]	No	Specifies the notification content in the remote push notification triggered when the recipient is offline. Note: For some message types, whether this field has a value determines whether a remote push notification is triggered. Supports defining template placeholders, using values from values for substitution. If the message type (objectName field) is a predefined message type from the IM Service, filling this field will display the template-defined push content in the offline push notification, rather than the default push content for the message type. If the message type is a custom message type and needs to support remote push notifications, the pushContent field must be filled, otherwise the recipient will not receive a remote push notification when offline. If the message type is a custom message type but does not need to support remote push notifications (e.g., App business layer operation instructions implemented via custom message types), the pushContent field can be set to an empty array to disable offline push.
pushData	String[]	No	When an iOS platform receives a push message, the APNs push data can be obtained from the payload, corresponding to the appData field (Hint: the rc field carries basic message information by default). For Android platforms, the corresponding field name is appData.
contentAvailable	Int	No	For iOS platforms, this enables silent push when the SDK is in the background, a push method introduced after iOS7. It allows the app to run a piece of code in the background upon receiving the notification and execute it immediately. For details, see Knowledge Base Document. 1 means enabled, 0 means disabled, default is 0
disablePush	Boolean	No	Whether it is a silent message, default is false. When set to true, end users will not receive notification reminders when offline.
disableUpdateLastMsg	Boolean	No	Disables updating the last message in the conversation. When this parameter is false, the sent message will enter the conversation list; when true, it will not update the message content in the conversation list. Note: This parameter only affects messages stored on the client.

Request Example

POST /message/system/publish_template.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/json

{
    "fromUserId":"fromuser",
    "objectName":"RC:TxtMsg",
    "content":"{\"content\":\"{c}{d}{e}\",\"extra\":\"bb\"}",
    "toUserId":["21","22"],
    "values":[{"{c}":"1","{d}":"2","{e}":"3"},{"{c}":"4","{d}":"5","{e}":"6"}],
    "pushContent":["push{c}","push{c}"],
    "pushData":["pushd","pushd{e}"]
}

In the above example, the user with ID 21 receives the message "123", and the user with ID 22 receives the message "456".

Response

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

Return Value	Return Type	Description
code	Number	Return code, 200 is normal.
messageUIDs	Array	Returns a list of messageUIDs
messageUIDs[i].userId	String	The recipient's user ID, corresponding to the toUserId in the request
messageUIDs[i].messageUID	String	The unique ID of the message sent to the corresponding recipient

Response Example

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

{
    "code": 200,
    "messageUIDs": [
        {
            "userId": "uid1",
            "messageUID": "XXXX-JJJJ-KKK-LLLL"
        },
        {
            "userId": "uid2",
            "messageUID": "XXXX-JJJJ-KKK-LLKL"
        }
    ]
}