发送「学校通知」
POST
/cgi-bin/externalcontact/message/send
服务端API企业内部开发第三方应用开发
各个消息类型的具体POST格式参考以下文档。
支持id转译，将userid/部门id转成对应的企业通讯录内部的用户名/部门名，目前仅文本/图文/图文（mpnews）/小程序消息这四种消息类型的部分字段支持。具体支持的范围和语法，请查看附录id转译说明。
支持重复消息检查，当指定"enable_duplicate_check": 1开启: 表示在一定时间间隔内，同样内容（请求json）的消息，不会重复收到；时间间隔可通过duplicate_check_interval指定，默认1800秒。
如果部分接收人无权限或不存在，发送仍然执行，但会返回无效的部分（inavlid_external_user/invalid_parent_userid/invalid_student_userid/invalid_party）。
消息类型
文本消息
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "msgtype" : "text", "agentid" : 1, "text" : { "content" : "你的快递已到，请携带工卡前往邮件中心领取。\n出发前可查看<a href=\"http://work.weixin.qq.com\">邮件中心视频实况</a>，聪明避开排队。" }, "enable_id_trans": 0, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表，即将废弃（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表，表示发给学生的所有家长（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表，表示发给班级的所有家长（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：text |
| agentid | 是 | 企业应用的id，整型。可在应用的设置页面查看 |
| content | 是 | 消息内容，最长不超过2048个字节**（支持id转译）** |
| enable_id_trans | 否 | 表示是否开启id转译，0表示否，1表示是，默认0 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
图片消息
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "msgtype" : "image", "agentid" : 1, "image" : { "media_id" : "MEDIA_ID" }, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表，即将废弃（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表，表示发给学生的所有家长（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表，表示发给班级的所有家长（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：image |
| agentid | 是 | 企业应用的id，整型。可在应用的设置页面查看 |
| media_id | 是 | 图片媒体文件id，可以调用上传临时素材接口获取 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
语音消息
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "msgtype" : "voice", "agentid" : 1, "voice" : { "media_id" : "MEDIA_ID" }, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表，即将废弃（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表，表示发给学生的所有家长（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表，表示发给班级的所有家长（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：voice |
| agentid | 是 | 企业应用的id，整型。可在应用的设置页面查看 |
| media_id | 是 | 语音文件id，可以调用上传临时素材接口获取 |
| enable_duplicate_check | 否 | 表 示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
视频消息
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "msgtype" : "video", "agentid" : 1, "video" : { "media_id" : "MEDIA_ID", "title" : "Title", "description" : "Description" }, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表，即将废弃（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表，表示发给学生的所有家长（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表，表示发给班级的所有家长（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：video |
| agentid | 是 | 企业应用的id，整型。可在应用的设置页面查看 |
| media_id | 是 | 视频媒体文件id，可以调用上传临时素材接口获取 |
| title | 否 | 视频消息的 标题，不超过128个字节，超过会自动截断 |
| description | 否 | 视频消息的描述，不超过512个字节，超过会自动截断 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
文件消息
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "msgtype" : "file", "agentid" : 1, "file" : { "media_id" : "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o" }, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表，表示发给学生的所有家长（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表，表示发给班级的所有家长（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：file |
| agentid | 是 | 企业应用的id，整型。可在应用的设置页面查看 |
| media_id | 是 | 文件id，可以调用上传临时素材接口获取 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
图文消息
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "msgtype" : "news", "agentid" : 1, "news" : { "articles" : [ { "title" : "中秋节礼品领取", "description" : "今年中秋节公司有豪礼相送", "url" : "URL", "picurl" : "http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png" } ] }, "enable_id_trans": 0, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表，即将废弃（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表，表示发给学生的所有家长（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表，表示发给班级的所有家长（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：news |
| agentid | 是 | 企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 获取企业授权信息 获取该参数值 |
| articles | 是 | 图文消息，一个图文消息支持1到8条图文 |
| title | 是 | 标题，不超过128个字节，超过会自动截断**（支持id转译）** |
| description | 否 | 描述，不超过512个字节，超过会自动截断**（支持id转译）** |
| url | 是 | 点击后跳转的链接。 |
| picurl | 否 | 图文消息的图片链接，支持JPG、PNG格式，较好的效果为大图 1068455，小图150150。 |
| enable_id_trans | 否 | 表示是否开启id转译，0表示否，1表示是，默认0 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
图文消息（mpnews）
mpnews类型的图文消息，跟普通的图文消息一致，唯一的差异是图文内容存储在企业微信。
多次发送mpnews，会被认为是不同的图文，阅读、点赞的统计会被分开计算。
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "msgtype" : "mpnews", "agentid" : 1, "mpnews" : { "articles":[ { "title": "Title", "thumb_media_id": "MEDIA_ID", "author": "Author", "content_source_url": "URL", "content": "Content", "digest": "Digest description" } ] }, "enable_id_trans": 0, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表，即将废弃（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表，表示发给学生的所有家长（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表，表示发给班级的所有家长（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：mpnews |
| agentid | 是 | 企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 获取企业授权信息 获取该参数值 |
| articles | 是 | 图文消息，一个图文消息支持1到8条图文 |
| title | 是 | 标题，不超过128个字节，超过会自动截断 （支持id转译） |
| thumb_media_id | 是 | 图文消息缩略图的media_id, 可以通过素材管理接口获得。此处thumb_media_id即上传接口返回的media_id |
| author | 否 | 图文消息的作者，不超过64个字节 |
| content_source_url | 否 | 图文消息点击“阅读原文”之后的页面链接 |
| content | 是 | 图文消息的内容，支持html标签，不超过666 K个字节 （支持id转译） |
| digest | 否 | 图文消息的描述，不超过512个字节，超过会自动截断 （支持id转译） |
| enable_id_trans | 否 | 表示是否开启id转译，0表示否，1表示是，默认0 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
小程序消息
{ "to_external_user" : ["external_userid1", "external_userid2"], "to_parent_userid": ["parent_userid1", "parent_userid2"], "to_student_userid": ["student_userid1", "student_userid2"], "to_party": ["partyid1", "partyid2"], "toall" : 0, "agentid" : 1, "msgtype" : "miniprogram", "miniprogram" : { "appid": "APPID", "title": "欢迎报名夏令营", "thumb_media_id": "MEDIA_ID", "pagepath": "PAGE_PATH" }, "enable_id_trans": 0, "enable_duplicate_check": 0, "duplicate_check_interval": 1800}| 参数 | 是否必须 | 说明 |
|---|---|---|
| to_external_user | 否 | 已关注「学校通知」的家长列表，即将废弃（最多支持1000个） |
| to_parent_userid | 否 | 家校通讯录家长列表（最多支持1000个） |
| to_student_userid | 否 | 家校通讯录学生列表（最多支持1000个） |
| to_party | 否 | 家校通讯录部门列表（最多支持100个） |
| toall | 否 | 1表示发送给学校的所有家长，默认为0 |
| msgtype | 是 | 消息类型，此时固定为：miniprogram |
| agentid | 是 | 企业应用的id，整型。可在应用的设置页面查看 |
| appid | 是 | 小程序appid，必须是关联到企业的小程序应用 |
| title | 否 | 小程序消息标题，最多64个字节，超过会自动截断**（支持id转译）** |
| thumb_media_id | 是 | 小程序消息封面的mediaid，封面图建议尺寸为520*416 |
| pagepath | 是 | 点击消息卡片后进入的小程序页面路径 |
| enable_id_trans | 否 | 表示是否开启id转译，0表示否，1表示是，默认0 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
原文档地址：
https://open.work.weixin.qq.com/api/doc/90000/90135/91609
https://open.work.weixin.qq.com/api/doc/90001/90143/92291
https://open.work.weixin.qq.com/api/doc/90000/90135/92321
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location -g --request POST 'https://qyapi.weixin.qq.com/cgi-bin/externalcontact/message/send?access_token='响应示例响应示例
{
"errcode": 0,
"errmsg": "string",
"invalid_external_user": [
"string"
],
"invalid_parent_userid": [
"string"
],
"invalid_student_userid": [
"string"
],
"invalid_party": [
"string"
]
}请求参数
Query 参数
access_token
调用接口凭证
示例值:
{{accesstoken}}
返回响应
扫码加入交流群