Send notification by tag

Send a system channel message and push notification to users matching specified tags.

• User tags must be configured via the Set user tag or Batch set user tags APIs.
• Supports built-in and custom message types. Channel type is SYSTEM. Recipients cannot reply.
• Online recipients receive the message immediately. Offline recipients receive a push notification.

Prerequisites

Enable the Broadcast Service for the current App Key. See Broadcast service configuration. Returns error 1009 if not enabled.

Request

POST: https://[Base URL](/platform-chat-api/base-url)/v4/system-channel/push

Rate limit: Shares the /v4/system-channel/push quota — 2 per hour, 3 per day (calendar day). Processes up to 1500 messages per second.

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

Request body

Content type: application/json

Parameter	Type	Required	Description
platform	String[]	Yes	Target platforms: iOS, Android, HarmonyOS. At least one required. Web users also receive messages if logged in.
fromUserId	String	Yes	Sender user ID. Must have obtained an access token.
audience	Object	Yes	Targeting criteria. If isToAll is true, other criteria are ignored.
audience.userId	String[]	No	User IDs. Max 1000. If set, platform, tag, tagItems are ignored.
audience.tag	String[]	No	User tags (AND logic). Max 20. Ignored when isToAll is true.
audience.tagOr	String[]	No	User tags (OR logic). Max 20. Can coexist with tag.
audience.isToAll	Boolean	Yes	true: send to all users (ignores tag, tagOr, userId). false: use targeting criteria.
message.content	String	Yes	Message content, max 128 KB.
message.messageType	String	Yes	Message type. See Message type overview.
message.disableUpdateLastMsg	Boolean	No	Prevent updating the last message in the channel list.
notification	Object	Yes	Push notification settings by platform.
notification.title	String	No	Push notification title (max 50 characters).
notification.forceShowPushContent	Int	No	Force display push content. 0 (default): no. 1: force.
notification.alert	String	No	Push content. If omitted, must set notification.ios.alert and notification.android.alert separately.
notification.ios	Object	No	iOS push settings. Includes title, alert, contentAvailable, badge, thread-id, apns-collapse-id, category, richMediaUri, interruption-level, extras.
notification.android	Object	No	Android push settings. Includes alert, honor.*, hw.*, mi.*, oppo.*, vivo.*, fcm.*, meizu.*, extras.
notification.harmonyOS	Object	No	HarmonyOS push settings. Includes alert, ohos.category, ohos.image, extras.

Request example

HTTP

POST /v4/system-channel/push HTTP/1.1
Host: api.sg-light-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1585127132438
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/json

{
  "platform":["ios","android"],
  "fromUserId": "fromuseId1",
  "audience":{
    "tag":["premium","active"],
    "tagOr":["beijing","shanghai"],
    "isToAll":false
  },
  "message": {
    "content": "{\"content\":\"Hello\",\"extra\":\"data\"}",
    "messageType": "RC:TxtMsg"
  },
  "notification":{
    "title":"New Announcement",
    "forceShowPushContent":0,
    "alert":"You have a new notification",
    "ios":{
      "alert": "iOS notification",
      "thread-id":"223",
      "apns-collapse-id":"111",
      "extras": {"id": "1","name": "2"}
    },
    "android": {
      "alert": "Android notification",
      "hw":{"channelId":"NotificationKanong","importance":"NORMAL"},
      "mi":{"channelId":"rongcloud_kanong"},
      "oppo":{"channelId":"rc_notification_id","category":"IM","notify_level":2},
      "vivo":{"classification":"0"},
      "extras": {"id": "1","name": "2"}
    },
    "harmonyOS": {
      "ohos":{"category":"IM","image":"https://example.com/image.png"},
      "extras": {"id": "1","name": "2"}
    }
  }
}

Response

Property	Type	Description
code	Number	Status code. 0 indicates success.
result	Object	Response data.
result.messageUID	String	Message ID.

Response example

HTTP

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

{
    "code": 0,
    "result": {
        "messageUID": "XXXX-JJJJ-KKK-LLLL"
    }
}