GET方式
http://www.phprm.com/services/push/send/xxxxxxxxxxxxxxx?head=msgHead&body=msgBody
说明:如遇到乱码请自行给相关参数编码,如果body太长请用POST方式, 如果需要指定3000毫秒后才送达, 可以参考一下方式进行推送:
示例:http://www.phprm.com/services/push/send/4d2dac865118761a14d10d7d3afe7c35?head=测试告警&body=长内容&delayMilliseconds=3000
POST方式
http://www.phprm.com/services/push/send/xxxxxxxxxxxxxxxx
说明:仅支持application/json的Content-Type进行POST请求, 如果需要立即跳转到自定义消息查看网址, 传递url参数为合法网址即可。
post参数:{"head":msgHead,"body":msgBody,"delayMilliseconds":3000,"url":"https://weibo.com"}
POST格式举例
POST http://www.phprm.com/services/push/send/4d2dac865118761a14d10d7d3afe7c35 HTTP/1.1
Host: www.phprm.com
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:10.0.2) Gecko/20100101 Firefox/10.0.2
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
Content-Length: 124
Origin: http://www.phprm.com
Pragma: no-cache
Cache-Control: no-cache
Request Payload
{"head":"测试告警","body":"长内容","delayMilliseconds":3000,"url":"https://weibo.com"}
GET/POST消息推送说明
1. channelCode: 创建通道后会自动给每条通道分配一个 通道码 ,如果你创建的通道是组合通道,可以绑定多个钉钉、飞书、邮箱等多个通道
2. head: 消息标题,长度200以内
3. body: 消息体内容,长度1M以内,如果数据太长请用POST方式,切记body尽量UrlEncode
4. 消息体内容 支持markdown格式,请参考markdown语法
5. 中文或其他特殊字符乱码情况下请UrlEncode处理下数据
6. 可以追加delayMilliseconds: 延时毫秒,最大延时推送毫秒时间不超过864000000 毫秒(10天)
自定义webhook请求参数示例(如果发送时经过API签名, 那么以下参数中也会重新生成timestamp、nonce、sign)
{ "channelCode": "4d2dac865118761a14d10d7d3afe7c35", "channelName": "示例通道", "eventType": 4, "messageId": "1154161735171727360", "pushTime": "2019-11-11 00:00:00", "data": { "head": "测试告警", "body": "长内容", "url": "http://push.phprm.com/api.html" } }
1. 自定义webhook 仅发起post请求, 请求Content-Type: application/json; charset=UTF-8
2. 鉴于自定义webhook网址的稳定性, API在回调时最长请求超时为10秒, 最大尝试次数为3次
二、口令提醒推送API(支持消息推送API所有特性, 扩展了quartz表达式以及参数映射功能)
发送提醒接口,支持仅提醒一次功能,支持GET或者POST请求方式,API支持https协议,具体文档查看移动端文档;
为了更好地适配其他外部系统, 移动端口令提醒支持标题/内容/跳转网址参数自动映射,无需修改代码也可以快速接入提醒功能,支持Server酱、网页更新提醒推送转移到本系统;
移动端还提供了禁止新成员加入功能、推送时间范围设置功能, 非推送时间将不会推送打扰到您,即使二维码泄露也不会有人误扫二维码加入通道;
移动端还支持@所有人功能,开启后提醒下所有群机器人通道将具备@所有人特性,手机会发出提示音+顶部消息通知,不会漏看消息。
文档中心提供了更加全面的API介绍以及推送样例代码、样例截图,点击查看。
GET方式(API和send完全相同,具备send所有特性之外, 还扩展了预设标题、预设内容、触发次数限制功能)
http://www.phprm.com/services/push/trigger/xxxxxxxxxxxxxxx?head=msgHead&body=msgBody
说明:如遇到乱码请自行给相关参数编码,如果body太长请用POST方式, 如果需要指定3000毫秒后才送达, 可以参考一下方式进行推送:
示例:http://www.phprm.com/services/push/trigger/4d2dac865118761a14d10d7d3afe7c35?head=测试告警&body=长内容&delayMilliseconds=3000
POST方式(API和send完全相同,具备send所有特性之外, 还扩展了预设标题、预设内容、触发次数限制、参数映射功能)
http://www.phprm.com/services/push/trigger/xxxxxxxxxxxxxxxx
说明:仅支持application/json的Content-Type进行POST请求, 如果需要跳转到自定义消息查看网址, 传递url参数即可。另外支持高级高能,具体文档查看移动端文档。
post参数:{"head":msgHead,"body":msgBody,"delayMilliseconds":3000,"url":"https://weibo.com"}
三、消息查询API
消息推送和口令提醒,推送成功都会返回messageIdList,可以使用英文,连接多个消息ID,传递给http://www.phprm.com/services/push/sendMessageResult/xxxxxxxxxxxxxxx?messageIds=消息ID, 进行GET查询
示例:http://www.phprm.com/services/push/sendMessageResult/c27ef861da4b29e14712a5c55d3c4010?messageIds=1205957302260228096,1205957305749889024
Tips:最大数量不能超过5个messageId批量查询,文档中心提供了更加全面的API介绍以及查询样例代码、样例截图,点击查看
消息ID批量查询响应内容
{ "code": 0, "message": "请求成功", "data": { "1205957302260228096": { "messageId": "1205957302260228096", "pushTypeDesc": "官方邮件", "pushedCount": 1, "viewCount": "0", "triggerTimeList": ["2023-02-10 19:23:46"], "handleTimeList": ["2023-02-10 19:23:49"], "readTimeList": [null], "handleCodeList": ["0"], "handleMsgList": [null] } } }
1. messageId作为data数据对象的Key,pushTypeDesc标识该推送通道的类型,pushedCount标识成功推送人次,viewCount标识该通道阅读人次。
2. triggerTimeList是您调用接口后系统分配推送任务的时间,handleTimeList是推送结束的时间,handleCodeList和handleMsgList是推送结束记录的错误码和错误信息,为0或者为空标识无错误
PHP webhook推送方举例(使用send、trigger均可)
<?php // 通道码 $channelCode = "540747bd92cc537a"; // 通道secret $signSecret = "abc"; // 获取毫秒时间戳 $timestamp = time()."000"; // 生成32位长度的随机码 $nonce = md5(uniqid()); // 生成签名 $sign = md5("{$timestamp}#{$signSecret}#{$nonce}"); // 标题为必传参数, 内容参数非必传但支持markdown语法 $head = "这是标题"; $body = "这是内容"; // 建议使用curl发送GET或者POST请求, 这里使用系统函数模拟 echo file_get_contents("http://www.phprm.com/services/push/send/{$channelCode}?head=".urlencode($head)."×tamp={$timestamp}&nonce={$nonce}&sign={$sign}&body=".urlencode($body));
PHP webhook接收方举例
<?php // 不加签时仅需要这一句即可获取到所有POST请求接收到json数据 $raw = file_get_contents("php://input"); $info = json_decode($raw, true); $signSecret = "abc"; if(isset($info["sign"]) && isset($info["nonce"]) && isset($info["timestamp"])) { // 验签: md5(timestamp#signSecret#nonce) $serverSign = md5("{$info["timestamp"]}#{$signSecret}#{$info["nonce"]}"); if($serverSign == $info["sign"]) { // 执行webhook通知业务逻辑 exit(); } } echo "permission deny";
四、进阶——API签名、组合、自定义关键词、IP白名单
1. API签名适用于推送、回调API,默认均不开启验签;如果您在官方已经配置过加签,修改推送通道/回调通道,填写官方签名;如果您未在官方配置加签, 您依然可以填写您自定义secret保护您在本平台的通信安全;
2. 点击通道详情——点这里在线测试——"发送测试"按钮,将自动读取您配置的secret值并按照加签规则生成随机串(不建议您通过网页源码查看javascript加签逻辑, 具体原因请看说明);
3. 如果事先创建了钉钉(官方加签)的群机器人和飞书(官方加签)的群机器人, 现在录入这两条通道记录后, 再创建一个 组合 通道(有无签名皆可, 无签名更简单), 并将前面两条记录的父通道指向 组合 通道, 最后程序里只需接入父通道码即可;
建议:您创建完钉钉、飞书等推送通道后, 将官方secret签名值配置到本平台;再创建一个组合通道作为这两种通道的 父通道, 程序接入父通道时无需签名, 因为即使父通道码泄露了也可以通过 重置 按钮更新父通道码,之前泄露的 父通道码 自动作废,最后更换您配置中心里的父通道码即可。
说明:设计签名的目的并不是让您在程序里进行加签增加工作量,而是为了尽可能安全的前提下让程序替我们做更多的事情;使用父通道码发起的请求与子通道验签逻辑无关,推送、回调时推送API会自动识别子通道签名值并帮您自动签名发送给钉钉、飞书。
一般安全等级 可更换的父通道码能保证您在钉钉、飞书webhook的安全性;更高安全等级 才需要在程序里调用API时加签, 此时可在父通道上设置自定义secret签名值。
自定义关键词 此类情况只需您创建指定关键词的通道名,推送任意文本时均可满足钉钉、飞书官方的匹配规则。
IP白名单 不推荐您配置IP白名单, 因为出口IP会变更, 目前暂时可填写以下IP:123.56.16.57、47.93.245.118、60.205.212.207