Send a direct message

Send a direct message from one user to one or more recipients.

You can send a message to up to 1000 users in a single request.
By default, the message is not synced to the sender's client and is not stored in the sender's message history. To enable sync, see the isEchoToSender parameter.

Request

POST: https://[Base URL](/platform-chat-api/base-url)/v4/direct-channel/message/send

Rate limit: 6000 messages per minute. Sending to 1000 users in a single request counts as 1000 messages. See also known issues.

Authentication: All server API requests require signature verification. See API request signing.

Request body

Content type: application/json

Parameter	Type	Required	Description
`fromUserId`	`String`	Yes	Sender's user ID. The user must have obtained an access token; otherwise, if the message triggers a push notification, the sender's user info cannot display correctly.
`toUserIds`	`String[]`	Yes	Recipient user IDs. Up to 1000 users per request.
`messageType`	`String`	Yes	Message type. Accepts a built-in message type or a custom message type value. Custom message types must not start with `RC:` and must not exceed 32 characters. The custom message type must be registered in the client SDK; otherwise, the SDK cannot parse it.
`content`	`String`	Yes	Message content, max 128 KB per message. Built-in message types: Pass the message content JSON object serialized as a JSON string. See User content message format for the JSON structure. For example, for a text message: `{"content":"Hello world!"}`. Custom message types: The format is flexible and not limited to JSON.
`pushContent`	`String`	No	Push notification content displayed when the recipient is offline. For user content message types, this field is optional; the server uses a default push notification message. For notification and signal message types (except the recall command message), you must provide `pushContent` to trigger push notifications. For custom message types that need push notifications, `pushContent` is required. For custom message types that do not need push notifications (e.g., app-level commands), leave `pushContent` empty.
`pushData`	`String`	No	Custom data included in the push notification payload. On iOS, accessible as `appData` in the APNs payload (the `rc` field carries basic message info by default). On Android, accessible as `appData`.
`isEchoToSender`	`Number`	No	Whether to sync the sent message to the sender's client. `1` to sync, `0` (default) to not sync. Setting this alone may not guarantee delivery to the sender's client. See How to sync sent messages to the sender's client.
`count`	`Number`	No	iOS only. Controls the badge count for push notifications. Only effective when `toUserIds` contains a single user ID. Set to `-1` to leave the badge unchanged, or a number up to 9999 to set the badge count.
`verifyBlocklist`	`Number`	No	Whether to filter recipients against the sender's blocklist. `0` (default): do not filter. `1`: filter.
`shouldPersist`	`Number`	No	Whether to store this message in the cloud message history for the recipient. `0`: do not store. `1` (default): store. Requires the Direct and Group Channel Cloud Message Storage service. This does not affect missed messages — messages for offline users are always stored as missed messages. Note: In most cases, client-side storage does not depend on this parameter: Built-in message types: the client SDK uses the storage flag defined by the message type itself. Custom message types: the client SDK uses the storage flag set at registration. Unregistered custom message types: the client SDK falls back to this parameter value, but cannot parse the message.
`contentAvailable`	`Number`	No	iOS only. Enables silent push notifications (iOS 7+). When set to `1`, allows the app to execute code in the background upon receiving a notification. Default: `0` (disabled).
`hasMetadata`	`Boolean`	No	Whether to enable metadata (message expansion) for this message. Default: `false`. When `true`, clients can set metadata on this message after receiving it.
`metadata`	`Object`	No	Only effective when `hasMetadata` is `true`. Custom key-value pairs for message metadata. Unlike the `extra` field in the message body, `metadata` values can be modified after sending. See Message metadata. Requirements: Keys are max 32 characters (letters, digits, `+ = - _`). Values are max 4096 characters. Max 100 KV pairs per request, max 300 KV pairs per message.
`disablePush`	`Boolean`	No	Whether to suppress push notifications. Default: `false`. When `true`, offline recipients do not receive push notifications.
`pushExt`	`String`	No	Push notification configuration (e.g., title). Ignored when `disablePush` is `true`. See `pushExt` parameters below.
`disableUpdateLastMsg`	`Boolean`	No	Whether to prevent updating the last message in the channel. When `false`, the message appears in the channel list. When `true`, the channel list is not updated. Only effective for messages stored on the client.
`needReadReceipt`	`Number`	No	Whether to request a read receipt. `1`: request. `0` (default): do not request. Only effective for persisted messages (`shouldPersist` is `1`).

`pushExt` parameters

The pushExt parameter configures push notification properties such as title, template, forced display, and provider-specific channel IDs. Pass as an escaped JSON string.

