# pushplus 接口文档 V1.3

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
支持多种请求方式,基于不同模板展示不同内容

# 一、发送消息接口

  • 请求地址: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 发送结果回调地址
  • 发送渠道(channel)枚举,邮件和短信暂未对外开放
发送渠道 是否免费 描述
wechat 免费 微信公众号
webhook 免费 第三方webhook;企业微信、钉钉、飞书、server酱;
cp 免费 企业微信应用
sms 收费 短信,未开放
mail 免费 邮箱,未开放
  • 模板(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模板效果对比\
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"
}

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

  • 请求地址:http://www.pushplus.plus/send
  • 请求方式:POST
  • 请求内容:
{
    "token":"{token}",
    "title":"标题",
    "content":"消息内容",
    "channel":"webhook",
    "webhook":"pushplus"
}
  • 说明:需要先配置对应的第三方webhook,如本例中的编码pushplus即为预先配置好的企业微信机器人。同理也可以配置钉钉机器人、飞书机器人等。
    webhook参数

# 示例八,企业微信应用的例子

  • 请求地址:http://www.pushplus.plus/send
  • 请求方式:POST
  • 请求内容:
{
    "token":"{token}",
    "title":"标题",
    "content":"消息内容",
    "channel":"cp",
    "webhook":"cp"
}
  • 说明:需要先配置对应的企业微信应用,在webhook字段中填入配置好的企业微信编码,如本例子中的cp。
    企业微信应用参数