pushplus 消息接口文档

pushplus 消息接口文档 V1.4

1.4 接口更新日期：2021-08-31
新增timestamp时间戳字段，可用于避免重复发送相同消息

1.3 接口更新日期：2021-06-16
接口由同步改成异步；新增callbackUrl参数，用于异步回调结果

1.2 接口更新日期：2021-03-30
支持txt格式内容；优化markdown格式内容展示；改进换行问题

1.1 接口更新日期：2021-03-14
增加webhook推送方式；支持markdown格式内容

1.0 接口更新日期：2020-06-01
支持多种请求方式，基于不同模板展示不同内容

pushplus官网地址：http://www.pushplus.plus

一、发送消息接口

• 请求地址：http://www.pushplus.plus/send
• 请求方式：GET,POST,PUT,DELTE
• 请求参数，均支持url参数和body参数：
• Content-Type: application/json

参数名称	是否必填	默认值	说明
token	是	无	用户令牌，可直接加到请求地址后，如：http://www.pushplus.plus/send/{token}
title	否	无	消息标题
content	是	无	具体消息内容，根据不同template支持不同格式
topic	否	无	群组编码，不填仅发送给自己；channel为webhook时无效
template	否	html	发送模板
channel	否	wechat	发送渠道
webhook	否	无	webhook编码，仅在channel使用webhook渠道和CP渠道时需要填写
callbackUrl	否	无	发送结果回调地址
timestamp	否	无	毫秒时间戳。格式如：1632993318000。服务器时间戳大于此时间戳，则消息不会发送

• 发送渠道（channel）枚举，短信暂未对外开放

发送渠道	是否免费	描述
wechat	免费	微信公众号
webhook	免费	第三方webhook；企业微信、钉钉、飞书、server酱；webhook机器人推送
cp	免费	企业微信应用；具体参考企业微信应用推送
mail	免费	邮箱；具体参考邮件渠道使用说明
sms	收费	短信，未开放

• 模板（template）枚举。默认使用html模板

模板名称	描述
html	默认模板，支持html文本
txt	纯文本展示，不转义html
json	内容基于json格式展示
markdown	内容基于markdown格式展示
cloudMonitor	阿里云监控报警定制模板
jenkins	jenkins插件定制模板
route	路由器插件定制模板

• webhook参数说明。
  请到微信公众号菜单中预先进行webhook配置。当前字段需填写配置中的webHook编码。

• 响应内容
  　  原本接口采用同步模式，直接返回发送结果。现在已调整为异步返回结果，同步响应状态只代表收到请求，将会异步处理消息。
  请求成功返回code为200，同时data会返回消息流水号，如请求带有回调地址参数，发送结果会主动回调一次。同时也可以根据消息流水号来查询发送结果。
  请求的时候也会同步验证消息是否合法，可以根据判断code的值来确定请求成功还是失败。

{
    "code": 200,
    "msg": "请求成功",
    "data": "3cbc5eab19fe512e80677540fbde332a"
}

• 回调内容
  如请求时带有callbackUrl参数，异步发送消息完成后将会发送一个post请求到回调地址上。post请求的body内容如下：

{
  "shortCode":"88*********50fe",   //消息流水号
  "sendStatus": 2,  //发送状态；0未发送，1发送中，2发送成功，3发送失败
  "message":""   //推送错误内容（如有）
}

二、示例

  接口设计考虑尽可能多的支持各种请求方式。以下举例几种常用的请求方式仅供参考，接口不仅局限于以下几种请求。

示例一，最简单的例子

• 请求地址：http://www.pushplus.plus/send?token={token}&content=pushplus消息内容
• 请求方式: GET
• 说明：具体使用的时候将请求地址上的{token}替换成自己的token。content中如包含中文需要UrlEncode编码处理下。

示例二，POST方式推送消息

• 请求地址：http://www.pushplus.plus/send/
• 请求方式: POST
• 请求内容：

{
    "token":"{token},
    "title":"标题",
    "content":"消息内容",
    "topic":"test"
}

• 说明：具体使用的时候将请求内容中的{token}替换成自己的token

示例三，一对多消息的例子

• 请求地址：http://www.pushplus.plus/send/
• 请求方式: POST
• 请求内容：

{
    "token":"{token}",
    "title":"标题",
    "content":"消息内容",
    "topic":"code",
    "template":"html"
}

• 说明：消息将会发送给加入群组编码为code的成员

示例四，json格式的例子

• 请求地址：http://www.pushplus.plus/send
• 请求方式：POST
• 请求内容：

{
    "token":"{token}",
    "title":"标题",
    "content":"{'name':'名称','size':'大小','number':'数量'}",
    "template":"json"
}

• 说明：当template参数为json并且放在body中的时候，pushplus会解析content中的json格式内容，以更加友好的方式展示出来。如template参数放在url地址上，会将整个body内容视为content进行解析，具体见下面的例子。
• json模板和html模板效果对比\

示例五，webhook的例子

• 请求地址：http://www.pushplus.plus/send/{token}?template=json
• 请求方式：POST
• 请求内容：

{
    "userName":"pushplus",
    "updateTime":"2020-04-29 14:59:35",
    "projectId":82
}

• 说明：这个例子适用于外部第三方webhook接口，仅能填写url地址，无法修改body内容。示例中整个body内容被当成content处理。

示例六，markdown的例子

• 请求地址：http://www.pushplus.plus/send
• 请求方式：POST
• 请求内容：

{
    "token":"{token}",
    "title":"标题",
    "content":"# 大标题 \n ##### 小标题 \n  1. 第一项 \n 2. 第二项 \n 3. 第三项",
    "template":"markdown"
}

• 说明：markdown语法参考https://www.appinn.com/markdown/。支持html格式，换行使用\n来表示。

示例七，企业微信机器人的例子

• 请求地址：http://www.pushplus.plus/send
• 请求方式：POST
• 请求内容：

{
    "token":"{token}",
    "title":"标题",
    "content":"消息内容",
    "channel":"webhook",
    "webhook":"pushplus"
}

• 说明：需要先配置对应的第三方webhook，如本例中的编码pushplus即为预先配置好的企业微信机器人。同理也可以配置钉钉机器人、飞书机器人等。
  
  
  

示例八，企业微信应用的例子

• 请求地址：http://www.pushplus.plus/send
• 请求方式：POST
• 请求内容：

{
    "token":"{token}",
    "title":"标题",
    "content":"消息内容",
    "channel":"cp",
    "webhook":"cp"
}

• 说明：需要先配置对应的企业微信应用，在webhook字段中填入配置好的企业微信编码，如本例子中的cp。
  

示例九，增加时间戳的例子

• 请求地址：http://www.pushplus.plus/send
• 请求方式：POST
• 请求内容：

{
    "token":"{token}",
    "title":"标题",
    "content":"消息内容",
    "timestamp": 1632993318000
}

• 说明：时间戳使用的是毫秒。如果时间戳小于当前时间，则消息不会发送。用于时效性较强的消息，避免无用的消息重复发送。