消息推送API

消息推送系统，统一了发送的接口。一个接口就可以实现发送邮件、企业微信、钉钉消息等。同时提供了扩展的接口，方便实现对其它平台的对接。

平台类型

平台类型	平台代码
邮件	EMAIL
企业微信-应用	WECHAT_WORK_AGENT
企业微信-群机器人	WECHAT_WORK_ROBOT
钉钉-工作通知	DING_TALK_CORP
钉钉-自定义机器人	DING_TALK_ROBOT

消息类型

平台对应的消息类型

消息类型	消息代码
邮件	EMAIL
企业微信-应用-文本	WECHAT_WORK_AGENT_TEXT
企业微信-应用-图片	WECHAT_WORK_AGENT_IMAGE
企业微信-应用-视频	WECHAT_WORK_AGENT_VIDEO
企业微信-应用-文件	WECHAT_WORK_AGENT_FILE
企业微信-应用-文本卡片	WECHAT_WORK_AGENT_TEXTCARD
企业微信-群机器人-文本	WECHAT_WORK_ROBOT_TEXT
企业微信-群机器人-图文	WECHAT_WORK_ROBOT_NEWS
企业微信-群机器人-markdown	WECHAT_WORK_ROBOT_MARKDOWN
企业微信-群机器人-图片消息	WECHAT_WORK_ROBOT_IMAGE
钉钉-工作通知-文本	DING_TALK_COPR_TEXT
钉钉-工作通知-markdown	DING_TALK_COPR_MARKDOWN
钉钉-工作通知-链接	DING_TALK_COPR_LINK
钉钉-工作通知-图片	DING_TALK_COPR_IMAGE
钉钉-工作通知-卡片-单按钮	DING_TALK_COPR_ACTION_CARD_SINGLE
钉钉工作通知-文件	DING_TALK_COPR_FILE
钉钉-自定义机器人-文本	DING_TALK_ROBOT_TEXT
钉钉-自定义机器人-Markdown	DING_TALK_ROBOT_MARKDOWN
钉钉-自定义机器人-链接	DING_TALK_ROBOT_LINK

统一接口

param里面的参数根据消息代码的不同，会有差异

{
    "messageParam": {
        "消息代码": {
            "configIds": [
                //平台类型配置id
                "1449300018182877185"
            ],
            "param": {
                //...不同的消息代码参数是不一样的
            }
        }
    }
}

邮件

服务器配置

• host：服务器域名
• port：端口
• from：发送方，遵循RFC-822标准（邮箱@前面的字符串）
• user：用户名
• password：密码
• sslEnable：是否使用 SSL安全连接

例如163邮箱-设置-》POP3/SMTP/IMAP

类型	服务器名称	服务器地址	SSL协议端口号	非SSL协议端口号
收件服务器	POP	pop.163.com	995	110
收件服务器	IMAP	imap.163.com	993	143
发件服务器	SMTP	smtp.163.com	465/994	25

param配置参数

字段	含义	类型	是否必须
toUser	接收人邮箱，多个人用,隔开	String	是
title	主题	String	是
content	发送内容	String	是
ccs	抄送人列表，多个人用,隔开	String	否
fileNames	附件列表，先调用文件上传接口获取	List(String)	否

参数示例

{
    "messageParam": {
        "EMAIL": {
            "configIds": [
                "xxxxxxxx"
            ],
            "param": {
                "toUser": "xxxx@qq.com,xxxx@qq.com",
                "fileNames": ["73a78d289400464a9389dadf9a5b57e6.jpg"],
                "title": "cccc",
                "content": "cccc"
            }
        }
    }
}

效果

带附件的发送

文件上传

文件存储对接的是：https://gitee.com/bushro/oss-spring-boot-start。该系统已经集成了，需要先配置oss相关配置。

钉钉-工作通知

钉钉服务端的API官网有新版的和旧版的

API版本	旧版服务端API	新版服务端API
规范	旧版规范。	新版规范。
SDK	支持以下版本：Java、PHP、Python、.NET、.NET Core。	支持以下版本：Java（支持通过Maven安装）、Node.js、PHP、Go、C#、Python。
开放的产品能力	现状：旧版服务端API和新版服务端API开放的产品能力不同，即新版服务端API未包含全部的服务端API的产品能力，请根据实际需求，选择需要的API接入。计划：旧版服务端API接口升级到新版规范，升级完成后，新版服务端API会包含全部功能。
是否开放新能力	不再开放新能力。	持续开放新能力。
是否推荐	已接入应用可继续使用，接口不会下线。	新版本如有对应的API，推荐接入新版服务端API。