Parameter	Type	Required	Description
`title`	`String`	No	Push notification title, max 50 characters. Defaults to the user name for direct channels or the group name for group channels.
`templateId`	`String`	No	Push template ID. Matches the recipient's language setting on the SDK. Falls back to default content if no match. Configure templates in the console under Custom Push Content.
`forceShowPushContent`	`Number`	No	Override client-side settings to force display of `pushContent` in push notifications. `0` (default): do not force. `1`: force display.
`pushConfigs`	`Array`	No	Provider-specific push settings. Supported providers: `MI`, `HONOR`, `HW`, `OPPO`, `VIVO`, `APNs`, `FCM`.
`pushConfigs.HONOR.importance`	`String`	No	HONOR notification priority. Values: `NORMAL` (service/communication), `LOW` (marketing; images are not displayed).
`pushConfigs.HONOR.image`	`String`	No	HONOR custom large icon URL (HTTPS). Max 512 KB, recommended 40×40 dp with 8 dp corner radius.
`pushConfigs.HW.channelId`	`String`	No	Huawei push notification channel ID. See Huawei custom notification channels.
`pushConfigs.HW.importance`	`String`	No	Huawei notification priority. Values: `NORMAL` (default), `LOW`.
`pushConfigs.HW.image`	`String`	No	Huawei custom large icon URL (HTTPS). Max 512 KB, recommended 40×40 dp with 8 dp corner radius.
`pushConfigs.HW.category`	`String`	No	Huawei message category identifier (uppercase, e.g., `IM`). Requires self-classification rights. Overrides the console-level Huawei Push category setting for this App Key.
`pushConfigs.MI.channelId`	`String`	No	Xiaomi push notification channel ID. See Xiaomi push message classification.
`pushConfigs.MI.large_icon_uri`	`String`	No	Xiaomi custom large icon URL. China edition: MIUI 12+ only. International edition: supported. Image requirements: 120×120 px, PNG or JPG.
`pushConfigs.OPPO.channelId`	`String`	No	OPPO push notification channel ID. See OPPO PUSH channel upgrade.
`pushConfigs.OPPO.category`	`String`	No	OPPO push content category. See OPUSH message classification.
`pushConfigs.OPPO.notify_level`	`Number`	No	OPPO notification type. `1`: notification bar. `2`: notification bar + lock screen. `16`: notification bar + lock screen + banner + vibration + sound. Effective after `category` is set.
`pushConfigs.VIVO.classification`	`Number`	No	VIVO message category. `0` (default): operational. `1`: system. See VIVO push message classification. Overrides the console-level VIVO push channel type.
`pushConfigs.VIVO.category`	`String`	No	VIVO message subcategory (e.g., `IM`). Must be paired with a matching `classification` value. See VIVO push message classification. Overrides the console-level VIVO push category.
`pushConfigs.APNs.thread-id`	`String`	No	iOS notification group ID. Notifications with the same `thread-id` are grouped. Groups with more than 5 notifications are collapsed.
`pushConfigs.APNs.apns-collapse-id`	`String`	No	iOS only. Notifications with the same collapse ID are merged into one. Requires iOS 10.0+.
`pushConfigs.APNs.richMediaUri`	`String`	No	iOS only. Custom large icon URL for push notifications. The app must parse `richMediaUri` to display it. Requires iOS 10.0+.
`pushConfigs.APNs.interruption-level`	`String`	No	iOS 15+ only. Values: `passive`, `active` (default), `time-sensitive`, `critical`. See APNs interruption-level.
`pushConfigs.FCM.channelId`	`String`	No	FCM notification channel ID. The app must create a channel with this ID before receiving notifications. See Android notification channels.
`pushConfigs.FCM.collapse_key`	`String`	No	Android only. Collapse key for grouping messages, so only the last message is delivered when connectivity resumes.
`pushConfigs.FCM.imageUrl`	`String`	No	Android only. Custom large icon URL for FCM push. Max 1 MB. Requires FCM configured with certificate and notification message mode in the console.
`pushConfigs.OHOS.category`	`String`	No	HarmonyOS push notification category (e.g., `IM`). Requires self-classification rights.
`pushConfigs.OHOS.image`	`String`	No	HarmonyOS large icon URL (HTTPS). Supported formats: PNG, JPG, JPEG, BMP. Recommended: under 128×128 px. Images exceeding 49152 px are not displayed.
`pushConfigs.MEIZU.noticeMsgType`	`Number`	No	Meizu push message type. `1`: private message. `2`: public message. See Meizu push classification.

`pushExt` example

JSON
{
   "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"
           }
       },
       {
           "MEIZU": {
             "noticeMsgType": 1
           }
       }
   ]
}

Request example

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

{
    "fromUserId": "2191",
    "toUserIds": ["2193", "2192"],
    "messageType": "RC:TxtMsg",
    "content": "{\"content\":\"hello\"}",
    "pushContent": "thisisapush",
    "pushData": "{\"pushData\":\"hello\"}",
    "shouldPersist": 1,
    "isEchoToSender": 0
}

Response

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

Property	Type	Description
`code`	`Number`	Status code. `0` indicates success. See Server API status codes.
`result`	`Object`	Response data object.
`result.messageUIDs`	`Array`	List of message UIDs.
`result.messageUIDs[i].userId`	`String`	Recipient user ID, corresponding to the `toUserIds` in the request.
`result.messageUIDs[i].messageUID`	`String`	Unique ID of the message sent to the corresponding recipient.

Response example

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

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

Chat SDK

Push Notification Service

Chat SDK

Call SDK

Call SDK

Chat Server

Request​

Request body​

pushExt parameters​

pushExt example​

Request example​

Response​

Response example​