发送应用消息

[TOC]

接口定义

应用支持推送文本、图片、视频、文件、图文等类型。

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

参数说明:

参数 是否必须 说明
access_token 调用接口凭证

各个消息类型的具体POST格式请阅后续“消息类型”部分。
如果有在管理端对应用设置“在微工作台中始终进入主页”,应用在微信端只能接收到文本消息,并且文本消息的长度限制为20字节,超过20字节会被截断。同时其他消息类型也会转换为文本消息,提示用户到企业微信查看。
支持id转译,将userid/部门id转成对应的用户名/部门名,目前仅文本/文本卡片/图文/图文(mpnews)这四种消息类型的部分字段支持。具体支持的范围和语法,请查看附录id转译说明
支持重复消息检查,当指定 "enable_duplicate_check": 1开启: 表示在一定时间间隔内,同样内容(请求json)的消息,不会重复收到;时间间隔可通过duplicate_check_interval指定,默认1800秒

返回示例:

 {
   "errcode" : 0,
   "errmsg" : "ok",
   "invaliduser" : "userid1|userid2",
   "invalidparty" : "partyid1|partyid2",
   "invalidtag": "tagid1|tagid2"
 }

如果部分接收人无权限或不存在,发送仍然执行,但会返回无效的部分(即invaliduser或invalidparty或invalidtag),常见的原因是接收人不在应用的可见范围内
如果全部接收人无权限或不存在,则本次调用返回失败,errcode为81013。
返回包中的userid,不区分大小写,统一转为小写

消息类型

文本消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1|PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype" : "text",
   "agentid" : 1,
   "text" : {
       "content" : "你的快递已到,请携带工卡前往邮件中心领取。\n出发前可查看<a href=\"http://work.weixin.qq.com\">邮件中心视频实况</a>,聪明避开排队。"
   },
   "safe":0,
   "enable_id_trans": 0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

参数说明:

参数 是否必须 说明
touser 指定接收消息的成员,成员ID列表(多个接收者用‘|’分隔,最多支持1000个)。
特殊情况:指定为”@all”,则向该企业应用的全部成员发送
toparty 指定接收消息的部门,部门ID列表,多个接收者用‘|’分隔,最多支持100个。
当touser为”@all”时忽略本参数
totag 指定接收消息的标签,标签ID列表,多个接收者用‘|’分隔,最多支持100个。
当touser为”@all”时忽略本参数
msgtype 消息类型,此时固定为:text
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
content 消息内容,最长不超过2048个字节,超过将截断(支持id转译)
safe 表示是否是保密消息,0表示否,1表示是,默认0
enable_id_trans 表示是否开启id转译,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

touser、toparty、totag不能同时为空,后面不再强调。

文本消息展现:

特殊说明:
其中text参数的content字段可以支持换行、以及A标签,即可打开自定义的网页(可参考以上示例代码)(注意:换行符请用转义过的\n)

图片消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1|PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype" : "image",
   "agentid" : 1,
   "image" : {
        "media_id" : "MEDIA_ID"
   },
   "safe":0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

请求参数:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
msgtype 消息类型,此时固定为:image
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
media_id 图片媒体文件id,可以调用上传临时素材接口获取
safe 表示是否是保密消息,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

语音消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1|PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype" : "voice",
   "agentid" : 1,
   "voice" : {
        "media_id" : "MEDIA_ID"
   },
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
msgtype 消息类型,此时固定为:voice
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
media_id 语音文件id,可以调用上传临时素材接口获取
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

视频消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1|PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype" : "video",
   "agentid" : 1,
   "video" : {
        "media_id" : "MEDIA_ID",
        "title" : "Title",
       "description" : "Description"
   },
   "safe":0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
msgtype 消息类型,此时固定为:video
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
media_id 视频媒体文件id,可以调用上传临时素材接口获取
title 视频消息的标题,不超过128个字节,超过会自动截断
description 视频消息的描述,不超过512个字节,超过会自动截断
safe 表示是否是保密消息,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

视频消息展现:

文件消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1|PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype" : "file",
   "agentid" : 1,
   "file" : {
        "media_id" : "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o"
   },
   "safe":0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
msgtype 消息类型,此时固定为:file
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
media_id 文件id,可以调用上传临时素材接口获取
safe 表示是否是保密消息,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

文件消息展现:

文本卡片消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1 | PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype" : "textcard",
   "agentid" : 1,
   "textcard" : {
            "title" : "领奖通知",
            "description" : "<div class=\"gray\">2016年9月26日</div> <div class=\"normal\">恭喜你抽中iPhone 7一台,领奖码:xxxx</div><div class=\"highlight\">请于2016年10月10日前联系行政同事领取</div>",
            "url" : "URL",
            "btntxt":"更多"
   },
   "enable_id_trans": 0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
