Send one-to-one chat messages

Users within an application can send one-to-one chat messages to other users.

• A single request supports sending messages to one or multiple users, with a maximum of 1000 users per request.
• Messages sent through this API will not be synchronized to the sender's client by default, nor will they be stored in the sender's historical message records. To enable synchronization, refer to the usage of the isIncludeSender parameter.

Request Method

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

Rate Limit: Up to 6000 messages can be sent per minute. Note that sending to 1000 users in one request counts as 1000 messages. Also, see Known Issue 1.

Signature Rule: All server API requests must follow the signature validation rules. For 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
fromUserId	String	Yes	The sender's user ID. Note: The user ID used to send the message must have obtained a user Token; otherwise, the sender's user information will not be correctly displayed in the notification if the message triggers an offline push.
toUserId	String	Yes	The recipient's user ID. Messages can be sent to multiple users, with a maximum of 1000 users per request.
objectName	String	Yes	The message type, which accepts built-in message types (see Message Type Overview) or custom message type values. Note: When using custom messages, the message type must not start with "RC:" to avoid conflicts with built-in message types; the message type length must not exceed 32 characters. The custom message type must be registered in the SDK; 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 and pass it here. The JSON structure of the message content is detailed in 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 value 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 field must be specified as a custom message type): If sending a custom message, this parameter can be in a custom 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. If the message type (objectName field) is a user content message format in the IM Service predefined message types, this field can be left blank, and the remote push notification will use the default push notification content preset by the server. If the message type (objectName field) is a notification or signaling type (excluding "recall command message") in the IM Service predefined message types, 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, then pushContent 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., an App business layer operation command implemented via a custom message type), the pushContent field can be left blank to disable remote push notification.
pushData	String	No	On the iOS platform, the APNs push data can be retrieved from the payload, corresponding to the appData field (Hint: The rc field carries basic message information by default). On the Android platform, the corresponding field 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 definitely receive this sent message; you may need to enable other services. For details, refer to How to Sync Sent Messages to Sender's Client.
count	Int	No	Only valid for iOS devices. Controls the badge count of unread messages when pushing. Only valid when toUserId is a single user ID. The client retrieves the remote push content as badge. For details, refer to the iOS client documentation under "APNs Push Development Guide" in the Integrate APNs Remote Push section. A value of -1 does not change the badge count; passing a specific number sets the badge count to that number, with a maximum of 9999.
verifyBlacklist	Int	No	Whether to filter the recipient's blocklist. 0 means no filtering, 1 means filter, default is 0.
isPersisted	Int	No	Whether to store this message in the historical message cloud storage service for the recipient. 0 means no storage; 1 means storage. Default is 1, meaning storage (dependent on Cloud Storage for One-to-One and Group Messages). This attribute does not affect the offline message functionality; messages will be stored as offline messages? when the user is offline. Hint: Generally (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 identifier 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 identifier when this type is registered on the client. If the message belongs to a custom message type not registered on the client App (e.g., the client is using an outdated App version), the client SDK will determine whether to store the message locally based on the current parameter value. However, since the message type is not registered, the client cannot parse and display the message.
contentAvailable	Int	No	Only valid for iOS devices. When the app is in the background, it is a silent push, 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 it is an extensible message, default is false. When set to true, the terminal can set extended information for this message after receiving it. Mobile SDK version 4.0.3 and Web SDK version 3.0.7 support this feature.
extraContent	Object	No	Only valid when expansion is true. 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 Expansion, or the client "Message Expansion" interface documentation. KV Detailed Requirements: Set in Key-Value pairs, e.g., {"type":"3"}. Key maximum 32 characters, supports uppercase and lowercase English letters, numbers, and special characters + = - _, does not support Chinese characters. Value maximum 4096 characters. Up to 100 KV pairs can be set per request, and up to 300 KV pairs can be set per message.
disablePush	Boolean	No	Whether it is a silent message, default is false. When set to true, the terminal user will not receive a notification reminder when offline.
pushExt	String	No	Configures the push notification for the message, such as the push notification title, etc. This attribute is invalid when disablePush is true. For details, refer to the pushExt Parameter Description below.
disableUpdateLastMsg	Boolean	No	Prevents 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 conversation list's message content. Note: This parameter is only valid for messages stored on the client.

• pushExt Parameter Description

  The pushExt parameter supports setting the title, push content template, whether to force notification, and the push ChannelID for the message's push notification. pushExt requires escaping when structured as a JSON request.

  pushExt Parameter	Type	Required	Description
  title	String	No	The title displayed in the notification bar, with a maximum length of 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	The push template ID. After setting, the push content will be matched based on the target user's language environment set via the SDK. If no match is found, the default content will be used.
  forceShowPushContent	Number	No	Whether to bypass client configurations and force the display of notification content (pushContent) in the push notification. Default value 0 means no force, 1 means force. Explanation: Client devices can be configured to display only reminders like "You have a new notification" when receiving push notifications. When sending messages from the server, setting forceShowPushContent to 1 bypasses this configuration, forcing 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 include 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 (consulting and marketing messages). If a marketing message with an image is sent, the image will not be displayed.
  pushConfigs.HONOR.image	String	No	Honor push custom notification bar message's large icon URL on the right. If not set, the notification bar's right icon will not be displayed. The URL must use HTTPS protocol, sample value: https://example.com/image.png. The icon file must be less than 512KB, with a recommended size of 40dp x 40dp and a corner radius of 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
  pushConfigs.HW.channelId	String	No	Huawei push notification channel ID. For details, refer to Huawei Custom Notification Channels. For more information on notification channels, refer to Android Official Documentation.
  pushConfigs.HW.importance	String	No	Huawei notification bar message priority, values: NORMAL (default, important information) LOW
  pushConfigs.HW.image	String	No	Huawei push custom notification bar message's large icon URL on the right. If not set, the notification bar's right icon will not be displayed. The URL must use HTTPS protocol, sample value: https://example.com/image.png. The icon file must be less than 512KB, with a recommended size of 40dp x 40dp and a corner radius of 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
  pushConfigs.HW.category	String	No	Huawei push channel's message self-classification identifier, category values must be uppercase letters, e.g., IM. After completing the Self-classification Rights Application or Special Permission Application as required by Huawei, this field can be passed effectively. For details, refer to Huawei's official documentation Message Classification Standards. This field has higher priority than the Huawei push Category configured for the App Key's Application Identifier in the Console.
  pushConfigs.MI.channelId	String	No	Xiaomi push notification channel ID. For details, refer to Xiaomi Push Message Classification New Rules.
  pushConfigs.MI.large_icon_uri	String	No	Xiaomi push custom notification bar message's right icon URL. If not set, the notification bar's right icon will not be displayed. Domestic version only supports MIUI12 and above; international version supports. Image requirements: size 120 * 120px, format png or jpg.
  pushConfigs.OPPO.channelId	String	No	OPPO push notification channel ID. 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 notification bar, 2 notification bar + lock screen, 16 notification bar + lock screen + banner + vibration + ringtone; this field is 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 (operational messages, default) and 1 (system messages). This parameter corresponds to the classification field in the VIVO push service, see VIVO Push Message Classification Instructions. This field has higher priority than the VIVO push channel type configured for the App Key's Application Identifier in the Console.
  pushConfigs.VIVO.category	String	No	Secondary classification for VIVO push service messages. For example, 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.
  pushConfigs.APNs.thread-id	String	No	iOS notification grouping ID. Notifications with the same thread-id are grouped. 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. Custom notification icon URL on the right (requires app-side parsing and display). Supported on iOS 10.0+.
  pushConfigs.APNs.interruption-level	String	No	For iOS 15+. Valid 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 messages, ensuring only the latest is delivered when recoverable.
  pushConfigs.FCM.imageUrl	String	No	For Android. Custom notification icon URL 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	Large notification icon URL (HTTPS required, e.g., https://example.com/image.png). Note: Supports PNG, JPG, JPEG, BMP formats. Recommended size is smaller than 128x128px. Images exceeding 49152px will not display.

Request Example

{
   "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 Example

POST /message/private/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&toUserId=2193&toUserId=2192&objectName=RC:TxtMsg&pushContent=thisisapush&pushData=%7B%22pushData%22%3A%22hello%22%7D&count=4&verifyBlacklist=0&isPersisted=1&isIncludeSender=0&disablePush=false&expansion=false

Response

The HTTP response body contains 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].userId	String	Recipient user ID (matches the request's toUserId).
messageUIDs[i].messageUID	String	Unique message ID sent to the recipient.

Response Example

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

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