由于我们要使用到的消息通知功能新版还没有支持，所以我们使用旧版的服务端API

官方文档：https://open.dingtalk.com/document/orgapp-server/asynchronous-sending-of-enterprise-session-messages

配置

登陆钉钉管理后台-》应用管理-》自建应用

获取AgentId、AppKey、AppSecret

文本消息

param参数

字段	含义	类型	是否必须
useridList	接收者的用户userid列表, user123,user456 接收者的userid列表，最大用户列表长度100。	String	否
deptIdList	接收者的部门id列表，最大列表长度20。接收者是部门ID时，包括子部门下的所有用户, 多个部门id用,隔开	String	否
toAllUser	是否全员发送，当设置为false时必须指定useridList或deptIdList其中一个参数的值。	boolean	是
content	发送内容	String	是

发送示例

{
    "messageParam": {
        "DING_TALK_COPR_TEXT": {
            "configIds": [
                "xxxxxxxx"
            ],
            "param": {
                "useridList":"xxxx",
                "content": "还没下班，别跑"
            }
        }
    }
}

markdown消息

param参数

字段	含义	类型	是否必须
useridList	接收者的用户userid列表, user123,user456 接收者的userid列表，最大用户列表长度100。	String	否
deptIdList	接收者的部门id列表，最大列表长度20。接收者是部门ID时，包括子部门下的所有用户, 多个部门id用,隔开	String	否
toAllUser	是否全员发送，当设置为false时必须指定useridList或deptIdList其中一个参数的值。	boolean	是
title	首屏会话透出的展示内容	String	是
text	Markdown内容	String	是

发送示例

{
    "messageParam": {
        "DING_TALK_ROBOT_MARKDOWN": {
            "configIds": [
                "xxxxxxxxxxxx"
            ],
            "param": {
                "title": "杭州天气",
                "text": "#### 杭州天气 @156xxxx8827\n" +
        "> 9度，西北风1级，空气良89，相对温度73%\n\n" +
        "> ![screenshot](https://gw.alicdn.com/tfs/TB1ut3xxbsrBKNjSZFpXXcXhFXa-846-786.png)\n"  +
        "> ###### 10点20分发布 [天气](http://www.thinkpage.cn/) \n"
            }
        }
    }
}

图片消息

字段	含义	类型	是否必须
useridList	接收者的用户userid列表, user123,user456 接收者的userid列表，最大用户列表长度100。	String	否
deptIdList	接收者的部门id列表，最大列表长度20。接收者是部门ID时，包括子部门下的所有用户,多个部门id用,隔开	String	否
toAllUser	是否全员发送，当设置为false时必须指定receiverIds或deptIdList其中一个参数的值。	boolean	是
mediaId	媒体文件mediaid。 可以通过媒体文件上传接口获取。	String	是

发送示例

{
    "messageParam": {
        "DING_TALK_COPR_IMAGE": {
            "configIds": [
                "xxxxxxxx"
            ],
            "param": {
                "useridList":"xxxxx",
                "mediaId": "@lALPDgCwYKNkrQvNAsnNBD4"
            }
        }
    }
}

文件消息

同上

卡片消息

字段	含义	类型	是否必须
useridList	接收者的用户userid列表, user123,user456 接收者的userid列表，最大用户列表长度100。	String	否
deptIdList	接收者的部门id列表，最大列表长度20。接收者是部门ID时，包括子部门下的所有用户,多个部门id用,隔开	String	否
toAllUser	是否全员发送，当设置为false时必须指定receiverIds或deptIdList其中一个参数的值。	boolean	是
title	是透出到会话列表和通知的文案	String	是
singleTitle	使用整体跳转ActionCard样式时的标题。必须与single_url同时设置，最长20个字符。	String	是
singleUrl	消息点击链接地址，当发送消息为小程序时支持小程序跳转链接，最长500个字符。	String	是
markdown	消息内容，支持markdown，语法参考标准markdown语法。建议1000个字符以内。	String	是

发送示例

{
    "messageParam": {
        "DING_TALK_COPR_ACTION_CARD_SINGLE": {
            "configIds": [
                "xxxxxxxx"
            ],
            "param": {
                "useridList": "xxxxx",
                "toAllUser": false,
                "title":"是透出到会话列表和通知的文案",
                "singleTitle":"查看详情",
                "markdown":"支持markdown格式的正文内容",
                "singleUrl":"https://open.dingtalk.com"
            }
        }
    }
}

媒体文件上传

字段	含义	类型	是否必须
fileType	媒体文件类型： image：图片，图片最大1MB。支持上传jpg、gif、png、bmp格式。file：普通文件，最大10MB。支持上传doc、docx、xls、xlsx、ppt、pptx、zip、pdf、rar格式。	String	是
configId	配置id	String	是
media	媒体文件id	String	是