msgtype 消息类型,此时固定为:textcard
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
title 标题,不超过128个字节,超过会自动截断(支持id转译)
description 描述,不超过512个字节,超过会自动截断(支持id转译)
url 点击后跳转的链接。
btntxt 按钮文字。 默认为“详情”, 不超过4个文字,超过自动截断。
enable_id_trans 表示是否开启id转译,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

文本卡片消息展现 :

特殊说明
卡片消息的展现形式非常灵活,支持使用br标签或者空格来进行换行处理,也支持使用div标签来使用不同的字体颜色,目前内置了3种文字颜色:灰色(gray)、高亮(highlight)、默认黑色(normal),将其作为div标签的class属性即可,具体用法请参考上面的示例。

图文消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1 | PartyID2",
   "totag" : "TagID1 | TagID2",
   "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
}

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
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,会被认为是不同的图文,阅读、点赞的统计会被分开计算。

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1 | PartyID2",
   "totag": "TagID1 | TagID2",
   "msgtype" : "mpnews",
   "agentid" : 1,
   "mpnews" : {
       "articles":[
           {
               "title": "Title", 
               "thumb_media_id": "MEDIA_ID",
               "author": "Author",
               "content_source_url": "URL",
               "content": "Content",
               "digest": "Digest description"
            }
       ]
   },
   "safe":0,
   "enable_id_trans": 0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
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转译)
safe 表示是否是保密消息,0表示可对外分享,1表示不能分享且内容显示水印,2表示仅限在企业内分享,默认为0;注意仅mpnews类型的消息支持safe值为2,其他消息类型不支持
enable_id_trans 表示是否开启id转译,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

markdown消息

目前仅支持markdown语法的子集
微工作台(原企业号)不支持展示markdown消息

