推送API

简述

个推为开发者提供了如下3种消息推送方式：

• toSingle ：简称“单推”，指向单个用户推送消息
• toList：简称“批量推”，指向指定的一批用户推送消息
• toApp：简称“群推”，指向APP符合筛选条件的所有用户推送消息，支持定速推送、定时推送，支持条件的交并补功能
• ClientID简称CID：是个推业务层中的对外用户的唯一标识，用户标识客户端身份；由客户端获取并自己记录保存到自己到服务端；
  安卓cid获取方法(onReceiveClientId) ：文档地址
  ios cid获取方法(GeTuiSdkDidRegisterClient)：文档地址

【toSingle】执行cid单推

向单个用户推送消息，可根据cid指定用户

• 接口地址: BaseUrl/push/single/cid
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "request_id": "xxx",
  "settings": {
    "ttl": 7200000
  },
  "audience": {
    "cid": [
      "xxx"
    ]
  },
  "push_message": {
    "notification": {
      "title": "请填写通知标题",
      "body": "请填写通知内容",
      "click_type": "url",
      "url": "https//:xxx"
    }
  }
}

• 请求参数说明

• audience 说明

• settings 说明

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "",
  "data": {
    "$taskid": {
      "$cid": "$status"
    }
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/push/single/cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
     "request_id":"xxx",
     "settings":{
         "ttl":7200000
     },
     "audience":{
         "cid":[
             "xxx"
         ]
     },
     "push_message":{
         "notification":{
             "title":"请填写通知标题",
             "body":"请填写通知内容",
             "click_type":"url",
             "url":"https//:xxx"
         }
     }
 }'

【toSingle】执行别名单推

通过别名推送消息，绑定别名请参考接口

• 接口地址: BaseUrl/push/single/alias
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "request_id": "xxx",
  "settings": {
    "ttl": 7200000
  },
  "audience": {
    "alias": [
      "xxx"
    ]
  },
  "push_message": {
    "notification": {
      "title": "请填写通知标题",
      "body": "请填写通知内容",
      "click_type": "url",
      "url": "https//:xxx"
    }
  }
}

• 请求参数说明

• audience 说明

• settings 说明

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "",
  "data": {
    "$taskid": {
      "$cid": "$status"
    }
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/push/single/alias -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "request_id":"xxx",
    "settings":{
        "ttl":7200000
    },
    "audience":{
        "alias":[
            "xxx"
        ]
    },
    "push_message":{
        "notification":{
            "title":"请填写通知标题",
            "body":"请填写通知内容",
            "click_type":"url",
            "url":"https//:xxx"
        }
    }
}'

【toSingle】执行cid批量单推

批量发送单推消息，每个cid用户的推送内容都不同的情况下，使用此接口，可提升推送效率。

• 接口地址: BaseUrl/push/single/batch/cid
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "is_async": true,
  "msg_list": [
    {
      "request_id": "",
      "settings": {
        "ttl": 7200000
      },
      "audience": {
        "cid": [
          "xxxx"
        ]
      },
      "push_message": {
        "notification": {
          "title": "请填写通知标题",
          "body": "请填写通知内容",
          "click_type": "url",
          "url": "https://xxx"
        }
      }
    }
  ]
}

• 请求参数说明

msg_list

audience

settings

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "",
  "data": {
    "$taskid": {
      "$cid": "$status"
    }
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明(入参is_async为false时返回此字段)

请求示例

curl $BaseUrl/push/single/batch/cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "is_async":true,
    "msg_list":[
        {
            "request_id":"",
            "settings":{
                "ttl":7200000
            },
            "audience":{
                "cid":[
                    "xxxx"
                ]
            },
            "push_message":{
                "notification":{
                    "title":"请填写通知标题",
                    "body":"请填写通知内容",
                    "click_type":"url",
                    "url":"https://xxx"
                }
            }
        }
    ]
}'

【toSingle】执行别名批量单推

批量发送单推消息，在给每个别名用户的推送内容都不同的情况下，可以使用此接口

• 接口地址: BaseUrl/push/single/batch/alias
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "is_async": true,
  "msg_list": [
    {
      "request_id": "",
      "settings": {
        "ttl": 7200000
      },
      "audience": {
        "alias": [
          "xxxx"
        ]
      },
      "push_message": {
        "notification": {
          "title": "请填写通知标题",
          "body": "请填写通知内容",
          "click_type": "url",
          "url": "https://xxx"
        }
      }
    }
  ]
}

• 请求参数说明

msg_list

audience

settings

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "",
  "data": {
    "$taskid": {
      "$cid": "$status"
    }
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明(入参is_async为false时返回此字段)

请求示例

curl $BaseUrl/push/single/batch/alias -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
     "is_async":true,
     "msg_list":[
         {
             "request_id":"",
             "settings":{
                 "ttl":7200000
             },
             "audience":{
                 "alias":[
                     "xxxx"
                 ]
             },
             "push_message":{
                 "notification":{
                     "title":"请填写通知标题",
                     "body":"请填写通知内容",
                     "click_type":"url",
                     "url":"https://xxx"
                 }
             }
         }
     ]
    }'

