Push interface

Last updated: 2020-03-31 11:52:53

PDF

Interface description

Request method : POST .

https://api.tpns.tencent.com/v3/push/app

Interface function : Push API is the general name for all push interfaces. Push API has a variety of push targets. See below.
All request parameters are uploaded to Backend Background through JSON encapsulation, and Backend Background uses the request parameters to distinguish different push targets. If you have any questions, please see Server error code .

Parameter description

Request parameter

Necessary parameters

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

Parameter name Type Is it necessary? Description
Audience_type String Yes Push destination:
  • Full push of all:
  • Tag: tag push
  • Token: single Device push
  • Token_list: Device list push
  • Account: single account push
  • Account_list: account list push
  • Message Object Yes Message body, see [Message body type](#Message body type)
    Message_type String Yes Message type:
  • Notify: Notification
  • Message: pass through message / Silent message
  • Environment String Yes (iOS platform only) User-specified push environment, which is only available for iOS platform push:
  • Product: push production environment
  • Dev: push development environment
  • Upload_id Int32 Yes (for number packet push only) Number package upload ID

    Audience_type: push target

    Push target indicates which devices a push can be delivered to.

    Push API provides a variety of push targets, such as full volume, tags, single Device, Device list, single account, account list.

    Push target Description Required parameters and instructions for use
    ALL Full push None
    tag Label push tag_list
  • Device who pushes tag1 and tag2 {"tags":["tag1","tag2"],"op":"AND"}
  • Device who pushes tag1 or tag {"tags":["tag1","tag2"],"op":"OR"}
  • Label list cannot exceed 512 characters
  • Token Single Device push token_list
  • If this parameter contains more than one token, only the first token will be pushed.
  • Format eg: [ "token1"]
  • Token string length cannot exceed 36
  • Token_list Device list group tweets token_list
  • Up to 1000 token
  • Format eg: [ "token1", "token2"]
  • Token string length cannot exceed 36
  • File ext Single account push account_list
  • When there are multiple accounts for this parameter, only the first account is pushed.
  • Format eg: [ "account1"]
  • Account_list Account list group tweets account_list Up to 1000 account2. Format eg: [ "account1", "account2"]
    Package_account_push Number packet push Upload number package push required
    • Full push: push to all Device

      {
        "audience_type": "all"
      }
    • Tag push: push to Device with both tag1 and tag2 tags

      {
        "audience_type": "tag",
        "tag_list": {
            "tags": [
                "tag1",
                "tag2"
            ],
            "op": "AND"
        }
      }
    • Single Device push: push to Device whose token is token1

      {
        "audience_type": "token",
        "token_list": [
            "token1"
        ]
      }
    • Device list push, push to Device whose token is token1 and token2

      {
        "audience_type": "token_list",
        "token_list": [
            "token1",
            "token2"
        ]
      }
    • Single account push: push to Device with account account1

      {
        "audience_type": "account",
        "account_list": [
            "account1"
        ]
      }
    • Account list push: push Device with account account1 and account2

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

    Message_type: message body type

    For different platforms, the message types are slightly different; for details, see the table below:

    Message Type Description Support platform Property description
    Notify Notification bar message Android & iOS The notification bar displays messages.
    Message Pass through message / Silent message Android (news from pass through)
    IOS (silent message)
    Notice column does not display news due to Vendor restrictions, Android pass through news only through Client's channel deliver, can not pass Vendor channel deliver

    Message: message body

    The message body, i.e., the message delivered to the client.

    Push API handles messages on iOS and Android differently, so you need to implement the push message on the corresponding platform separately. The body of the pushed message is in JSON format.

    Android normal message

    The specific fields of Android platform are shown in the following table:

    Field name Type Parent project Default Value Necessary Parameter description
    Title String Message None Yes Message title
    Content String Message None Yes Message content
    Accept_time JsonArray Message None No When the message will be allowed to be pushed to the user. A single element consists of a start and end time pair composed of "start" and "end". "start" and "end" are described by hour (hours) and min (minutes). Refer to specific examples in detail. Due to the restriction of Vendor, it is only valid for Client's and channel.
    Xg_media_resources String Message None No The address of the rich media element of the picture cannot be pushed through Vendor, channel and deliver due to the restriction of Vendor, but all through Client's, channel and deliver.
    Xg_media_audio_resources String Message None No Audio rich media element address. Audio in mp3 format is supported. The recommended size is less than 5m.
    Due to Vendor's restrictions, including rich media, the push cannot be passed by Vendor, channel, deliver, all through Client's, channel and deliver.
    Android JSON Message None No Android notifies the advanced setting structure. Please refer to the Android structure description.

    Android structure description

    Field name Type Parent project Default Value Necessary Parameter description
    N_id Int Android * 2018-5-4 No Unique identity of the notification message object (effective only for TPNS channel)
  • Greater than 0: messages with the same ID are overwritten
  • Equal to 0: display this notice without affecting other messages
  • Equal to-1: all previous messages will be cleared and only this message will be displayed
  • Builder_id Int Android * 2018-5-4 No Local notification style identification
    Ring Int Android 1 No Is there a ringtone?
  • 0: no ringtone
  • 1: there is a bell
  • Ring_raw String Android None No Specify the ringtone file name in raw Directory in the Android project. No suffix is required.
    Vibrate Int Android 1 No Whether to use vibration
  • 0: no vibration
  • 1: there is a vibration
  • Lights Int Android 1 No Whether or not to use a breathing lamp
  • 0: do not use breathing lights
  • 1: use breathing lights
  • Clearable Int Android 1 No Whether the notification bar can be cleared
    Icon_type Int Android * 2018-5-4 No Is the notification bar icon an in-application icon or an upload icon?
  • 0: icon in the application
  • 1: upload icon
  • Icon_res String Android None No The file name of the icon in the application or the url address of the download icon
    Style_id Int Android 1 No Sets whether to override the notification style with the specified number
    Small_icon String Android None No The icon that the message displays in the status bar. If not set, the application icon is displayed.
    Action JSON Android Yes No Set the behavior after clicking on the notification bar. The default is to open App.
    Action_type Int Action Yes No Click the action type,
  • 1: open activity or App itself
  • 2: open the browser
  • 3: open Intent
  • Custom_content String Android None No For the user-defined parameters, you need to serialize them to json string.

    Below is an example of a complete message:

    {
        "title": "xxx",
        "content": "xxxxxxxxx",
        "xg_media_resources": "xxx1" , //Enter the rich media element address, such as https://www.xx.com/img/bd_logo1.png?qua=high
        "xg_media_audio_resources":"xxx", //Enter the audio rich media element address, such as http://sc1.111ttt.cn/2018/1/03/13/396131227447.mp3 
        "accept_time": [
            {
                "start": {//Period start time,
                    "hour": "13",//Start time, hours, value [0:24)
                    "min": "00"//  Start time, minutes, value [0:60)
                },
                "end": {//Period end time
                    "hour": "14",//End time, hours, value [0:24)
                    "min": "00" //End time, minutes, value [0:60)
    
                }
            },
            {
                "start": {
                    "hour": "00",
                    "min": "00"
                },
                "end": {
                    "hour": "09",
                    "min": "00"
                }
            }
        ],
        "android": {
            "n_id": 0,
            "builder_id": 0,
            "ring": 1,
            "ring_raw": "ring",
            "vibrate": 1,
            "lights": 1,
            "clearable": 1,
            "icon_type": 0,
            "icon_res": "xg",
            "style_id": 1,
            "small_icon": "xg",
            "action": {
                "action_type": 1,//  Action type; 1. Open activity or app; 2. Open browser; 3. Open Intent
                "activity": "xxx",
                "aty_attr": {// activity attribute, only for action_type=1
                    "if": 0, // Intent's Flag attribute
                    "pf": 0  //PendingIntent's Flag attribute
                },
                "browser": {
                    "url": "xxxx ", // Only http and https are supported
                    "confirm": 1 // Whether user confirmation is required
                },
                "intent": "xxx" //The SDK version must be 1.0.9 or higher. Configure the data tag in the client's intent and set the scheme attribute
            },
          "custom_content":"{\"key\":\"value\"}"
        }
    }

    IOS normal message

    The specific fields of iOS platform are shown in the following table:

    Field name Type Parent project Default Value Necessary Parameter description
    Ios JSON Message None Yes IOS message structure, please refer to the iOS field description
    Xg_media_resources Array Message None No Rich media element address
    Xg String Message None No The use of key, reserved in the system should be avoided.

    Ios field description

    Field name Type Parent project Default Value Necessary Parameter description
    Aps JSON Ios None Yes For more information on the message body fields specific to Apple's push service (APNs), please see Payload
    Alert JSON Aps None Yes Contains the title and message content
    Badge_type Int Aps None No The number of corner marks displayed by App
    Category String Aps None No The action ID displayed when the message is pulled down
    Mutable-content Int Aps None No Notify the extension parameter. Push with "mutable-content": 1 indicates that when the Service Extension, that supports iOS10 is enabled, the arrival data will be reported in the push details. Before using this feature, please develop the corresponding module according to the integrated documentation. If you do not carry this field, the arrival data will not be reported.
    Sound String Aps None No The usage of the sound field is as follows:
    1: Playback system default prompt tone, "sound": "default"
    2: Playback local custom ringtone, "sound": "chime.aiff"
    3: mute effect, "sound": "or remove the sound field to customize the ringtone description: the format must be Linear PCM, MA4 (IMA/ADPCM), alaw, μ Law, and put the audio file into the project bundle Directory, and the duration is required to be less than 30s, otherwise it is the default ringtone of the system.
    Custom_content String Ios None No Custom parameters of deliver need to be serialized to json string

    Below is an example of a complete message:

    {
        "title": "xxx",
        "content": "xxxxxxxxx",
        "ios":{
            "aps": {
                "alert": {
                    "subtitle": "my subtitle"
                },
                "badge_type": 5,
                "category": "INVITE_CATEGORY",
                "sound":"default",
                "mutable-content":1
            },
           "custom_content":"{\"key\":\"value\"}",
            "xg": "oops"
        }
    }

    Android pass through news

    Pass through messages, unique to the Android platform, that is, messages that are not displayed in the mobile phone notification bar, can be used to enable users imperceptible to send a controlling message to App deliver.

    Due to Vendor restrictions, Android pass through news only through Client's channel deliver, can not pass Vendor channel deliver.

    The specific fields of Android platform are shown in the following table:

    Field name Type Parent project Default Value Is it necessary? Parameter description
    Title String Message None Yes Command description
    Content String Message None Yes Command content
    Android JSON Message None No Android message structure
    Custom_content String Android None No Need to serialize to json string
    Accept_time Array Message None No When the message will be allowed to be pushed to the user. A single element consists of a start and end time pair composed of "start" and "end". "start" and "end" are described by hour (hours) and min (minutes). Refer to specific examples in detail. Due to the restriction of Vendor, it is only valid for Client's and channel.

    Complete example:

    {
        "title": "this is title",
        "content": "this is content",
        "android": {
          "custom_content":"{\"key\":\"value\"}"
        },
        "accept_time": [
            {
                "start": {
                    "hour": "13",
                    "min": "00"
                },
                "end": {
                    "hour": "14",
                    "min": "00"
                }
            },
            {
                "start": {
                    "hour": "00",
                    "min": "00"
                },
                "end": {
                    "hour": "09",
                    "min": "00"
                }
            }
        ]
    }

    IOS silent messa

    Silent messages are unique to iOS platform, similar to pass through messages in Android. Messages are not displayed. When silent messages arrive at the terminal, iOS will wake up App in Backend Background for a period of time (less than 30s) and let App handle the message logic.

    The specific fields are as follows:

    Field name Type Parent project Default Value Is it necessary? Parameter description
    Aps JSON Ios None Yes Unique to (APNs), Apple's push service, the most important key-value pairs are as follows:
    Content-available: identifies the message type (must be 1) and cannot contain alert, sound, badge_type fields
    For more information, see Payload
    Ios JSON Message None Yes Ios message structure
    Custom_content String Ios None No Need to serialize to json string
    Xg String Ios None No The use of key, reserved in the system should be avoided.

    Complete example:

    {
        "ios":{
            "aps": {
                "content-available": 1
            },
          "custom_content":"{\"key\":\"value\"}",
            "xg": "oops"
        }
    }

    Optional parameter

    The Push API optional parameters are in addition to audience_typemessage_typemessage In addition, optional advanced parameters.

    Parameter name Type Parent project Necessary Default Value Description
    Expire_time Int None No 259200 (72 hours) Message offline storage time (in seconds), up to 72 hours
  • If expire_time=0, it means real-time message.
  • If expire_time is greater than 0 and less than 800s, the system will reset to 800s
  • If expire_time > = 800s, store it according to the actual set time, up to 72 hours.
  • The maximum value set must not exceed 2147483647, otherwise the push will fail.
  • Send_time String None No Current system time Specify push time:
  • Format is yyyy-MM-DD HH:MM:SS
  • If it is less than the current time of the server, it will be pushed immediately.
  • Only full push and label push support this field
  • Multi_pkg Bool None No False Push with multiple package names: when multiple channel packages exist in App and App of all channels are expected to receive messages during push, this value can be set to true.
    This parameter controls Client's and channel's multi-package name push by default. You need to implement Vendor and channel's multi-package name push. For more information, please see the document Vendor channel multi-package name configuration
    Loop_param Json None No * 2018-5-4 Circular push (full push, tag push) is related. For more information, please see the loop_param field description below.
    Badge_type Int IOS No -1 The user sets the corner number, which can only be used by iOS platform, and put it in the aps field.
  • -1: the corner number remains the same.
  • -2: corner numerals are automatically added by 1
  • > = 0: set custom corner number
  • Group_id String None No Tpns_yyyymmdd,yyyymmdd stands for push date Statistics label, for aggregate statistics
    Tag_list Object None Only label push is required None
  • Device who pushes tag1 and tag2: {"tags":["tag1","tag2"],"op":"AND"}
  • Device who pushes tag1 or tag2: {"tags":["tag1","tag2"],"op":"OR"}
  • Account_list Array None It is necessary to push a single account or a list of accounts. None If a single account pushes:
  • Requirements audience_type=account
  • Parameter format: [ "account1"]
    If the account list is pushed:
  • Parameter format: ["account1","account2"]
  • Up to 1000 account
  • Account_push_type Int None Optional when pushing account * 2018-5-4
  • 0: push messages to the latest device of the account
  • 1: push messages to all device Device of account Associate
  • Token_list Array None It is necessary for single Device push and Device list push. None If only Device pushes:
  • Require audience_type=token
  • Parameter format: [ "token1"]
    If Device's list is pushed:
  • Parameter format: [ "token1", "token2"]
  • Up to 1000 token
  • Push_speed Int None Only full push and label push are valid None Push speed limit is set as X per second. The range of parameters for X is 1000-50000.

    Loop_param parameter description

    Field name Type Required/Optional Annotation
    StartDate String Yes Looping interval start date, format YYYY-MM-DD, such as 2019 muri 07Mui 01
    EndDate String Yes Looping interval start date, format YYYY-MM-DD, such as 2019 muri 07 Mui 07
    LoopType Int Yes Cycle type, 1-by day, 2-by week, 3-by month
    LoopDayIndexs Array Yes Cycle by week, fill in what day of the week [ 0mur6], fill in 0 by day, such as [ 0,1,2], which means that the push is carried out on Monday, Tuesday and Wednesday every week.
    DayTimes Array Yes Specific push time, format HH:MM:SS, such as [ "19:00:00", "20:00:00"], which means that the push is carried out at 19:00 and 20:00 every day.

    Response parameter

    Field name Type Required/Optional Annotation
    Seq Int64_t Yes Consistent with the request packet (this field is 0 if the request packet is illegal json)
    Push_id String Yes Push ID
    Ret_code Int32_t Yes Error code, refer to the error code comparison table for details
    Environment String Yes User-specified push environment, which only supports iOS
  • Product: production environment
  • Dev: development environment
  • Err_msg String No Error message when the request goes wrong
    Result String No When the request is correct
  • If there is additional data to return, the result is encapsulated in the json of the field
  • If there is no additional data, this field may not be available.
  • Example illustration

    Android tag push request message

    {
        "audience_type": "tag",
        "tag_list": {
            "tags": [
                "tag1",
                "tag2"
            ],
            "op": "AND"
        },
        "multi_pkg":true,
        "push_speed":50000,
        "message_type": "notify",
        "message": {
        "title": "Test Title",
        "content": "Test Content",
        "xg_media_resources": "xxx1" , //Enter the rich media element address, such as https://www.xx.com/img/bd_logo1.png?qua=high
        "xg_media_audio_resources":"xxx", //Enter the audio rich media element address, such as http://sc1.111ttt.cn/2018/1/03/13/396131227447.mp3 
        "accept_time": [
            {
                "start": {//Period start time,
                    "hour": "13",//Start time, hours, value [0:24)
                    "min": "00"//Start time, minutes, value [0:60)
                },
                "end": {//Period end time
                    "hour": "14",//End time, hours, value [0:24)
                    "min": "00" //End time, minutes, value [0:60)
    
                }
            },
            {
                "start": {
                    "hour": "00",
                    "min": "00"
                },
                "end": {
                    "hour": "09",
                    "min": "00"
                }
            }
        ],
        "android": {
            "n_id": 0,
            "builder_id": 0,
            "ring": 1,
            "ring_raw": "ring",
            "vibrate": 1,
            "lights": 1,
            "clearable": 1,
            "icon_type": 0,
            "icon_res": "xg",
            "style_id": 1,
            "small_icon": "xg",
            "action": {
                "action_type": 1,//  action type, 1, open activity or app itself; 2, open browser; 3, open Intent 
                "activity": "xxx",
                "aty_attr": {//  activity attribute, only in the case of action_type=1 
                    "if": 0, // Flag attribute of Intent 
                    "pf": 0  // Flag property of PendingIntent
                },
                "browser": {
                    "url": "xxxx ", // Only http and https are supported
                    "confirm": 1 // Whether the user is required to confirm
                },
                "intent": "xxx" //The SDK version needs to be greater than or equal to 1.0.9, then configure the data tag in the client's intent and set the scheme attribute
            },
          "custom_content":"{\"key\":\"value\"}"
        }
    }
    }

    Label push reply message

    {
        "seq": 0,
        "environment": "product",
        "ret_code": 0,
        "push_id": "3895624686"
    }

    IOS single Device push request message

    {
        "audience_type": "token",
        "environment":"dev",
        "token_list": [ "05da87c0ae5973bd2dfa9e08d884aada5bb2"],
        "message_type":"notify",
        "message":{
         "title": "Push title",
        "content": " Push content",
        "ios":{
            "aps": {
                "alert": {
                    "subtitle": "Push subtitle "
                },
                "badge_type": -2,
                "sound":"Tassel.wav",
                "category": "INVITE_CATEGORY"
    
            },
           "custom_content":"{\"key\":\"value\"}",
            "xg": "oops"
        }
     }
    }

    Single Device pushes reply message

    {
        "seq": 0,
        "push_id": "427184209",
        "ret_code": 0,
        "environment": "dev",
        "err_msg": "",
        "result": "[0]"
    }