Send notification 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](/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 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.packageName	String	No	App package name. Ignored when is_to_all is true. AND logic with tag/tag_or.
audience.tag	String[]	No	User tags (AND logic). Max 20.
audience.tag_or	String[]	No	User tags (OR logic). Max 20.
audience.userid	String[]	No	User IDs. Max 1000. Takes priority over tag and packageName.
audience.is_to_all	Boolean	Yes	true: send to all users. false: use targeting criteria.
message.content	String	Yes	Message content, max 128 KB.
message.objectName	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 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/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":{
    "packageName":"xxx.rong.xxx",
    "is_to_all":false
  },
  "message": {
    "content": "{\"content\":\"Hello\",\"extra\":\"data\"}",
    "objectName": "RC:TxtMsg"
  },
  "notification":{
    "title":"Announcement",
    "forceShowPushContent":0,
    "alert":"You have a new notification",
    "ios":{
      "alert": "iOS notification",
      "extras": {"id": "1","name": "2"}
    },
    "android": {
      "alert": "Android notification",
      "hw":{"channelId":"NotificationKanong","importance":"NORMAL"},
      "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. 200 indicates success.
id	String	Push unique identifier (same as messageUID).
messageUID	String	Message ID.

Response example

HTTP

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

{
    "code": 200,
    "id": "XXXX-JJJJ-KKK-LLLL",
    "messageUID": "XXXX-JJJJ-KKK-LLLL"
}