Broadcast to tagged users

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

• User tags must be configured via the Batch set user tags API.
• 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/v4/system-channel/tagged-users/send

Rate limit: Shares the system notification send 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, and tagOr 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	Number	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/tagged-users/send HTTP/1.1
Host: api.sg-light-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/json

{
   "platform": [
      "ios",
      "android"
   ],
   "fromUserId": "fromuseId1",
   "audience": {
      "tag": [
         "A",
         "B"
      ],
      "tagOr": [
         "C"
      ],
      "userId": [
         "123",
         "456"
      ],
      "isToAll": false
   },
   "message": {
      "content": "{\"content\":\"1111\",\"extra\":\"aa\"}",
      "messageType": "RC:TxtMsg"
   },
   "notification": {
      "title": "Title",
      "forceShowPushContent": 0,
      "alert": "this is a push"
   }
}

Response

Field	Type	Description
code	Number	Status code. 0 indicates success.
result	Object	Response data.
result.id	String	Unique push identifier. Same as messageId.
result.messageId	String	Message ID.

Response example

HTTP

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

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