HOS基础开发平台

# 消息发送

# 1.概述

消息中心接收上游应用/用户发送的消息,再基于一定规则以邮件、短信、站内信等方式推送到下游应用。

# 2.系统内部发消息

系统内部如果有发消息的场景，例如登录时发验证码或者流程过程中发消息等，可以直接调用SendMessageUtil工具类发送消息。

方法名        方法说明
appPushMessageByChannel 自定义消息内容发消息
appPushMessageExistMegTemplate 根据消息模板的发消息

# 自定义消息内容发消息

用户按照需要发送的渠道自定义每个渠道发送的消息内容进行发消息。入参的详情如下：

{
 "priority": "",//优先级,1,2,3代表低、中、高，数字越大优先级越高
 "receiverType": "specified",//发送类型 specified选择对象,all广播所有，必填
 "sendTime": "2023-08-06 08:30:77",//发送日期，不指定代表即时发送
 "senderCode": "",//发送者账号
 "receiverData": {//如果receiverType是specified选择对象时填写，分为 post,user,dept,role 四个类型，每个类型都对应着相应的目标编码集合。多个类型可同时存在，必填
   "user": [
     "1001"
   ],
    "dept": [
      "DEPT001",
      "DEPT002"
   ],
    "post": [//简版不支持业务岗位
       "POST001",
       "POST002"
   ],
   "role": [
         "ROLE001",
         "ROLE002"
     ]
 },
 "channelData": {//每个渠道的发送内容，key为渠道彪马，value为内容体，不同类型渠道不同的内容格式，必填
   "005": {// 短信渠道demo
     "sign": "",//签名
     "templateData": { //模板配置数据
       "templateId": "SMS_154950909",//短信服务商的模板id,如果短信服务商不需要模板可以为空
       "paramData": {// 短信模板参数的参数配置数据
         "name": "尊敬的${rname}先生/女士"
       }
     },
     "content": "${name}您好"//要发送的内容，最终发送效果为：尊敬的${rname}先生/女士您好
   },
   "001": {//站内信demo
     "title": "测试哦",//标题
     "content": "您的工资已到账",//内容
     "website": "http://baidu.com"//链接
   },
   "002": {//邮件demo
     "title": "测试哦",//标题
     "content": "您的工资已到账",//内容
   }
 }
}

# 按照模板发送消息

按照预设好的消息模板发送消息，发送消息时，不需要给完整的消息内容，只需给出模板中需要的自定义变量的值即可。

{
 "priority": "",//优先级,1,2,3数字越大优先级越高
 "receiverType": "specified",//发送类型 specified选择对象,all广播所有，必填
 "sendTime": "2023-08-06 08:30:07",//发送日期,不指定代表即时发送
 "senderCode": "",//发送者账号
 "receiverData": {//如果receiverType是specified选择对象时填写，分为 post,user,dept,role 四个类型，每个类型都对应着相应的目标编码集合。多个类型可同时存在，必填
   "user": [
     "1001"
   ],
    "dept": [
      "DEPT001",
      "DEPT002"
   ],
    "post": [
       "POST001",
       "POST002"
   ],
   "role": [
         "ROLE001",
         "ROLE002"
     ]    
 },
 "templateCode": "1243123"//消息模板编码，必填
 "channelParamData": {///消息模板中自定义变量的值，key为变量名称value为具体的值
   "desc": "test"
 }
}

# 响应出参

{
	"code": 200,//编码
	"msg": "",//信息描述
    "msgId": "",//本次消息id,用于查询使用
    "data": ""//具体内容描述
}

响应编码说明

编码        说明
200 发送成功
200100 消息已成功加入定时任务
200200 发送成功,但是部分有问题
400 参数有误
400600 发送失败,详情请在在异常消息中查看
400100 参数格式不正确
400200 消息模板不存在
400300 发送目标不存在
400400 消息渠道不存在
400500 无法找到发送任务
401 发送成功,但是部分有问题
404 服务器无法取得所请求的网页，请求资源不存在
500 服务器内部错误

# 3.外部系统发消息