【toList】创建消息

此接口用来创建消息体，并返回taskid，为批量推的前置步骤
注：此接口频次限制200万次/天，申请修改请点击右侧“技术咨询”了解详情。

• 接口地址: BaseUrl/push/list/message
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "group_name": "请填写任务组名",
  "settings": {
    "ttl": 7200000
  },
  "push_message": {
    "notification": {
      "title": "请填写通知标题",
      "body": "请填写通知内容",
      "click_type": "url",
      "url": "https//:xxx"
    }
  }
}

• 请求参数说明

settings

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "",
  "data": {
    "taskid": ""
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/push/list/message -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "group_name":"请填写任务组名",
    "settings":{
        "ttl":7200000
    },
    "push_message":{
        "notification":{
            "title":"请填写通知标题",
            "body":"请填写通知内容",
            "click_type":"url",
            "url":"https//:xxx"
        }
    }
}'

【toList】执行cid批量推

对列表中所有cid进行消息推送。调用此接口前需调用创建消息接口设置消息内容。

• 接口地址: BaseUrl/push/list/cid
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "audience": {
    "cid": [
      "xxxx1",
      "xxxx2"
    ]
  },
  "taskid": "",
  "is_async": true
}

• 请求参数说明

audience

说明：cid、smart_crowd_task_id、crowd_id必须3选1

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "",
  "data": {
    "$taskid": {
      "$cid": "$status"
    }
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明(当is_async=false时返回此字段)

请求示例

curl $BaseUrl/push/list/cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "audience": {
        "cid": [
            "xxxx1",
            "xxxx2"
        ]
    },
    "taskid": "",
    "is_async": true
}'

【toList】执行别名批量推

对列表中所有别名进行消息推送。调用此接口前需调用创建消息接口设置消息内容。

• 接口地址: BaseUrl/push/list/alias
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "audience": {
    "alias": [
      "xxxx1",
      "xxxx2"
    ]
  },
  "taskid": "",
  "is_async": true
}

• 请求参数说明

audience

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "",
  "data": {
    "$taskid": {
      "$cid": "successed_offline"
    }
  }
}

当is_async=false，need_alias_detail=true时，返回别名详情，返回结构如下

{
  "msg": "success",
  "code": 0,
  "data": {
    "$taskid": {
      "$alias1": {
        "$cid1": "successed_online",
        "$cid2": "successed_offline"
      },
      "$alias2": {
        "$cid3": "successed_online",
        "$cid4": "successed_ignore"
      }
    }
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明(当is_async=false时返回此字段)

请求示例

curl $BaseUrl/push/list/alias -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "audience": {
        "alias": [
            "xxxx1",
            "xxxx2"
        ]
    },
    "taskid": "",
    "is_async": true
}'

【toApp】执行群推

对指定应用的所有用户群发推送消息。支持定时、定速功能，查询任务推送情况请见接口查询定时任务。
注：此接口频次限制20次/天，每分钟不能超过5次(推送限制和接口根据条件筛选用户推送共享限制)

• 接口地址: BaseUrl/push/all
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "request_id": "请填写requestid",
  "group_name": "请填写任务组名",
  "settings": {
    "ttl": 7200000
  },
  "audience": "all",
  "push_message": {
    "notification": {
      "title": "请填写通知标题",
      "body": "请填写通知内容",
      "click_type": "url",
      "url": "https//:xxx"
    }
  }
}

• 请求参数说明

settings

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskid": ""
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/push/all -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "request_id":"请填写requestid",
    "group_name":"请填写任务组名",
    "settings":{
        "ttl":7200000
    },
    "audience":"all",
    "push_message":{
        "notification":{
            "title":"请填写通知标题",
            "body":"请填写通知内容",
            "click_type":"url",
            "url":"https//:xxx"
        }
    }
}'

【toApp】根据条件筛选用户推送

对指定应用的符合筛选条件的用户群发推送消息。支持定时、定速功能。
注：此接口频次限制20次/天，每分钟不能超过5次(推送限制和接口执行群推共享限制)，定时推送功能需要申请开通才可以使用，申请修改请点击右侧“技术咨询”了解详情。
注：个推用户画像中的，单身、已婚、彩票类标签已经下架，请开发者及时关注和处理。

• 接口地址: BaseUrl/push/tag
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "request_id": "请填写requestid",
  "group_name": "请填写任务组名",
  "settings": {
    "ttl": 7200000
  },
  "audience": {
    "tag": [
      {
        "key": "phone_type",
        "values": [
          "android"
        ],
        "opt_type": "and"
      },
      {
        "key": "region",
        "values": [
          "11000000"
        ],
        "opt_type": "not"
      },
      {
        "key": "custom_tag",
        "values": [
          "0901",
          "0902"
        ],
        "opt_type": "or"
      },
      {
        "key": "portrait",
        "values": [
          "si1003",
          "si1100"
        ],
        "opt_type": "or"
      }
    ]
  },
  "push_message": {
    "notification": {
      "title": "请填写通知标题",
      "body": "请填写通知内容",
      "click_type": "url",
      "url": "https//:xxx"
    }
  }
}

