Broadcast by package name

Send a system channel message and push notification to all users of a specific app package (e.g., a student app vs. a teacher app sharing the same App Key).

• 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.

tip

Web users are not supported by this feature. Recipients cannot reply to system channel messages.

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/app-package-users/send

Rate limit: Shares the system notification send quota — 2 per hour, 3 per day (calendar day). Processes up to 2000 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.
fromUserId	String	Yes	Sender user ID. Must have obtained an access token.
audience	Object	Yes	Targeting criteria. Set packageName for package-based targeting.
audience.userId	String[]	No	User IDs. Max 1000. Takes priority over tag and packageName.
audience.packageName	String	No	App package name. Ignored when isToAll is true. AND logic with tag and tagOr.
audience.isToAll	Boolean	Yes	true: send to all users. 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 platform-specific alert values.
notification.ios	Object	No	iOS push settings.
notification.android	Object	No	Android push settings.
notification.harmonyOS	Object	No	HarmonyOS push settings.

Request example

HTTP

POST /v4/system-channel/app-package-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": {
      "packageName":"xxx.xxx.xxx",
      "is_to_all":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"
   }
}