一、消息推送API使用说明

消息推送接口,支持GET或者POST请求方式,API支持https协议, 只有head参数是必填, 其他都是选填。

文档中心提供了更加全面的API介绍以及推送样例代码、样例截图,点击查看

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: 延时毫秒,最大延时推送毫秒时间不超过1296000000 毫秒(15天)

自定义webhook请求参数示例(如果发送时经过API签名, 那么以下参数中也会重新生成timestamp、nonce、sign)
{
	"channelCode": "4d2dac865118761a14d10d7d3afe7c35",
	"channelName": "示例通道",
	"eventType": 4,
	"messageId": "1154161735171727360",
	"pushTime": "2019-11-11 00:00:00",
	"data": {
		"head": "测试告警",
		"body": "长内容"
	}
}

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": "官方邮件",
			"pushCount": 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标识该推送通道的类型,pushCount标识该通道推送人次(仅微信通道可能会大于1),viewCount标识该通道阅读人次。

2. triggerTimeList是您调用接口后系统分配推送任务的时间,handleTimeList是推送结束的时间,handleCodeList和handleMsgList是推送结束记录的错误码和错误信息,为0或者为空标识无错误

PHP webhook推送方举例(使用send、trigger均可)
<?php
// 通道code
$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)."&timestamp={$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