请求示例

钉钉- 自定义机器人

https://open.dingtalk.com/document/robots/custom-robot-access

场景介绍

企业内部有较多系统支撑着公司的核心业务流程，譬如CRM系统、交易系统、监控报警系统等等。通过钉钉的自定义机器人，可以将这些系统事件同步到钉钉的聊天群。

说明

当前机器人尚不支持应答机制，该机制指的是群里成员在聊天@机器人的时候，钉钉回调指定的服务地址，即Outgoing机器人。

调用频率

由于消息发送太频繁会严重影响群成员的使用体验，因此钉钉开放平台对自定义机器人发送消息的频率作出以下限制：

每个机器人每分钟最多发送20条消息到群里，如果超过20条，会限流10分钟。

注意

如果你有大量发消息的场景（譬如系统监控报警）可以将这些信息进行整合，通过markdown消息以摘要的形式发送到群里。

配置

使用电脑端添加才可以

这里使用的是加签的方式

文本消息

param参数

字段	含义	类型	是否必须
atMobiles	被@人的手机号。	List(String)	否
atUserIds	被@人的用户userid。	List(String)	否
isAtAll	是否@所有人。	Boolean	否
content	发送内容	String	是

发送示例

{
    "messageParam": {
        "DING_TALK_ROBOT_TEXT": {
            "configIds": [
                "1449300018182877191"
            ],
            "param": {
                "content": "还没下班，别跑"
            }
        }
    }
}

效果

markdown消息

param参数

字段	含义	类型	是否必须
atMobiles	被@人的手机号。	List(String)	否
atUserIds	被@人的用户userid。	List(String)	否
isAtAll	是否@所有人。	Boolean	否
title	首屏会话透出的展示内容。	String	是
text	markdown格式的消息。	String	是

发送示例

{
    "messageParam": {
        "DING_TALK_ROBOT_MARKDOWN": {
            "configIds": [
                "1449300018182877191"
            ],
            "param": {
                "title": "杭州天气",
                "text": "- host：服务器域名
- port：端口
- from：发送方，遵循RFC-822标准（邮箱@前面的字符串）
- user：用户名
- password：密码
- sslEnable：是否使用 SSL安全连接"
            }
        }
    }
}

效果

link消息

param参数

字段	含义	类型	是否必须
atMobiles	被@人的手机号。	List(String)	否
atUserIds	被@人的用户userid。	List(String)	否
isAtAll	是否@所有人。	Boolean	否
title	消息标题。	String	是
text	消息内容。如果太长只会部分展示。	String	是
messageUrl	点击消息跳转的URL	String	是
picUrl	图片URL。	String	否

发送示例

{
    "messageParam": {
        "DING_TALK_ROBOT_LINK": {
            "configIds": [
                "1449300018182877191"
            ],
            "param": {
                "title": "时代的火车向前开",
                "text": "这个即将发布的新版本，创始人xx称它为红树林。而在此之前，每当面临重大升级，产品经理们都会取一个应景的代号，这一次，为什么是红树林",
                "messageUrl": "https://www.dingtalk.com/",
                "picUrl": ""
            }
        }
    }
}

效果

企业微信-应用

配置

官方文档：https://developer.work.weixin.qq.com/document/path/90372

登陆企业微信

在应用管理页面创建一个应用然后获取AgentId、Secret。

文本消息

param配置参数

字段	含义	类型	是否必须
toUser	成员ID列表（消息接收者，多个接收者用‘|’分隔，最多支持1000个）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送	String	否
toParty	PartyID列表，非必填，多个接受者用‘|’分隔。当touser为@all时忽略本参数	String	否
toTag	TagID列表，非必填，指定接收消息的标签，标签ID列表，多个接收者用‘|’分隔，最多支持100个。 当touser为"@all"时忽略本参数	String	否
content	发送内容	String	是

发送示例

{
    "messageParam": {
        "WECHAT_WORK_AGENT_TEXT": {
            "configIds": [
                "xxxxxxxx"
            ],
            "param": {
                "toUser":"xxxxx",
                "content": "还没下班，别跑"
            }
        }
    }
}

图片消息

param配置参数

字段	含义	类型	是否必须
toUser	成员ID列表（消息接收者，多个接收者用‘|’分隔，最多支持1000个）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送	String	否
toParty	PartyID列表，非必填，多个接受者用‘|’分隔。当touser为@all时忽略本参数	String	否
toTag	TagID列表，非必填，指定接收消息的标签，标签ID列表，多个接收者用‘|’分隔，最多支持100个。 当touser为"@all"时忽略本参数	String	否
mediaId	媒体文件mediaid。 可以通过媒体文件上传接口获取	String	是