外部系统如果想通过消息中心发消息，则需要调用本系统发布的openapi实现消息的发送。消息中心对外发布了很多restful接口，供第三方系统调用。 为了识别消息的来源，外部系统发消息之前必须在第三方应用中注册应用，生成appId，后续发消息的时候必须将这个参数带上才能正常发消息。

# 3.1 发送普通消息【业务系统】

用户按照需要发送的渠道自定义每个渠道发送的消息内容进行发消息。

  • 接口说明
功能说明 发送普通消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/push/channel
  • 请求信息
  1. 参数详情
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用发送的消息
receiverType 接收目标类型 String 是 all代表广播，specified代表指定对像
receiverData 接收目标数据 JSONObject 否
channelData 渠道数据 JSONObject 是 渠道以及各个渠道的内容。不同类型渠道的格式也会有所不同
businessId 业务Id String 否 业务id，非必填
msgType 消息类别 String 否 消息的类别
priority 发送优先级 String 否 3、2、1，高、中、低， 不填就是中优先级
senderCode 发送者编码 String 否 发送人描述
sendTime 发送时间 Datetime 否 为空代表即时发送，定时消息时可设置此字段的数据
msgCategory 消息类型 String 是 0代表待阅消息，1代表待办消息，待办需要业务系统处理业务后才才算处理
mobileParam 移动端参数 JSONObject 否 需要在移动端展示时提供，具体根据业务系统移动端不同去提供.将需要的参数封装成json格式
  1. 接收目标详情receiverData
代码 名称 数据类型 是否必需 备注
user 用户 String Array 否 用户编码集合
dept 部门 String Array 否 部门编码集合
post 业务岗位 String Array 否 业务岗位编码集合(简版不支持业务岗位)
role 角色 String Array 否 角色编码集合
  1. 渠道数据详情channelData 不同的渠道类型返回的参数是不一样的，按照渠道编码为key，内容为value的形式传递数据。不同类型的渠道的内容格式如下. (1) 站内信
代码 名称 数据类型 是否必需 备注
title 标题 String 否
content 内容 String 是 支持html
website 消息详情链接 String 详情
mobileWebsite 移动端消息详情链接 String 移动端跳转地址 针对h5应用跳转需要

(2) 短信

