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