Documentation | Tencent Cloud

Recent Pages

Push API

Last updated: 2021-04-22 16:52:56

API Description

Request method: POST

Service URL/v3/push/app

API service URLs correspond to service access points one by one. Please select the service URL corresponding to the service access point of your application.

Feature: Push API is the general term for all push APIs. Push API supports different push targets, as described below.
All request parameters are JSON encapsulated and uploaded to the backend, which differentiates push targets based on the request parameters. If an error code is returned, see Server Error Codes.

Required Parameters

The required push parameters refer to the parameters that must be carried in a push message.

Parameter	Type	Required	Description
audience_type	String	Yes	Push target. Valid values: all: push to all devices tag: push to devices with specified tags token: push to a single device token_list: push to a list of devices account: push to a single account account_list: push to a list of accounts package_account_push: push by account package package_token_push: push by token package
message	Object	Yes	Message body. For more information, please see message body type
message_type	String	Yes	Message type. Valid values: notify: notification message: in-app message/silent message
environment	String	Yes (only for iOS)	Push environment (only available for pushes on iOS). Valid values: product: production environment dev: development environment
upload_id	Integer	Yes (only available for account package push/token package push)	Account/token package upload ID

audience_type: push target

Push target indicates which devices a push can be delivered to.
Push API supports a variety of push targets. For example, you can push to all devices, devices with specified tags, a single device, a list of devices, a single account, or a list of accounts.

Push Target	Description	Required Parameters and Instructions
all	Push to all devices	None
tag	Push to devices with specified tags	`tag_rules` (recommended): Push by a combination of tags. You can set 'AND', 'OR' and 'NOT' rules. Note: if both `tag_rules` and `tag_list` are specified, `tag_list` becomes invalid automatically. For parameter descriptions, see Tag combination rules. `tag_list` (no further updates): Push to devices with tag1 and tag2 `{"tags":["tag1","tag2"],"op":"AND"}` Push to devices with tag1 or tag2 `{"tags":["tag1","tag2"],"op":"OR"}` A tag list cannot exceed 512 characters.
token	Push to a single device	`token_list` If the parameter contains multiple tokens, messages are pushed only to the first token. Format example: ["token1"] A token string cannot exceed 36 characters.
token_list	Push to a list of devices	`token_list` Up to 1,000 tokens Format example: ["token1","token2"] A token string cannot exceed 36 characters. Note: if the token list contains more than 1,000 tokens, the push will fail. To push messages to more than 1,000 tokens, you are recommended to use the Token Package Upload API.
account	Push to a single account	`account_list` If the parameter contains multiple accounts, messages are pushed only to the first account. Format example: ["account1"]
account_list	Push to a list of accounts	`account_list` Up to 1,000 accounts Format example: ["account1","account2"] Note: if the account list contains more than 1,000 accounts, the push will fail. To push messages to more than 1,000 accounts, you are recommended to use the Account Package Upload API.
package_account_push	Push by account package	Required for uploading the account package to push
package_token_push	Push by token package	Required for uploading the token package to push

Push to all devices

  {
    "audience_type": "all"
  }

Push to devices with specified tags (using tag_rules): push to male users who were active on April 8, 2020 in Guangdong or Hunan province

 {
  "audience_type": "tag",
  "tag_rules": [
        {
            "tag_items": [
                {
                    "tags": [
                        "guangdong",
                        "hunan"
                    ],
                    "is_not": false,   
                    "tags_operator": "OR",  
                    "items_operator": "OR", 
                    "tag_type": "xg_auto_province" 
                },
                {
                    "tags": [
                        "20200408"
                    ],
                    "is_not": false,
                    "tags_operator": "OR",
                    "items_operator": "AND",
                    "tag_type": "xg_auto_active"
                },
                {
                    "tags": [
                        "male"
                    ],
                    "is_not": false,
                    "tags_operator": "OR",
                    "items_operator": "AND",
                    "tag_type": "xg_user_define"
                }
            ],
            "operator": "OR", 
            "is_not": false  
        }
    ]
}

Push to a single device: push to the device with token1 as the token

  {
    "audience_type": "token",
    "token_list": [
        "token1"
    ]
  }

Push to a list of devices: push to devices with token1 and token2 as their tokens

  {
    "audience_type": "token_list",
    "token_list": [
        "token1",
        "token2"
    ]
  }

Push to a single account: push to the device bound to account1

  {
    "audience_type": "account",
    "account_list": [
        "account1"
    ]
  }

Push to a list of accounts: push to devices bound to account1 and account2

  {
    "audience_type": "account_list",
    "account_list": [
        "account1",
        "account2"
    ]
  }

message_type: message type

The message types may vary slightly depending on the platform. For more information, see the table below:

Message Type