代码 名称 数据类型 是否必需 备注
sign 短信签名 String 否
templateData 短信模板 JSONObject 否 {"templateId": "1001","paramData": {"code": "AAAb"} 必须通过短信模板发送消息的短信平台时需要的参数
content 自定义短信内容 String 否 自定义短信内容的短信平台

(3) 邮件

代码 名称 数据类型 是否必需 备注
title 邮件标题 String 否
content 邮件内容 String 是 支持html

请求消息完整示例（示例数据仅供参考，不代表实际业务数据）

{
     "appId": "102343444",
     "receiverType": "specified",
     "receiverData": {
       "user": [
         "USER001",
         "USER002"
       ],
       "dept": [
         "DEPT001",
         "DEPT002"
       ],
       "post": [
         "POST001",
         "POST002"
       ],
       "role": [
         "ROLE001",
         "ROLE002"
       ]
     },
     "channelData": {
       "001": {//渠道编码，以实际注册渠道编码为准
         "sign": "东华医为",
         "templateData": {
           "templateId": "T100101",
           "paramData": {
             "code": 1001,
             "time": 5
           }
         },
         "content": "这是我的第一条短信消息"
       },
       "002": {//渠道编码，以实际注册渠道编码为准
         "title": "发工资了",
         "content": "你好，您的工资已发，请及时查收！",
         "website": "http://xxxx",
         "mobileWebsite": "http://xxxx",
       },
       "003": {//渠道编码，以实际注册渠道编码为准
         "title": "邮件标题",
         "content": "邮件内容"
       }
     },
     "businessId":"xxxxxx",
     "priority": "2",
     "senderName": "张三",
     "sendTime": "2023-08-04 12:15:12",
     "msgCategory":"1",
     "mobileParam":{}
}
  • 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 String 是 见附录状态代码表
msg 状态描述 String 是 见附录状态代码表
msgId 消息Id String 否 消息发送异常时不返回

成功示例

{
"code": 200,
"msg": "操作成功",
"msgId": "消息ID"
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.2 发送模板消息【业务系统】

按照预设好的消息模板发送消息，发送消息时，不需要给完整的消息内容，只需给出模板中需要的自定义变量的值即可。

  • 接口说明
功能说明 根据预设的消息模板发送消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/push/template
  • 请求信息
  1. 参数详情
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用发送的消息
receiverType 接收目标类型 String 是 all代表广播，specified代表指定对像
receiverData 接收目标数据 JSONObject 否
templateCode 消息模板编码 String 是
channelParamData 模板变量数据 JSONObject 是 变量值集合。Key、value的形式传递
businessId 业务Id String 否 业务id，非必填
priority 发送优先级 String 否 3、2、1，高、中、低， 不填就是中优先级
senderCode 发送者编码 String 否 发送人描述
sendTime 发送时间 Datetime 否 为空代表即时发送，定时消息时可设置此字段的数据
msgCategory 消息类型 String 是 0代表待阅消息，1代表待办消息，待办需要业务系统处理业务后才才算处理
mobileParam 移动端参数 JSONObject 否 需要在移动端展示时提供，具体根据业务系统移动端不同去提供.将需要的参数封装成json格式
  1. 接收目标详情receiverData
代码 名称 数据类型 是否必需 备注
user 用户 String Array 否 用户编码集合
dept 部门 String Array 否 部门编码集合
post 业务岗位 String Array 否 业务岗位编码集合(简版不支持业务岗位)
role 角色 String Array 否 角色编码集合

请求消息完整示例（示例数据仅供参考，不代表实际业务数据）

{
  "appId": "102343444",
  "receiverType": "specified",
  "receiverData": {
     "user": [
        "USER001",
        "USER002"
     ],
     "dept": [
        "DEPT001",
        "DEPT002"
     ],
     "post": [
        "POST001",
        "POST002"
     ],
     "role": [
        "ROLE001",
        "ROLE002"
     ]
  },
  "templateCode": "MSG1001",
  "channelParamData": {
     "code": "Meidcal1001",
     "name": "患者001"
  },
  "businessId":"xxxxxx",
  "priority": "2",
  "senderName": "张三",
  "sendTime": "2023-08-04 12:15:12",
  "msgCategory":"1",
  "mobileParam":{}

}
  • 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 String 是 见附录状态代码表
msg 状态描述 String 是 见附录状态代码表

成功示例

{
"code": 200,
"msg": "操作成功",
"msgId": "消息ID"
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.3 获取未读未处理消息数量【移动端】

获取未读未处理的消息数量，【未处理的待办消息数量+未阅读的待阅消息数量】

  • 接口说明
功能说明 处理消息中心的待处理消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/receiver-open/get-inmail-count
  1. 请求信息
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用
userCode 用户账号 String 是 必填

请求信息完整示例 示例

{
"appId": "123456",
" userCode ": "admin"
}
  1. 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 varchar(10) 是 见附录状态代码表
msg 状态描述 varchar(100) 是 见附录状态代码表
data 返回数据 JSONObject 是
msgNum 消息数量 Int 是 未处理消息总数量，待阅消息未读和待办消息未处理
unreadNum 待阅消息未读数量 Int
untreatedNum 待办消息未处理数量 Int

成功示例

{
   "code": 200,
   "msg": "操作成功",
   "data": {
     "msgNum": 15,
     "unreadNum": 8,
     "untreatedNum": 7
   }
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.4 获取各个消息类别下的消息数量【移动端】

  • 接口说明
功能说明 处理消息中心的待处理消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/receiver-open/type-count
  1. 请求信息
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用
userCode 用户账号 String 是 必填
readStatus 阅读状态 String 否 阅读状态(false-未读，true-已读，空为不限)
handleStatus 处理状态 String 否 处理状态(false-未读，true-已读，空为不限)，如果是待阅消息，这个状态失效
startTime 开始日期 Datetime 否 发送时间
endTime 结束日期 Datetime 否 结束时间
search 标题或者内容 String 否 标题和内容
msgCategory 消息类型 String 是 0代表待阅消息，1代表待办消息
  1. 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 varchar(10) 是 见附录状态代码表
msg 状态描述 varchar(100) 是 见附录状态代码表
data 返回数据 JSONObject 是
msgType 消息类别编码 String 是 未处理消息总数量，待阅消息未读和待办消息未处理
msgTypeName 消息类别名称 String 是
sumNum 消息数量 Int 是

成功示例

{
   "code": 200,
   "msg": "操作成功",
   "data": [
      {
      "msgType": "all",
      "msgTypeName": "全部",
      "sumNum": 1
      },
      {
      "msgType": "notice",
      "msgTypeName": "通知",
      "sumNum": 1
      }
      ]
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.5 获取消息列表【移动端】

  • 接口说明
功能说明 处理消息中心的待处理消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/receiver-open/get-inmail-msg
  1. 请求信息
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用
size 一页显示数量 Int 否 分页参数
current 页码 Int 否 分页参数
msgType 消息类别 String 是 消息的类别，all代表全部
userCode 用户账号 String 是 必填
readStatus 阅读状态 String 否 阅读状态(false-未读，true-已读，空为不限)
handleStatus 处理状态 String 否 处理状态(false-未读，true-已读，空为不限)，如果是待阅消息，这个状态失效
startTime 开始日期 Datetime 否 发送时间
endTime 结束日期 Datetime 否 结束时间
search 标题或者内容 String 否 标题和内容
msgCategory 消息类型 String 是 0代表待阅消息，1代表待办消息
  1. 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 varchar(10) 是 见附录状态代码表
msg 状态描述 varchar(100) 是 见附录状态代码表
data 消息明细 JSONObject 是
records 列表数据 Jsonarray 是
total 消息总数量 Int 是
current 当前页 Int 是
pages 总页码 Int 是
size 一页显示数量 Int 是

消息列表字段详情records

代码 名称 数据类型 是否必需 备注
id 消息id String 是 消息id，是后续读消息的必填字段
senderName 发送者姓名 String 是 发送者姓名
title 消息标题 String 是 消息标题
content 消息内容 String 否 消息内容
url 链接地址 String 否 消息的链接地址，用于PC系统页面跳转
mobileUrl 移动端链接地址 String 否 移动端跳转地址，针对h5的移动应用
receiveTime 消息发送时间 String 是 消息发送时间
systemName 消息发送应用的名称 String 否 消息发送用的应用，内部发送则为空
priority 消息优先级 String 是 3、2、1，高、中、低
msgCategory 消息类型 String 是 0代表待阅，1代表待办
msgType 消息类别 String 否 消息类别编码
msgTypeName 消息名称 String 是 消息类别名称
readStatus 阅读状态 Boolean 是 是否阅读
handleStatus 处理状态 Boolean 是 待办消息的处理状态
readTime 阅读时间 DateTime 是 阅读时间
handleTime 处理时间 DateTime 否 处理时间
mobileParam 移动端参数 JSONObject 是 移动端展示必须的
appId 互联网平台appId String 否 小程序移动端跳转才需要
uniappId uniappId String 否 小程序移动端跳转才需要

成功示例

{
   "code": "200",
   "msg": "操作成功",
   "data": {
   "records": [
   {
   "id": "4367a77ae9ca49488e25c8c370f83862",
   "systemName": "测试应用",
   "senderName": "超级管理员",
   "receiverId": "3e2bdf84f7b4f94be2d8a72135f6c925",
   "title": "您有危急值消息，请注意查收",
   "content": "您有危急值消息，请注意查收",
   "url": "http://114.251.235.9:8327/third-party-app",
   "mobileUrl": "http://114.251.235.9:8327/third-party-app",
   "receiveTime": "2023-11-30 12:56:59",
   "priority": "2",
   "readStatus": true,
   "msgCategory": "1",
   "msgType": null,
   "msgTypeName": null,
   "handleStatus": false,
   "readTime": "2023-12-04 15:38:47",
   "handleTime": null,
   "mobileParam": {},
   "uniappId": "__UNI__A5B7AC1",
   "appId": "__UNI__A5B7AC1"
   }
   ],
   "total": 1,
   "size": 10,
   "current": 1,
   "orders": [],
   "optimizeCountSql": true,
   "searchCount": true,
   "countId": null,
   "maxLimit": null,
   "pages": 1
   },
   "success": true
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.6 阅读消息（通过消息ID）【移动端】

  • 接口说明
功能说明 阅读消息中心的未读消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/receiver-open/read-inmail-msg
  1. 请求信息
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用
msgId 消息ID String 是 消息ID，必填
readerCode 阅读者编码 String 是 阅读者编码，必填

请求信息完整示例 示例

{
"appId": "123456",
" msgId": " 041eb94eb779460ab922721cb88f0243",
"readerCode":"admin"
}
  1. 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 varchar(10) 是 见附录状态代码表
msg 状态描述 varchar(100) 是 见附录状态代码表

成功示例

{
"code": 200,
"msg": "操作成功"
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.7 处理消息 【业务系统】

待办消息，业务系统处理业务时调用消息中心的接口处理消息。

  • 接口说明
功能说明 处理消息中心的待办消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/receiver-open/handle-inmail-msg
  1. 请求信息
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用
templateCode 消息模板编码 String 否 消息模板编码
businessId 业务Id String 是 必填，需保证本应用内是唯一的，如果不能保证，必须的搭配发消息的模板使用，否则无法保证找到对应的消息
handlerCode 处理者编码 String 是 处理者编码，必填

请求信息完整示例 示例

{
   "appId": "123456",
   "templateCode": "MSG1001",
   "businessId": "xxxxx",
   "handlerCode":"admin"
}
  1. 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 varchar(10) 是 见附录状态代码表
msg 状态描述 varchar(100) 是 见附录状态代码表

成功示例

{
"code": 200,
"msg": "操作成功"
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.8 撤回消息（根据业务id） 【业务系统】

撤回已发的消息

  • 接口说明
功能说明 撤回已发送的消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/receiver-open/push/revoked-business
  1. 请求信息
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用
templateCode 消息模板编码 String 否 消息模板编码
businessId 业务Id String 是 必填，需保证本应用内是唯一的，如果不能保证，必须的搭配发消息的模板使用，否则无法保证找到对应的消息
handlerCode 撤回者编码 String 是 撤回者编码，必填

请求信息完整示例 示例

{
   "appId": "123456",
   "templateCode": "MSG1001",
   "businessId": "xxxxx",
   "handlerCode":"admin"
}
  1. 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 varchar(10) 是 见附录状态代码表
msg 状态描述 varchar(100) 是 见附录状态代码表

成功示例

{
"code": 200,
"msg": "操作成功"
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.9 撤回消息（根据messageId） 【业务系统】

根据发消息返回的messageId，撤回已发的消息。

  • 接口说明
功能说明 撤回已发送的消息
通讯方式 Http Post
数据编码 JSON ,UTF8
请求头格式 Content-Type: application/json
服务地址 http://ip:port/api/openApi/message/push/revoked-message
  1. 请求信息
代码 名称 数据类型 是否必需 备注
appId 应用Id String 是 用于识别哪个应用
messageId 消息发送Id String 是 发消息后，返回的messageId
handlerCode 撤回者编码 String 是 撤回者编码，必填

请求信息完整示例 示例

{
   "appId": "123456",
   " messageId": "xxxxx",
   "handlerCode":"admin"
}
  1. 应答信息
代码 名称 数据类型 是否必需 备注
code 状态代码 varchar(10) 是 见附录状态代码表
msg 状态描述 varchar(100) 是 见附录状态代码表

成功示例

{
"code": 200,
"msg": "操作成功"
}

失败示例

{
"code": 404,
"msg": "参数有误"
}

# 3.10 附录

  • 接口状态码
状态码 状态名称 状态说明
200 OK 代表发消息成功
401 Unauthorized 身份验证失败
400 Forbidden 参数有误
404 Not Found 服务器无法取得所请求的网页，请求资源不存在
500 Internal Server Error 服务器内部错误

← 安全 →