Sending Downlink Messages

Authorization

For details, please refer to Client Credentials.

Bearer CF3Xl2XV6jMKZgqYSZFws9IPlgDvxqOfFSmrlmtkTRupbU2VklvhX9kC9JCnKVSDX2VrDgAPuzvNm3WccUIaDg==

validate_only

O

boolean

Indicates whether a message is a test message. The test message is only used to verify format validity and is not pushed to user devices. The options are as follows:

• true: test message
• false: formal message

The default value is false.

message

M

object

Message structure, which must contain the valid message payload and valid sending object. For details about the parameters, please refer to the definition in Message Structure.

data

O

string

Custom message payload. The value can be a JSON string for notification messages, and can be a common string or JSON string for data messages. Example: "your data" or "{'param1':'value1','param2':'value2'}"

• If the message body contains message.data and does not contain message.notification or message.android.notification, the message is a data message.
• If a data message is sent to a web app, the orignData field in the received data message indicates the content of the data message.

notification

O

object

Notification message content. For details about the parameters, please refer to the definition in Notification Structure.

android

O

object

Android message push control. For details about the parameters, please refer to the definition in AndroidConfig Structure.

This parameter is mandatory for Android notification messages.

apns

O

object

iOS message push control. For details about the parameters, please refer to the definition in ApnsConfig Structure.

This parameter is mandatory for iOS messages.

webpush

O

object

Web app message push control. For details about the parameters, please refer to the definition in WebPushConfig Structure.

This parameter is mandatory for web app notification messages.

token

O

list

Push token of the target user of a message. You must and only can set one of token, topic, and condition. Example: "token":["token1","token2"]

topic

O

string

Topic subscribed by the target user of a message. (Currently, this parameter applies only to Android apps.) You must and can only set one of token, topic, and condition.

condition

O

string

• Condition (topic combination expression) for sending a message to the target user. (Currently, this parameter applies only to Android apps.) You must and can only set one of token, topic, and condition.
• A Boolean expression of target topics can be specified to send messages based on a combination of condition expressions.
• Syntax and restrictions:
  • Boolean operation
    • &&: logical AND
    • ||: logical OR
    • !: logical NOT
    • (): priority control
    • in: keywords
  • Restrictions:

    A maximum of five topics can be included in the expression.

  • Example:

    "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

    The preceding expression indicates that messages are sent to devices that subscribe to topics A and B or topic C. Devices that subscribe to a single topic do not receive the messages.

title

M

string

Notification message title.

body

M

string

Notification message content.

image

O

string

URL of the custom large icon on the right of a notification message. If this parameter is not set, the icon is not displayed. The URL must be an HTTPS URL. Example: https://example.com/image.png

collapse_key

O

integer

Mode for the Push Kit server to cache messages sent to an offline device. These cached messages will be delivered once the device goes online again. The options are as follows:

• 0: Only the latest message sent by each app to the user device is cached.
• -1: All messages are cached.
• 1-100: message cache group ID. Messages are cached by group. Each group can cache only one message for each app.

  For example, if you send 10 messages and set collapse_key to 1 for the first five messages and to 2 for the rest, the latest message whose value of collapse_key is 1 and the latest message whose value of collapse_key is 2 are sent to the user after the user's device goes online.

The default value is -1.

ttl

O

string

Message cache time, in seconds. When a user device is offline, the Push Kit server caches messages. If the user device goes online within the message cache time, the messages are delivered. Otherwise, the messages are discarded. The default value is 86400 (1 day), and the maximum value is 1296000 (15 days).

bi_tag

O

string

Tag of a message in a batch delivery task. The tag is returned to your server when Push Kit sends the message receipt. Your server can analyze message delivery statistics based on bi_tag.

receipt_id

O

string

Unique receipt ID that associates with the receipt URL and configuration of the downlink message. You can find the receipt ID in Message Receipt.

fast_app_target

O

integer

State of a mini program when a quick app sends a data message. The options are as follows:

• 1: development state
• 2: production state

The default value is 2.

data

O

string

Custom message payload. If the data parameter is set, the value of the message.data field is overwritten.

notification