请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1|PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype": "markdown",
   "agentid" : 1,
   "markdown": {
        "content": "您的会议室已经预定,稍后会同步到`邮箱` 
                >**事项详情** 
                >事 项:<font color=\"info\">开会</font> 
                >组织者:@miglioguan 
                >参与者:@miglioguan、@kunliu、@jamdeezhou、@kanexiong、@kisonwang 
                > 
                >会议室:<font color=\"info\">广州TIT 1楼 301</font> 
                >日 期:<font color=\"warning\">2018年5月18日</font> 
                >时 间:<font color=\"comment\">上午9:00-11:00</font> 
                > 
                >请准时参加会议。 
                > 
                >如需修改会议信息,请点击:[修改会议信息](https://work.weixin.qq.com)"
   },
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

示例效果:

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
msgtype 消息类型,此时固定为:markdown
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
content markdown内容,最长不超过2048个字节,必须是utf8编码
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

小程序通知消息

小程序通知消息只允许小程序应用发送,之前,消息会通过统一的会话【小程序通知】发送给用户
从2019年6月28日起,用户收到的小程序通知会出现在各个独立的小程序应用中。
小程序应用仅支持发送小程序通知消息,暂不支持文本、图片、语音、视频、图文等其他类型的消息。
不支持@all全员发送

请求示例:

{
   "touser" : "zhangsan|lisi",
   "toparty": "1|2",
   "totag": "1|2",
   "msgtype" : "miniprogram_notice",
   "miniprogram_notice" : {
        "appid": "wx123123123123123",
        "page": "pages/index?userid=zhangsan&orderid=123123123",
        "title": "会议室预订成功通知",
        "description": "4月27日 16:16",
        "emphasis_first_item": true,
        "content_item": [
            {
                "key": "会议室",
                "value": "402"
            },
            {
                "key": "会议地点",
                "value": "广州TIT-402会议室"
            },
            {
                "key": "会议时间",
                "value": "2018年8月1日 09:00-09:30"
            },
            {
                "key": "参与人员",
                "value": "周剑轩"
            }
        ]
    },
   "enable_id_trans": 0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

示例效果:

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。
msgtype 消息类型,此时固定为:miniprogram_notice
appid 小程序appid,必须是与当前小程序应用关联的小程序
page 点击消息卡片后的小程序页面,仅限本小程序内的页面。该字段不填则消息点击后不跳转。
title 消息标题,长度限制4-12个汉字(支持id转译)
description 消息描述,长度限制4-12个汉字(支持id转译)
emphasis_first_item 是否放大第一个content_item
content_item 消息内容键值对,最多允许10个item
key 长度10个汉字以内
value 长度30个汉字以内(支持id转译)
enable_id_trans 表示是否开启id转译,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

任务卡片消息

仅企业微信2.8.2及以上版本支持
请求示例:

{
   "touser" : "UserID1|UserID2|UserID3",
   "toparty" : "PartyID1 | PartyID2",
   "totag" : "TagID1 | TagID2",
   "msgtype" : "taskcard",
   "agentid" : 1,
   "taskcard" : {
            "title" : "赵明登的礼物申请",
            "description" : "礼品:A31茶具套装<br>用途:赠与小黑科技张总经理",
            "url" : "URL",
            "task_id" : "taskid123",
            "btn":[
                {
                    "key": "key111",
                    "name": "批准",
                    "replace_name": "已批准",
                    "color":"red",
                    "is_bold": true
                },
                {
                    "key": "key222",
                    "name": "驳回",
                    "replace_name": "已驳回"
                }
            ]
   },
   "enable_id_trans": 0,
   "enable_duplicate_check": 0,
   "duplicate_check_interval": 1800
}

参数说明:

参数 是否必须 说明
touser 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。特殊情况:指定为@all,则向关注该企业应用的全部成员发送
toparty 部门ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
totag 标签ID列表,多个接收者用‘|’分隔,最多支持100个。当touser为@all时忽略本参数
msgtype 消息类型,此时固定为:taskcard
agentid 企业应用的id,整型。企业内部开发,可在应用的设置页面查看;第三方服务商,可通过接口 获取企业授权信息 获取该参数值
title 标题,不超过128个字节,超过会自动截断(支持id转译)
description 描述,不超过512个字节,超过会自动截断(支持id转译)
url 点击后跳转的链接。最长2048字节,请确保包含了协议头(http/https)
task_id 任务id,同一个应用发送的任务卡片消息的任务id不能重复,只能由数字、字母和“_-@”组成,最长支持128字节
btn 按钮列表,按钮个数为1~2个。
btn:key 按钮key值,用户点击后,会产生任务卡片回调事件,回调事件会带上该key值,只能由数字、字母和“_-@”组成,最长支持128字节
btn:name 按钮名称
btn:replace_name 点击按钮后显示的名称,默认为“已处理”
btn:color 按钮字体颜色,可选“red”或者“blue”,默认为“blue”
btn:is_bold 按钮字体是否加粗,默认false
enable_id_trans 表示是否开启id转译,0表示否,1表示是,默认0
enable_duplicate_check 表示是否开启重复消息检查,0表示否,1表示是,默认0
duplicate_check_interval 表示是否重复消息检查的时间间隔,默认1800s,最大不超过4小时

任务卡片消息展现 :

特殊说明

  1. 任务卡片消息的展现形式非常灵活,支持使用br标签或者空格来进行换行处理,也支持使用div标签来使用不同的字体颜色,目前内置了3种文字颜色:灰色(gray)、高亮(highlight)、默认黑色(normal),将其作为div标签的class属性即可,具体用法请参考上面的示例。
  2. 如果应用配置了回调URL,用户点击任务卡片的按钮后,企业微信会回调任务卡片事件到该URL。
  3. 开发者可以通过更新任务卡片消息状态接口更新卡片状态。

附录

支持的markdown语法

目前应用消息中支持的markdown语法是如下的子集:

  1. 标题 (支持1至6级标题,注意#与文字中间要有空格)
    # 标题一
    ## 标题二
    ### 标题三
    #### 标题四
    ##### 标题五
    ###### 标题六
    
  2. 加粗
    **bold**
    
  3. 链接
    [这是一个链接](http://work.weixin.qq.com/api/doc)
    
  4. 行内代码段(暂不支持跨行)
    `code`
    
  5. 引用
    > 引用文字
    
  6. 字体颜色(只支持3种内置颜色)
    <font color="info">绿色</font>
    <font color="comment">灰色</font>
    <font color="warning">橙红色</font>
    

id转译说明

1.支持的消息类型和对应的字段

消息类型 支持字段
文本(text) content
文本卡片(textcard) title、description
图文(news) title、description
图文(mpnews) title、digest、content
任务卡片(taskcard) title、description
小程序(miniprogram) title、digest、content_item.value

2.id转译模版语法

$departmentName=DEPARTMENT_ID$
$userName=USERID$

其中 DEPARTMENT_ID 是数字类型的部门id,USERID 是成员帐号
譬如,
$departmentName=1$替换成部门id为“1”对应的部门名,如“企业微信产品部”;
$userName=lisi007$替换成userid为“lisi007”对应的用户名,如“李四”;

© 1998 - 2020 Tencent Inc. All Rights Reserved