Intelligent Assistant
Chat with our virtual assistant to get answers promptly.
Sending Messages
Content overview
1. API Information
Function: You can call the API to send push messages.
Restriction: The message body cannot exceed 4096 bytes(excluding token). When messages are sent by token, the maximum number of tokens cannot exceed 1000 (specified by the current system parameter).
2. Prototype
Protocol | HTTPS POST |
Direction | App server -> HUAWEI Push Kit server |
URL | https://push-api.cloud.huawei.com/v1/[appid]/messages:send |
3. Parameters
Request Parameters (HTTP Header)
Parameter | Description | Example |
Authorization | For details, please refer to Open Platform Authentication - Client Password Mode. Notice: A space character must be added between Bearer and the value of access_token. | Bearer CF3Xl2XV6jMKZgqYSZFws9IPlgDvxqOfFSmrlmtkTRupbU2VklvhX9kC9JCnKVSDX2VrDgAPuzvNm3WccUIaDg== |
Request Parameters (HTTP Body)
Parameter | Type | Mandatory (M)/Optional (O) | Description |
validate_only | boolean | O | 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 | object | M | Push message structure. The message structure must contain the valid message payload and valid sending object. For details about the fields, please refer to the table of Message Structure definition. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
data | string | O | Custom message payload, which can be a common string or a string in JSON format. 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 user sends a data message from a web app, the orignData field in the received data message indicates the content of the data message. |
notification | object | O | Notification message content. For details about the fields, please refer to the table of Notification Structure definition. |
android | object | O | Android push message control. For details about the fields, please refer to the table of AndroidConfig Structure definition. This parameter is mandatory for Android notification messages. |
apns | object | O | iOS push message control. For details about the fields, please refer to the table of ApnsConfig Structure definition. This parameter is mandatory for iOS messages. |
webpush | object | O | Web app push message control. For details about the fields, please refer to the table of WebPushConfig Structure definition. This parameter is mandatory for web app notification messages. |
token[] | string | O | Push token of the target user of a message. You must set one of token, topic, and condition. Example: ["pushtoken1","pushtoken2"] |
topic | string | O | Topic subscribed by the target user of a message. (Currently, this parameter only applies to Android apps). You must set one of token, topic, and condition. |
condition | string | O | Condition (topic combination expression) for sending a message to the target user. (Currently, this parameter applies only to Android apps.) You must 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: 1. Boolean operation '&&': logical AND '||': logical OR '! ': logical negative '()': priority control 'in': keywords 2. Restrictions A maximum of five topics can be included in a condition expression. 3. 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. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
title | string | M | Notification message title. |
body | string | M | Notification message content. |
image | string | O | The URL of 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 |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
collapse_key | integer | O | Mode for the HUAWEI Push Kit server to control messages cached in user offline status. These cached messages will be delivered once the user device goes online again. The options are as follows: 0: Only the latest offline message sent by each app to the user device is cached. -1: All offline messages are cached. 1-100: Offline message cache group ID. Offline messages are cached by group. Each group can cache only one offline 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 offline message whose value of collapse_key is 1 and the latest offline message whose value of collapse_key is 2 are sent to the user. |
urgency | string | O | Delivery priority of a data message. The options are as follows: HIGH NORMAL You need to apply for the permission when setting the parameter to HIGH, in which the app process can be forcibly started when a data message reaches a user's mobile phone. Please refer to FAQs. |
category | string | O | Scenario where a high-priority data message is sent. Currently, this parameter can only be set to PLAY_VOICE (voice playing) and additional permission is required. Please refer to FAQs. |
ttl | string | O | Message cache time, in seconds. When a user device is offline, the HUAWEI 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 | string | O | Tag of a message in a batch delivery task. The tag is returned to the app server when HUAWEI Push Kit sends the message receipt. The app server can analyze message delivery statistics based on bi_tag. |
fast_app_target | integer | O | State of a mini program when a quick app sends a data message. The options are as follows: 1: development state. 2: production state (default value). |
data | string | O | Custom message payload. If the data parameter is set, the value of the message.data field is overwritten. |
notification | object | O | Android notification message structure. For details about the fields, please refer to the table of AndroidNotification Structure definition. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
title | string | M | Android notification message title. 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 | string | M | Android notification message body. 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 | string | O | Customized 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 specifications of the custom small icon, please refer to Notification Icon Specifications. |
color | string | O | Custom notification bar button colors in the #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 | string | O | Customized 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. Note: The ringtone is an attribute of the notification channel. Therefore, a ringtone is valid only if it is set during channel creation. If a ringtone is set after the channel is created, it will not be played and the one set during channel creation is played instead. |
default_sound | boolean | O | 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 | string | O | Message tag. Messages that use the same message tag in the same app will be overwritten by the latest message. |
click_action | object | M | Message tapping action. For details about the fields, please refer to the table of ClickAction Structure definition. This parameter is mandatory for Android notification messages. |
body_loc_key | string | O | ID in a string format of the localized message body. For details, please refer to Notification Message Localization. |
body_loc_args[] | string | O | Variable parameter of the localized message body. For details, please refer to Notification Message Localization. Example: ["args1","args2"] |
title_loc_key | string | O | ID in a string format of the localized message title. For details, please refer to Notification Message Localization. |
title_loc_args[] | string | O | Variable parameter of the localized message title. For details, please refer to Notification Message Localization. Example: ["args1","args2"] |
multi_lang_key | object | O | Message in multiple languages. 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 | string | O | Customized channel for displaying notification messages. Customized channels are supported in the Android O version or later. For details, please refer to Customized Notification Channel. |
notify_summary | string | O | Brief description of an Android notification message. |
image | string | O | The URL of custom large icon on the right of an Android 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 | integer | O | Notification bar style. The options are as follows: 0: default style. 1: bigText. 3: inbox style. |
big_title | string | O | Android notification message title in bigText 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 | string | O | Android notification message body in bigText 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 | integer | O | Message display duration, in milliseconds. Messages are automatically deleted after the duration expires. |
notify_id | integer | O | 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 | string | O | Message group. For example, if 10 messages are sent and the group parameter of the messages is set to 10, only one message is displayed in the notification bar of the mobile phone. |
badge | object | O | Android notification message badge control. For details about the fields, please refer to the table of BadgeNotification Structure definition. |
ticker | string | O | 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. |
auto_cancel | boolean | O | Indicates whether an Android notification message is not still displayed in the notification bar after a user taps the message. The options are as follows: true: Yes. false: No. This value requires additional permission from Huawei. Please refer to FAQs. |
when | string | O | Message sorting event. Android notification messages are sorted based on this value. This event is displayed in the notification bar. For example: 2014-10-02T15:01:23.045123456Z |
importance | string | O | Android notification message priority, which determines the message notification behavior of a user device. The options are as follows: LOW: common (silent) message NORMAL: important message HIGH: very important message |
use_default_vibrate | boolean | O | Indicates whether to use the default vibration mode. |
use_default_light | boolean | O | Indicates whether to use the default breath light mode. |
vibrate_config[] | string | O | 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 0 to 60. |
visibility | string | O | Android notification message visibility. The options are as follows: VISIBILITY_UNSPECIFIED PRIVATE PUBLIC SECRET For details about the options, please refer to Notification Content Hiding on the Lock Screen. |
light_settings | object | O | Custom breath light mode. For details about the fields, please refer to the table of LightSettings Structure definition. |
foreground_show | boolean | O | Indicates whether to display notification messages on the foreground when an app is running on the foreground.Please refer to Notification Message Display on UI. |
inbox_content[] | string | O | 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. |
buttons[] | object | O | 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. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
name | string | M | Button name, which is mandatory and cannot exceed 40 characters. |
action_type | integer | M | Button action. The options are as follows: 0: Open the app home page. 1: Open a specified app page. 2: Open a specified web page. 3: Delete a notification message. 4: Share a notification message. |
intent_type | integer | O | Method of opening a customized 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 | string | O | When action_type is set to 1, set this parameter to an action or the URL 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 | string | O | The maximum length is 1024 characters. When action_type is set to 0 or 1, this parameter is used to transparently transfer 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. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
type | integer | M | Message tapping action type. The options are as follows: 1: custom tapping action. 2: tap to open a specified URL. 3: tap to start the app. 4: tap to access rich media information. |
intent | string | O | For details about intent implementation on a custom page, please refer to Opening a Specified Page of an App. When type is set to 1, you must set at least one of intent and action. |
url | string | O | URL to be opened. The value must be an HTTPS URL, example: https://example.com/image.png. This parameter is mandatory when type is set to 2. |
rich_resource | string | O | URL of a rich media resource to be opened. The value must be an HTTPS URL. Rich media is a self-contained HTML resource package in .zip format. This parameter is mandatory when type is set to 4. |
action | string | O | 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, you must set at least one of intent and action. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
add_num | integer | M | Accumulative badge number, which is an integer ranging from 1 to 99. |
class | string | M | Class name in APK name + App entry activity format. For example: com.huawei.codelabpush.MainActivity |
set_num | integer | M | Set badge number, which is an integer ranging from 0 to 99. If add_num and set_num exist at the same time, set_num is valid. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
color | object | M | Breath light color. This parameter is mandatory when light_settings is set. For details about the fields, please refer to the table of Color structure definition. |
light_on_duration | string | M | Interval when a breath 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 | string | M | Interval when a breath 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. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
alpha | float | O | Alpha setting of the RGB color. The default value is 1, and the value range is [0,1]. |
red | float | O | Red setting of the RGB color. The default value is 0, and the value range is [0,1]. |
green | float | O | Green setting of the RGB color. The default value is 0, and the value range is [0,1]. |
blue | float | O | Blue setting of the RGB color. The default value is 0, and the value range is [0,1]. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
headers | object | O | APNs message header. For details about the fields, visit the APPLE Developer website. |
payload | object | M | 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 fields, visit the APPLE Developer website. |
hms_options | object | M | HMS parameter for APNs. For details about the fields, please refer to the table of ApnsConfig.HmsOptions Structure definition. |
ApnsConfig.HmsOptions Structure
Parameter | Type | Mandatory (M)/Optional (O) | Description |
target_user_type | integer | M | Target user type. The options are as follows: 1: test user. 2: formal user. 3: VoIP user. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
headers | object | O | WebPush message header. For details about the fields, please refer to the table of Headers Structure definition. |
notification | object | O | WebPush notification message structure. For details about the fields, please refer to the table of WebNotification Structure definition. |
hms_options | object | O | WebPush agent parameter. For details about the fields, please refer to the table of WebPushConfig.HmsOptions Structure definition. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
ttl | string | O | Message cache time, in seconds, for example, 20, 20s, or 20S. |
topic | string | O | Message ID, which can be used to overwrite undelivered messages. |
urgency | string | O | Message emergency level. The value can only be very-low, low, normal, or high. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
title | string | O | 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 | string | O | 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 | string | O | Small icon URL. |
image | string | O | Large image URL. |
lang | string | O | Language. |
tag | string | O | 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 | string | O | Browser icon URL, which only applies to mobile phone browsers and is used to replace the default browser icon. |
dir | string | O | Text direction, which can be set to auto, ltr, or rtl. |
vibrate[] | integer | O | Vibration interval, in milliseconds. The value is an integer by default. The value range is [100,200,300]. |
renotify | boolean | O | Message reminding flag. |
require_interaction | boolean | O | Indicates that notification messages should remain active until a user taps or closes them. |
silent | boolean | O | Message sound-free and vibration-free reminding flag. |
timestamp | Long | O | Sending timestamp. |
actions[] | object | O | Message action. For details about the fields, please refer to the table of WebActions Structure definition. |
Parameter | Type | Mandatory (M)/Optional (O) | Description |
action | string | O | Action name. |
icon | string | O | URL for the button icon of an action. |
title | string | O | Title of an action. |
WebPushConfig.HmsOptions Structure
Parameter | Type | Mandatory (M)/Optional (O) | Description |
link | string | O | Default URL for redirection when no action is performed. |
Response Parameters
Parameter | Type | Description |
code | string | Result code. |
msg | string | Result code description. |
requestId | string | Request ID. |
Response example:
- {
- "code": "80000000",
- "msg": "Success",
- "requestId": "157440955549500001002006"
- }
4. API Result Codes
HTTP Status Code | Description | Solution |
200 | OK | N/A |
400 | Incorrect parameter. | Check the status code in the response and rectify the fault based on the status code. |
401 | Authentication failed. | Check the access token in the Authorization parameter in the request HTTP header. |
404 | Service not found. | Check whether the request URL is correct. |
500 | Internal service error. | Contact Huawei technical support. |
Service Result Code | Description | Solution |
80000000 | Success. | N/A |
80100000 | Some tokens are successfully sent. Tokens identified by illegal_token are those failed to be sent. | Check these tokens in the return value. |
80100001 | Some token parameters are incorrect. | Check the token parameters as prompted in the response. |
80100002 | The number of tokens must be 1 when a synchronization message is sent. | Check the token field in the request. |
80100003 | Incorrect message structure. | Check the parameters in the message structure as prompted in the response. |
80100004 | The message expiration time is earlier than the current time. | Check the message field ttl. |
80100013 | The collapse_key message field is invalid. | Check the message field collapse_key. |
80100016 | The message contains sensitive information. | Check whether the message contains sensitive words. Please refer to FAQs. |
80200001 | OAuth authentication error. | The access token in the Authorization parameter in the request HTTP header failed to be authenticated. Ensure that the access token is correct. |
80200003 | OAuth token expired. | The access token in the Authorization parameter in the request HTTP header expired. Apply for a new access token. |
80300002 | The current app does not have the permission to send push messages. | Check the push message sending permission of the current app. Please refer to FAQs. |
80300007 | All tokens are invalid. | Check the push token parameters. Please refer to FAQs. |
80300008 | The message body size exceeds the default value. | Reduce the message body size. |
80300010 | The number of tokens in the message body exceeds the default value. | Reduce the number of tokens and send them in batches. |
80300011 | You are not authorized to send high-priority notification messages. | Related permissions must be applied for. Please refer to FAQs. |
81000001 | System internal error. | Contact Huawei technical support of HUAWEI Push Kit. |
Search
Enter a keyword.