O

object

Android notification message structure. For details about the parameters, please refer to the definition in AndroidNotification Structure.

title

M

string

Title of an Android notification message. If the title parameter is set, the value of the message.notification.title field is overwritten. Before a message is sent, you must set at least one of title and message.notification.title.

body

M

string

Body of an Android notification message. If the body parameter is set, the value of the message.notification.body field is overwritten. Before a message is sent, you must set at least one of body and message.notification.body.

icon

O

string

Custom small icon on the left of a notification message. The icon file must be stored in the /res/raw directory of an app. For example, the value /raw/ic_launcher indicates the local icon file ic_launcher.xxx stored in /res/raw. Currently, supported file formats include PNG and JPG. For details about the custom small icon, please refer to Notification Icon Specifications.

color

O

string

Custom notification bar button color in #RRGGBB format, where RR indicates the red hexadecimal color, GG indicates the green hexadecimal color, and BB indicates the blue hexadecimal color. Example: #FFEEFF

sound

O

string

Custom message notification ringtone, which is valid during channel creation. The ringtone file must be stored in the /res/raw directory of an app. For example, the value /raw/shake indicates the local ringtone file /res/raw/shake.xxx stored in /res/raw. Currently, various file formats such as MP3, WAV, and MPEG are supported. If this parameter is not set, the default system ringtone will be used.

default_sound

O

boolean

Indicates whether to use the default ringtone. The options are as follows:

• true: The default ringtone is used.
• false: A custom ringtone is used.

tag

O

string

Message tag. Messages that use the same message tag in the same app will be overwritten by the latest message.

click_action

M

object

Message tapping action. For details about the parameters, please refer to the definition in ClickAction Structure.

This parameter is mandatory for Android notification messages.

body_loc_key

O

string

ID in a string format of the localized message body. For details, please refer to Notification Message Localization.

body_loc_args

O

list

Variables of the localized message body. For details, please refer to Notification Message Localization. Example: "body_loc_args":["1","2","3"]

title_loc_key

O

string

ID in a string format of the localized message title. For details, please refer to Notification Message Localization.

title_loc_args

O

list

Variables of the localized message title. For details, please refer to Notification Message Localization. Example:

"title_loc_args":["1","2","3"]

multi_lang_key

O

object

Multi-language parameter. body_loc_key and title_loc_key are read from multi_lang_key first. If they are not read from multi_lang_key, they will be read from the local character string of the APK. For details, please refer to Notification Message Localization.

A maximum of three languages can be set.

channel_id

O

string

Custom channel for displaying notification messages. Custom channels are supported in the Android O version or later. For details, please refer to Notification Channel Customization.

notify_summary

O

string

Brief description of a notification message to an Android app.

image

O

string

URL of the custom large icon on the right of a notification message. The function is the same as that of the message.notification.image field. If the image parameter is set, the value of the message.notification.image field is overwritten. The URL must be an HTTPS URL. Example: https://example.com/image.png

style

O

integer

Notification bar style. The options are as follows:

• 0: default style
• 1: large text
• 3: inbox style

big_title

O

string

Android notification message title in large text style. This parameter is mandatory when style is set to 1. When the notification bar is displayed after big_title is set, big_title instead of title is used.

big_body

O

string

Android notification message body in large text style. This parameter is mandatory when style is set to 1. When the notification bar is displayed after big_body is set, big_body instead of body is used.

auto_clear

O

integer

Message display duration, in milliseconds. Messages are automatically deleted after the duration expires.

notify_id

O

integer

Unique notification ID of a message. If a message does not contain the ID or the ID is -1, NC will generate a unique ID for the message. Different notification messages can use the same notification ID, so that new messages can overwrite old messages.

group

O

string

Message group. For example, if 10 messages that contain the same value of group are sent to a device, the device displays only the latest message and the total number of messages received in the group, but does not display these 10 messages.

badge

O

object

Android notification message badge control. For details about the parameters, please refer to the definition in BadgeNotification Structure.

ticker

O

string

Content displayed on the status bar after the device receives a notification message. Due to the restrictions of the Android native mechanism, the content will not be displayed on the status bar on the device running Android 5.0 (API level 21) or later even if this field is set.