• 请求参数说明

audience

tag

• 不同key之间是交集，同一个key之间是根据opt_type操作
• eg. 需要发送给城市在A,B,C里面，没有设置tagtest标签，手机型号为android的用户，用条件交并补功能可以实现，city(A|B|C) && !tag(tagtest) && phonetype(android)

settings

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskid": ""
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/push/tag -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "request_id":"请填写requestid",
    "group_name":"请填写任务组名",
    "settings":{
        "ttl":7200000
    },
    "audience":{
        "tag":[
            {
                "key":"phone_type",
                "values":[
                    "android"
                ],
                "opt_type":"or"
            },
            {
                "key":"region",
                "values":[
                    "11000000"
                ],
                "opt_type":"and"
            }
        ]
    },
    "push_message":{
        "notification":{
            "title":"请填写通知标题",
            "body":"请填写通知内容",
            "click_type":"url",
            "url":"https//:xxx"
        }
    }
}'

【toApp】使用标签快速推送

根据标签过滤用户并推送。支持定时、定速功能。
注：该功能需要申请相关套餐，请点击右侧“技术咨询”了解详情 。

• 接口地址: BaseUrl/push/fast_custom_tag
• 请求方式: POST

Request请求说明:

Header参数说明

body参数说明

• content-type:application/json;charset=utf-8

• 参数示例

{
  "request_id": "请填写requestid",
  "group_name": "请填写任务组名",
  "settings": {
    "ttl": 7200000
  },
  "audience": {
    "fast_custom_tag": "xxxx"
  },
  "push_message": {
    "notification": {
      "title": "请填写通知标题",
      "body": "请填写通知内容",
      "click_type": "url",
      "url": "https//:xxx"
    }
  }
}

• 请求参数说明

audience

settings

Response响应说明

成功响应数据格式:

• content-type: application/json;charset=utf-8

• http code: 200(http code码说明)

• 返回值示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskid": ""
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/push/fast_custom_tag -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: $token" -d '{
    "request_id":"请填写requestid",
    "group_name":"请填写任务组名",
    "settings":{
        "ttl":7200000
    },
    "audience":{
        "fast_custom_tag":"xxxx"
    },
    "push_message":{
        "notification":{
            "title":"请填写通知标题",
            "body":"请填写通知内容",
            "click_type":"url",
            "url":"https//:xxx"
        }
    }
}'

【任务】停止任务

对正处于推送状态，或者未接收的消息停止下发（只支持批量推和群推任务）

• 接口地址: BaseUrl/task/$taskid
• 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

Header参数说明

Response响应说明

成功响应数据格式:

• content-type:application/json;charset=utf-8

• 返回值示例

 {
  "code": 0,
  "msg": "success"
}

• 返回结构说明请参考公共返回结构

请求示例

curl $BaseUrl/task/$taskid -X DELETE -H "token: xxx" 

【任务】查询定时任务

该接口支持在推送完定时任务之后，查看定时任务状态，定时任务是否发送成功。
创建定时任务请见接口执行群推

• 接口地址: BaseUrl/task/schedule/$taskid
• 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

Header参数说明

Response响应说明

成功响应数据格式:

• content-type:application/json;charset=utf-8

• 返回值示例

 {
  "code": 0,
  "msg": "success",
  "data": {
    "$taskid": {
      "create_time": "2024-07-24 09:43:07",
      "send_result": "do_not_send",
      "push_time": "202407250900",
      "transmission_content": ""
    }
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/task/schedule/$taskid -H "token: xxx" 

【任务】删除定时任务

用来删除还未下发的任务，删除后定时任务不再触发(距离下发还有一分钟的任务，将无法删除，后续可以调用停止任务接口。)

• 接口地址: BaseUrl/task/schedule/$taskid
• 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

Header参数说明

Response响应说明

成功响应数据格式:

• content-type:application/json;charset=utf-8

• 返回值示例

 {
  "code": 0,
  "msg": "success"
}

• 返回结构说明请参考公共返回结构

请求示例

curl $BaseUrl/task/schedule/$taskid -X DELETE -H "token: xxx" 

【推送】查询消息明细

调用此接口可以查询某任务下某cid的具体实时推送路径情况

使用该接口需要申请权限，若有需要，请点击右侧“技术咨询”了解详情

• 接口地址: BaseUrl/task/detail/${cid}/${taskid}
• 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

Header参数说明

Response响应说明

成功响应数据格式:

• content-type:application/json;charset=utf-8

• 返回值示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "deatil": [
      {
        "time": "yyyy-MM-dd HH:mm:ss",
        "event": "消息请求成功"
      },
      {
        "time": "yyyy-MM-dd HH:mm:ss",
        "event": "到达客户端"
      }
    ]
  }
}

• 返回结构说明请参考公共返回结构

• 返回参数data说明

请求示例

curl $BaseUrl/task/detail/${cid}/${taskid} -H "token: xxx"