发送示例

{
    "messageParam": {
        "WECHAT_WORK_AGENT_IMAGE": {
            "configIds": [
                "xxxxxxxx"
            ],
            "param": {
                "toUser":"xxxxxx",
                "mediaId": "3I90K4fdBGNW3Aqjqo5tgS4rFj79S3miqK2jrCC5oMwFa3pMmNuCIDrUQJPpifSeO"
            }
        }
    }
}

文件消息

和图片一样

卡片消息

字段	含义	类型	是否必须
toUser	成员ID列表（消息接收者，多个接收者用‘|’分隔，最多支持1000个）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送	String	否
toParty	PartyID列表，非必填，多个接受者用‘|’分隔。当touser为@all时忽略本参数	String	否
toTag	TagID列表，非必填，指定接收消息的标签，标签ID列表，多个接收者用‘|’分隔，最多支持100个。 当touser为"@all"时忽略本参数	String	否
title	标题	String	是
btntxt	按钮文字。 默认为“详情”， 不超过4个文字，超过自动截断。	String	是
description	描述，不超过512个字节，超过会自动截断	String	是

发送示例

{
    "messageParam": {
        "WECHAT_WORK_AGENT_TEXTCARD": {
            "configIds": [
                "xxxxxxxx"
            ],
            "param": {
                "toUser":"xxxxx",
                "title": "领奖通知",
                "description": "<div class=\"gray\">2022年10月24日</div> <div class=\"normal\">恭喜你抽中iPhone 13一台，领奖码：xxxx</div><div class=\"highlight\">请于2022年10月30日前联系行政同事领取</div>",
                "url": "URL",
                "btntxt": "更多"
            }
        }
    }
}

媒体文件上传

字段	含义	类型	是否必须
fileType	媒体文件类型： image：图片，图片最大1MB。支持上传jpg、gif、png、bmp格式。file：普通文件，最大10MB。支持上传doc、docx、xls、xlsx、ppt、pptx、zip、pdf、rar格式。	String	是
configId	配置id	String	是
media	媒体文件id	String	是

请求示例

企业微信-群机器人

官方文档：访问地址open in new window

通过手机的企业微信在群里添加机器人，记录下Webhook地址后面的key 。后面需要用这个来发送消息

配置

文本消息

param参数

字段	含义	类型	是否必须
mentionedMobileList	手机号列表，提醒手机号对应的群成员(@某个成员)，@all表示提醒所有人	String	否
mentionedList	userid的列表，提醒群中的指定成员(@某个成员)，@all表示提醒所有人，如果开发者获取不到userid，可以使用mentioned_mobile_list	String	否
content	文本内容，最长不超过2048个字节，必须是utf8编码	String	是

发送示例

{
    "messageParam": {
        "WECHAT_WORK_ROBOT_TEXT": {
            "configIds": [
                "1449300018182877190"
            ],
            "param": {
                "content": "还没下班，别跑"
            }
        }
    }
}

样例

图文消息

param参数

字段	含义	类型	是否必须
articles.title	标题，不超过128个字节，超过会自动截断	String	是
articles.description	描述，不超过512个字节，超过会自动截断	String	否
articles.url	点击后跳转的链接。	String	是
articles.picurl	图文消息的图片链接，支持JPG、PNG格式，较好的效果为大图 1068455，小图150150。	String	否

请求示例

{
    "messageParam": {
        "WECHAT_WORK_ROBOT_NEWS": {
            "configIds": [
                "1449300018182877190"
            ],
            "param": {
                "articles": [
                    {
                        "title": "中秋节礼品领取",
                        "description": "今年中秋节公司有豪礼相送",
                        "url": "www.qq.com",
                        "picurl": "http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png"
                    }
                ]
            }
        }
    }
}

样例

markdown消息

字段	含义	类型	是否必须
content	markdown内容，最长不超过4096个字节，必须是utf8编码	String	是

请求示例

{
    "messageParam": {
        "WECHAT_WORK_ROBOT_MARKDOWN": {
            "configIds": [
                "1449300018182877190"
            ],
            "param": {
                "content": "实时新增用户反馈<font color=\"warning\">132例</font>，请相关同事注意。\n
         >类型:<font color=\"comment\">用户反馈</font>
         >普通用户反馈:<font color=\"comment\">117例</font>
         >VIP用户反馈:<font color=\"comment\">15例</font>"
            }
        }
    }
}

样例