Send Group Messages

Send messages to one or multiple groups within your application. Note that when sending messages to a group via the Server API, the sender does not need to be a group member. The app must control message-sending permissions. This API supports the following functionalities:

• Send regular group messages: Supports sending messages to up to 3 groups at a time.
• Send targeted group messages: Allows sending messages to one or more specified users within a group, but only one target group is supported per request.

Messages sent via this API are not synchronized to the sender's client by default, nor are they stored in the sender's message history. For synchronization, refer to the isIncludeSender parameter.

Request Method

POST: https://data center domain/message/group/publish.json

Rate Limit: Up to 20 messages per second. Note that sending a message to 3 groups counts as 3 messages. Also, see Known Issue 1.

Signature Rule: All server API requests must be validated. For details, refer to API Request Signature.

Body Parameters

The HTTP request body data format is application/x-www-form-urlencoded, supporting the following HTTP form parameters:

tip

When sending targeted group messages, only one toGroupId is supported, and expansion, extraContent, disablePush, and pushExt fields are not supported.

Parameter	Type	Required	Description
fromUserId	String	Yes	Sender's user ID. Non-group members can also send messages to a group via the Server API. Note: The user ID used to send the message must have obtained a user Token; otherwise, if the message triggers an offline push, the sender's user information will not be displayed correctly in the notification.
toGroupId	String	Yes	Group ID(s) receiving the message. Supports up to 3 group IDs. When sending targeted group messages, only one group ID is supported.
toUserId	String	No	When sending targeted group messages, the list of user IDs of group members receiving the message. Other users in the group will not receive this targeted message. Only valid when toGroupId contains a single group ID.
objectName	String	Yes	Accepts built-in message types (see Message Type Overview) or custom message type values. Note: For custom messages, the message type must not start with "RC:" to avoid conflicts with system message types. The message type length must not 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.
content	String	Yes	The content of the message being sent, with a maximum size of 128k per message. Built-in message types: Serialize the message content JSON object into a JSON string. For the JSON structure of message content, refer to User Content Message Format or other built-in message type formats. For example, the JSON structure of a text message content includes a content field (this is the key within the JSON structure, note the distinction), so the serialized result of {"content":"Hello world!"} should be passed as the value of the content field here. Custom message types (objectName must specify a custom message type): If sending a custom message, this parameter can be customized and is 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. If the message type (objectName) is a predefined message type in the IM service such as User Content Message Format, this field can be left blank, and the remote push notification will use the default content preset by the server. If the message type (objectName) is a notification or signaling type (except "Recall Command Message") in the predefined message types in the IM service, and remote push notification is required, then pushContent must be filled in; otherwise, the recipient will not receive a remote push notification when offline. If remote push is not required, this field can be left blank. If the message type is a custom message type and remote push notification is required, the pushContent field must be filled in; otherwise, the recipient will not receive a remote push notification when offline. If the message type is a custom message type but remote push notification is not required (e.g., for app business layer operation commands implemented via custom message types), the pushContent field can be left blank to disable remote push notification.
pushData	String	No	On iOS, the APNs push data can be retrieved from the payload, with the field name appData (Hint: The rc field carries basic message information by default). On Android, the corresponding field name is appData.
isIncludeSender	Int	No	Whether to synchronize the sent message to the sender's client. 1 means synchronize, default is 0, meaning no synchronization. Note, merely setting this parameter does not guarantee that the sender's client will receive the sent message; you may need to enable other services. For details, refer to How to Synchronize Sent Messages to the Sender's Client.
isPersisted	Int	No	Whether to store this message in the recipient's cloud storage for historical messages. 0 means do not store; 1 means store. Default is 1, store (dependent on Cloud Storage for One-to-One and Group Messages). Note: Even if Cloud Storage for One-to-One and Group Messages is enabled, targeted group messages will not be stored in the server's historical message records. If needed, enable the Cloud Storage for Group Targeted Messages service in the RC Console under Basic Features. This attribute does not affect offline message functionality; messages will be stored as offline messages? when the user is offline. Hint: In general (cases 1 and 2), whether the client stores the message does not depend on this parameter. The following case 3 is an exception: If the message belongs to a built-in message type, the client SDK will determine whether to store it in the local database based on the storage attribute of the message type itself. Refer to Message Type Overview. If the message belongs to a custom message type, the client SDK will determine whether to store it in the local database based on the storage attribute set during registration of the type on the client. If the message belongs to a custom message type not registered on the client app (e.g., the client app version is outdated), the client SDK will determine whether to store the message locally based on this parameter. However, since the message type is not registered, the client cannot parse or display the message.
isMentioned	Int	No	Whether it is an @ message. Default is non-@ message (equivalent to passing 0). To send an @ message, this must be set to 1, and the @ information (mentionedInfo) must be included in the message content field (content). For a detailed explanation of the mentionedInfo structure, refer to How to Send @ Messages.
contentAvailable	Int	No	For iOS, enables silent push when the SDK is in the background, a push method introduced after iOS7. Allows the app to run a piece of code in the background upon receiving the notification and execute it immediately. For details, refer to the Knowledge Base Document. 1 means enabled, 0 means disabled, default is 0.
expansion	Boolean	No	Whether the message is extensible. Default is false. When set to true, the terminal can set extension information for this message upon receipt. Supported in mobile SDK version 4.0.3 and web SDK version 3.0.7. Only valid when toGroupId contains a single group ID.
extraContent	Object	No	Only valid when expansion is true, and only when toGroupId contains a single group ID. Custom message extension information, this field accepts key-value pairs in JSON string format. Note the distinction from the extra field in the message body; the value of extraContent can be modified after the message is sent. For modification methods, refer to the server API documentation Message Extension or the client "Message Extension" interface documentation. KV Requirements: Set in Key-Value pairs, e.g., {"type":"3"}. Key maximum 32 characters, supports uppercase and lowercase letters, numbers, and special characters + = - _. Does not support Chinese characters. Value maximum 4096 characters. Up to 100 KV pairs can be set at a time, and a single message can have up to 300 KV pairs.
disablePush	Boolean	No	Whether the message is silent. Default is false. When set to true, offline users will not receive notification reminders. Only valid when toGroupId contains a single group ID.
pushExt	String	No	Configures the push notification for the message, such as the notification title. This attribute is invalid if disablePush is true. For details, see the pushExt Parameter Description below. Only valid when toGroupId contains a single group ID.
disableUpdateLastMsg	Boolean	No	Disables updating the last message in the conversation. When this parameter is false, the sent message will appear in the conversation list; when true, it will not update the conversation list's message content. Note: This parameter only affects messages stored on the client.