when

O

string

Time when Android notification messages are delivered, in the UTC timestamp format. If you send multiple messages at the same time, they will be sorted based on this value and displayed in the Android notification panel. Example: 2014-10-02T15:01:23.045123456Z

importance

O

string

Android notification message priority, which determines the message notification behavior of a user device. The options are as follows:

• LOW: low-priority (silent) message
• NORMAL: medium-priority message

use_default_vibrate

O

boolean

Indicates whether to use the default vibration mode.

use_default_light

O

boolean

Indicates whether to use the default breathing light mode.

vibrate_config

O

list

Custom vibration mode for an Android notification message. Each array element adopts the format of [0-9]+|[0-9]+[sS]|[0-9]+[.][0-9]{1,9}|[0-9]+[.][0-9]{1,9}[sS], for example, ["3.5S","2S","1S","1.5S"]. A maximum of ten array elements are supported. The value of each element is an integer ranging from 1 to 60. EMUI 11 is not supported. Example: "vibrate_config":["1","3"]

visibility

O

string

Android notification message visibility. The options are as follows:

• VISIBILITY_UNSPECIFIED: The visibility is not specified. This value is equivalent to PRIVATE.
• PUBLIC: The content of a received notification message is displayed on the lock screen.
• SECRET: A received notification message is not displayed on the lock screen.
• PRIVATE: If you have set a lock screen password and enabled Hide notification content under Settings > Notifications, the content of a received notification message is hidden on the lock screen.

light_settings

O

object

Custom breathing light color. For details about the parameters, please refer to the definition in LightSettings Structure.

foreground_show

O

boolean

Indicates whether to display notification messages in the foreground when an app is running in the foreground. For details, please refer to Notification Message Display for Apps Running in the Foreground.

profile_id

O

string

ID of the user-app relationship. The value contains a maximum of 64 characters.

inbox_content

O

list

Content in inbox style. A maximum number of five content records are supported and each record can contain at most 1024 characters. This parameter is mandatory when style is set to 3. For details about the display effect, please refer to Inbox Style. Example: "inbox_content":["content1","content2","content3"]

buttons

O

object

Action buttons of a notification message. A maximum of three buttons can be set. For details about the parameters, please refer to the definition in Button Structure. Example: "buttons":[{"name":"Open app","action_type":"1"}]

name

M

string

Button name, which cannot exceed 40 characters.

action_type

M

integer

Button action. The options are as follows:

• 0: Open the app home page
• 1: open a custom app page
• 2: open a specified web page
• 3: delete a notification message
• 4: share a notification message (this action is supported only on Huawei device)

intent_type

O

integer

Method of opening a custom app page. The options are as follows:

• 0: open the page through intent
• 1: open the page through action

This parameter is mandatory when action_type is set to 1.

intent

O

string

• When action_type is set to 1, set this parameter to an action or the URI of the app page to be opened based on the value of intent_type. For details, please refer to Opening a Specified Page of an App.
• When action_type is set to 2, set this parameter to the URL of the web page to be opened. The URL must be an HTTPS URL. Example: https://example.com/image.png

data

O

string

The maximum length is 1024 characters.

• When action_type is set to 0 or 1, this parameter is used to transparently transmit data to an app after a button is tapped. The parameter is optional and its value must be key-value pairs in format of {"key1":"value1","key2":"value2",...}.
• When action_type is set to 4, this parameter indicates content to be shared and is mandatory.

type

M

integer

Message tapping action type. The options are as follows:

• 1: tap to open a custom app page
• 2: tap to open a specified URL
• 3: tap to start the app

intent

O

string

For details about intent implementation, please refer to Setting the intent Parameter.

When type is set to 1, you must set at least one of intent and action.

url

O

string

• URL to be opened. The URL must be an HTTPS URL. Example: https://example.com/image.png
• This parameter is mandatory when type is set to 2.

action

O

string

Action corresponding to the activity of the page to be opened when the custom app page is opened through the action.

When type is set to 1 (open a custom page), you must set at least one of intent and action.

