77 lines
5.1 KiB
Markdown
77 lines
5.1 KiB
Markdown
发送应用消息
|
||
最后更新：2025/09/24
|
||
接口定义
|
||
应用支持推送文本、图片、视频、文件、图文等类型。
|
||
|
||
请求方式：POST（HTTPS）
|
||
请求地址： https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN
|
||
|
||
参数说明：
|
||
|
||
参数 是否必须 说明
|
||
access_token 是 调用接口凭证
|
||
- 各个消息类型的具体POST格式请阅后续“消息类型”部分。
|
||
- 如果有在管理端对应用设置“在微工作台中始终进入主页”，应用在微信端只能接收到文本消息，并且文本消息的长度限制为20字节，超过20字节会被截断。同时其他消息类型也会转换为文本消息，提示用户到企业微信查看。
|
||
- 支持id转译，将userid/部门id转成对应的用户名/部门名，在企业授权了会话内容存档接口权限时，也可以将消息id和群id转成对应的消息内容/群名称，目前仅文本/文本卡片/图文/图文（mpnews）/任务卡片/小程序通知/模版消息/模板卡片消息这八种消息类型的部分字段支持。具体支持的范围和语法，请查看附录id转译说明。
|
||
- 支持重复消息检查，当指定 "enable_duplicate_check": 1开启: 表示在一定时间间隔内，同样内容（请求json）的消息，不会重复收到；时间间隔可通过duplicate_check_interval指定，默认1800秒。
|
||
- 从2021年2月4日开始，企业关联添加的「小程序」应用，也可以发送文本、图片、视频、文件、图文等各种类型的消息了。
|
||
调用建议：大部分企业应用在每小时的0分或30分触发推送消息，容易造成资源挤占，从而投递不够及时，建议尽量避开这两个时间点进行调用。
|
||
频率限制：每应用不可超过账号上限数*200人次/天（注：若调用api一次发给1000人，算1000人次；若企业账号上限是500人，则每个应用每天可发送100000人次的消息）。每应用对同一个成员不可超过30次/分钟，1000次/小时，超过部分会被丢弃不下发
|
||
返回示例：
|
||
|
||
{
|
||
"errcode" : 0,
|
||
"errmsg" : "ok",
|
||
"invaliduser" : "userid1|userid2",
|
||
"invalidparty" : "partyid1|partyid2",
|
||
"invalidtag": "tagid1|tagid2",
|
||
"unlicenseduser" : "userid3|userid4",
|
||
"msgid": "xxxx",
|
||
"response_code": "xyzxyz"
|
||
}
|
||
如果部分接收人无权限或不存在，发送仍然执行，但会返回无效的部分（即invaliduser或invalidparty或invalidtag或unlicenseduser），常见的原因是接收人不在应用的可见范围内。
|
||
权限包含应用可见范围和基础接口权限(基础账号、互通账号均可)，unlicenseduser中的用户在应用可见范围内但没有基础接口权限。
|
||
如果全部接收人无权限或不存在，则本次调用返回失败，errcode为81013。
|
||
返回包中的userid，不区分大小写，统一转为小写
|
||
|
||
|
||
|
||
---
|
||
文本卡片消息
|
||
请求示例：
|
||
```
|
||
{
|
||
"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 是 点击后跳转的链接。最长2048字节，请确保包含了协议头(http/https)
|
||
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属性即可，具体用法请参考上面的示例。 |