• pushExt Parameter Description

  The pushExt parameter supports setting the title, push content template, whether to force notification, and the ChannelID for push notifications. pushExt must be escaped when passed as a JSON structure.

  pushExt Parameter	Type	Required	Description
  title	String	No	The title displayed in the notification bar, up to 50 characters. By default, the notification title for one-to-one chats displays the user's name, and for group chats, it displays the group name.
  templateId	String	No	Push template ID. After setting, the push content will match the language environment set by the target user via the SDK. If no match is found, the default content will be used.
  forceShowPushContent	Number	No	Whether to bypass client settings and force the push notification to display the notification content (pushContent). Default is 0, meaning no force; 1 means force. Note: Client devices can be set to display only notifications like "You have received a notification" when receiving push notifications. When sending messages from the server, setting forceShowPushContent to 1 bypasses this setting and forces the client to display the push content in the notification for this message.
  pushConfigs	Array	No	Set different push attributes by vendor. Supported push channels are MI (Xiaomi), HONOR (Honor), HW (Huawei), OPPO, VIVO, APNs, FCM.
  pushConfigs.HONOR.importance	String	No	Honor notification bar message priority. Values: NORMAL (Service and communication messages) LOW (Marketing and advisory messages). If marketing messages are sent with an image, the image will not be displayed.
  pushConfigs.HONOR.image	String	No	URL of the large icon on the right side of the Honor push custom notification bar message. If not set, the icon will not be displayed. The URL must use the HTTPS protocol, e.g., https://example.com/image.png. The icon file must be less than 512KB, with a recommended size of 40dp x 40dp and rounded corners of 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
  pushConfigs.HW.channelId	String	No	ID of the Huawei push notification channel. For details, refer to Huawei Custom Notification Channels. For more information on notification channels, refer to the Android Official Documentation.
  pushConfigs.HW.importance	String	No	Huawei notification bar message priority. Values: NORMAL (default, important information) LOW
  pushConfigs.HW.image	String	No	URL of the large icon on the right side of the Huawei push custom notification bar message. If not set, the icon will not be displayed. The URL must use the HTTPS protocol, e.g., https://example.com/image.png. The icon file must be less than 512KB, with a recommended size of 40dp x 40dp and rounded corners of 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
  pushConfigs.HW.category	String	No	Huawei push channel message self-classification identifier, e.g., IM. After completing the Self-Classification Rights Application or Special Permission Application as required by Huawei, this field can be passed. For details, refer to the Huawei push official documentation Message Classification Standards. This field takes precedence over the Huawei push Category configured in the Console for the App Key's Application Identifier.
  pushConfigs.MI.channelId	String	No	ID of the Xiaomi push notification channel. For details, refer to Xiaomi Push Message Classification New Rules.
  pushConfigs.MI.large_icon_uri	String	No	URL of the large icon on the right side of the Xiaomi push custom notification bar message. If not set, the icon will not be displayed. Only supported on MIUI12 and above for the domestic version; not supported on versions below MIUI12. Supported on the international version. Image requirements: Size 120 * 120px, format png or jpg.
  pushConfigs.OPPO.channelId	String	No	ID of the OPPO push notification channel. For details, refer to OPPO PUSH Channel Upgrade Instructions.
  pushConfigs.OPPO.category	String	No	Push content classification. For details, refer to OPUSH Message Classification Details.
  pushConfigs.OPPO.notify_level	Number	No	Notification reminder type, 1 for notification bar, 2 for notification bar + lock screen, 16 for notification bar + lock screen + banner + vibration + ringtone; valid when category is set. For details, refer to OPUSH Message Classification Details.
  pushConfigs.VIVO.classification	Number	No	VIVO push service message category. Optional values 0 (marketing messages, default) and 1 (system messages). This parameter corresponds to the classification field in the VIVO push service, refer to VIVO Push Message Classification Instructions. This field takes precedence over the VIVO push channel type configured in the Console for the App Key's Application Identifier.
  pushConfigs.VIVO.category	String	No	Secondary classification for VIVO push service messages, e.g., IM (Instant Messaging). This parameter corresponds to the category field in VIVO's push service. For valid values, refer to VIVO Push Message Classification Guide. If specifying category, you must also provide the matching classification value (system message scenario or operational message scenario). Ensure the category values comply with VIVO's requirements and fall under permitted content for system/operational message scenarios. This field takes precedence over the VIVO push Category configured under the Application Identifier of the App Key in the console.
  pushConfigs.APNs.thread-id	String	No	iOS notification grouping ID. Notifications with the same thread-id are grouped, and groups exceeding 5 notifications are collapsed.
  pushConfigs.APNs.apns-collapse-id	String	No	For iOS. Messages with the same apns-collapse-id are merged into one on the device. Supported on iOS 10.0+.
  pushConfigs.APNs.richMediaUri	String	No	For iOS. URL for the custom notification icon on the right (requires app-side parsing and display). Supported on iOS 10.0+.
  pushConfigs.APNs.interruption-level	String	No	For iOS 15+. Values: passive, active (default), time-sensitive, or critical. See APNs interruption-level. Use this to ensure critical notifications (e.g., account balance changes) bypass "Scheduled Summary" or "Focus Mode" restrictions.
  pushConfigs.FCM.channelId	String	No	FCM notification channel ID. The app must create a channel with this ID before receiving notifications. See Android Docs.
  pushConfigs.FCM.collapse_key	String	No	For Android. Identifier for collapsing a group of messages, ensuring only the latest is delivered when recoverable.
  pushConfigs.FCM.imageUrl	String	No	For Android. URL for the custom notification icon on the right. Requirements: Image size ≤1MB FCM push configuration in the console must use Certificate + Notification Messages.
  pushConfigs.OHOS.category	String	No	HarmonyOS scenario-based notification category (e.g., IM). After completing Self-Classification Rights Application, this identifies notification types, affecting display and alerts. Valid values: API Parameters.
  pushConfigs.OHOS.image	String	No	URL for the large notification icon (HTTPS required, e.g., https://example.com/image.png). Note: Supports PNG, JPG, JPEG, BMP formats. Recommended size is smaller than 128x128 px. Images exceeding 49152 px will not display.

• Example of pushExt Structure

  {
  "title":"you have a new message.",
  "templateId":"123456",
  "forceShowPushContent":0,
  "pushConfigs": [
      {
          "HW": {
              "channelId": "hw-123",
              "importance": "NORMAL",
              "image":"https://example.com/image.png"
          }
      },
      {
          "MI": {
              "channelId": "mi-123",
              "large_icon_uri":"https://example.com/image.png"
          }
      },
      {
          "OPPO": {
                  "channelId": "oppo-123",
                  "category": "IM",
                  "notify_level": 2
              }
      },
      {
          "VIVO" : {"classification": "0"}
      },
      {
          "APNs": {
              "thread-id": "123",
              "apns-collapse-id":"123456",
              "richMediaUri":"https://example.com/image.png"
          }
      },
      {
          "FCM": {
              "channelId":"rongcloud_channelid",
              "collapse_key":"1234",
              "imageUrl":"https://example.com/image.png"
              }
      },
      {
          "OHOS": {
              "category": "IM",
              "image":"https://example.com/image.png"
          }
      }
  ]
  }

Request Examples

Regular Group Message

POST /message/group/publish.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

fromUserId=0MglYiqxW&toGroupId=d9Uia1h8C&content=%7B%22content%22%3A%22%40%E6%B5%8B%E8%AF%9511%20c%23hello%22%2C%22mentionedInfo%22%3A%7B%22type%22%3A2%2C%20%22userIdList%22%3A%5B%22wX7zFv8dR%22%5D%2C%22mentionedContent%22%3A%22%22%7D%7D&objectName=RC%3ATxtMsg&pushContent=thisisapush&pushData%22%3A%22hello%22%7D&isPersisted=1&isIncludeSender=0&isMentioned=1

Targeted Group Message

POST /message/group/publish.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

content=%7B%22content%22%3A%22hello%22%2C%22extra%22%3A%22helloExtra%22%7D&fromUserId=2191&toGroupId=2193&toUserId=123&toUserId=456&objectName=RC%3ATxtMsg&pushContent=thisisapush&pushData%22%3A%22hello%22%7D&isPersisted=1&isIncludeSender=0&isMentioned=1&mentionedInfo=%7B%22type%22%3A2%2C%22userIdList%22%3A%5B%22123%22%2C%22456%22%5D%2C%22mentionedContent%22%3A%22%E6%9C%89%E4%BA%BA%40%E4%BD%A0%22%7D

Response

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

Field	Type	Description
code	Number	Status code. 200 indicates success.
messageUIDs	Array	List of message UIDs.
messageUIDs[i].groupId	String	Group ID (matches the request's toGroupId).
messageUIDs[i].messageUID	String	Unique message ID sent to the group.

Response Example

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

{
    "code": 200,
    "messageUIDs": [
        {
            "groupId": "2191",
            "messageUID": "XXXX-JJJJ-KKK-LLLL"
        },
        {
            "groupId": "2192",
            "messageUID": "XXXX-JJJJ-KKK-LLKL"
        }
    ]
}