add_num

O

integer

Accumulative badge number, which is an integer ranging from 1 to 99.

For example, a user has N unread messages on an app. If add_num is set to 3, the number displayed on the app badge increases by 3 each time a message that contains add_num is received, that is, N+3.

class

M

string

Full path of the app entry activity class.

Example: com.example.hmstest.MainActivity

set_num

O

integer

Badge number, which is an integer ranging from 0 to 99.

For example, if set_num is set to 10, the number displayed on the app badge is 10 no matter how many messages are received.

If both set_num and add_num are set, the value of set_num prevails.

color

M

object

Breathing light color. This parameter is mandatory when light_settings is set. For details about the parameters, please refer to the definition in Color Structure.

light_on_duration

M

string

Interval when a breathing light is on, in the format of \d+|\d+[sS]|\d+.\d{1,9}|\d+.\d{1,9}[sS]. This parameter is mandatory when light_settings is set.

light_off_duration

M

string

Interval when a breathing light is off, in the format of \d+|\d+[sS]|\d+.\d{1,9}|\d+.\d{1,9}[sS]. This parameter is mandatory when light_settings is set.

alpha

O

float

Alpha setting of the RGB color. The default value is 1, and the value range is [0, 1].

red

O

float

Red setting of the RGB color. The default value is 0, and the value range is [0, 1].

green

O

float

Green setting of the RGB color. The default value is 0, and the value range is [0, 1].

blue

O

float

Blue setting of the RGB color. The default value is 0, and the value range is [0, 1].

headers

O

object

APNs message headers. For details about the parameters, visit the APPLE Developer website.

payload

M

object

APNs message payload. If title and body are set in the message payload, the values of the message.notification.title and message.notification.body fields are overwritten. Before a message is sent, you must set at least one of title and body and at least one of message.notification.title and message.notification.body.

For details about the parameters, visit the APPLE Developer website.

hms_options

M

object

HMS parameter for APNs. For details about the parameter, please refer to the definition in ApnsConfig.HmsOptions Structure.

target_user_type

M

integer

Target user type. The options are as follows:

• 1: test user
• 2: formal user
• 3: VoIP user

headers

O

object

Headers of a message sent through the WebPush agent. For details about the parameters, please refer to the definition in Headers Structure.

notification

O

object

Structure of a notification message sent through the WebPush agent. For details about the parameters, please refer to the definition in WebNotification Structure.

hms_options

O

object

WebPush agent parameter. For details about the parameter, please refer to the definition in WebPushConfig.HmsOptions Structure.

ttl

O

string

Message cache time, in seconds, for example, 20, 20s, or 20S.

topic

O

string

Message ID, which can be used to overwrite undelivered messages.

title

O

string

Title of a web app notification message. If the title parameter is set, the value of the message.notification.title field is overwritten. Before a message is sent, you must set at least one of title and message.notification.title.

body

O

string

Body of a web app notification message. If the body parameter is set, the value of the message.notification.body field is overwritten. Before a message is sent, you must set at least one of body and message.notification.body.

icon

O

string

Small icon URL.

image

O

string

Large image URL.

lang

O

string

Language

tag

O

string

Notification message group tag. Multiple same tags are collapsed and the latest one is displayed. This function is used only for mobile phone browsers.

badge

O

string

Browser icon URL, which only applies to mobile phone browsers and is used to replace the default browser icon.

dir

O

string

Text direction. The options are as follows:

• auto: from left to right (default value)
• ltr: from left to right
• rtl: from right to left

vibrate[]

O

integer

Vibration interval, in milliseconds. Example: [100,200,300]

renotify

O

boolean

Message reminding flag.

require_interaction

O

boolean

Indicates that notification messages should remain active until a user taps or closes them.

silent

O

boolean

Message sound-free and vibration-free reminding flag.

timestamp

O

Long

Standard Unix timestamp.

actions[]

O

object

Message action. For details about the parameters, please refer to the definition in WebActions Structure.

action

O

string

Action name.

icon

O

string

URL for the button icon of an action.

title

O

string

Title of an action.

link

O

string

Default URI for redirection when no action is performed.