第三方应用开发 服务端API 家校沟通 基础接口 发送「学校通知」
发送「学校通知」

目录

  • 概述
  • 接口定义
  • 消息类型
  •       文本消息
  •       图片消息
  •       语音消息
  •       视频消息
  •       文件消息
  •       图文消息
  •       图文消息(mpnews)
  •       小程序消息
  • 概述

    学校可以通过此接口来给家长发送不同类型的学校通知,来满足多种场景下的学校通知需求。目前支持的消息类型为文本、图片、语音、视频、文件、图文。

    接口定义


    请求方式:POST(HTTPS
    请求地址: https://qyapi.weixin.qq.com/cgi-bin/externalcontact/message/send?access_token=ACCESS_TOKEN

    参数说明:

    参数是否必须说明
    access_token调用接口凭证
    各个消息类型的具体POST格式参考以下文档。
    支持id转译,将userid/部门id转成对应的企业通讯录内部的用户名/部门名,目前仅文本/图文/图文(mpnews)/小程序消息这四种消息类型的部分字段支持。具体支持的范围和语法,请查看附录id转译说明
    支持重复消息检查,当指定 "enable_duplicate_check": 1开启: 表示在一定时间间隔内,同样内容(请求json)的消息,不会重复收到;时间间隔可通过duplicate_check_interval指定,默认1800秒

     

    权限说明:

    • 学校管理员需要将应用配置在「家长可使用的应用」才可调用

     

    返回示例:

    {
      "errcode" : 0,
      "errmsg" : "ok",
      "invalid_external_user" : ["external_userid1"],
      "invalid_parent_userid" : ["parent_userid1"],
      "invalid_student_userid" : ["student_userid1"],
      "invalid_party" : ["party1"]
    }
    如果部分接收人无权限或不存在,发送仍然执行,但会返回无效的部分(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个)
    toall1表示发送给学校的所有家长,默认为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个)
    toall1表示发送给学校的所有家长,默认为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个)
    toall1表示发送给学校的所有家长,默认为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个)
    toall1表示发送给学校的所有家长,默认为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个)
    toall1表示发送给学校的所有家长,默认为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个)
    toall1表示发送给学校的所有家长,默认为0
    msgtype消息类型,此时固定为:news
    agentid企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
    articles图文消息,一个图文消息支持1到8条图文
    title标题,不超过128个字节,超过会自动截断(支持id转译)
    description描述,不超过512个字节,超过会自动截断(支持id转译)
    url点击后跳转的链接。
    picurl图文消息的图片链接,支持JPG、PNG格式,较好的效果为大图 1068*455,小图150*150。
    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个)
    toall1表示发送给学校的所有家长,默认为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个)
    toall1表示发送给学校的所有家长,默认为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小时

     

    小程序消息展现:

    上一篇
    管理「学校通知」的关注模式
    下一篇
    获取外部联系人详情