是在发送应用消息接口的基础上,第三方应用支持一种新的消息类型:模板消息,msgtype指定为template_msg。模板消息是一种固定格式的消息。
注意
- 此消息类型目前仅第三方应用支持,自建应用不支持。服务商需在管理端申请模版。接口传参的内容必须与申请的模版匹配;
- 成员授权模式下,对于不在可见范围内的成员,第三方应用没有userid或open_userid,但可以通过传入合法且未过期的selected_ticket_list来推送模板消息,selected_ticket_list可通过返回ticket的选人接口获得。注意,管理员授权模式下,仅能给可见范围之内的成员推送消息,不在可见范围的成员将不能收到消息;
- 对于应用可见范围内的成员,直接通过touser指定即可,无须传入selected_ticket_list;
- 支持id转译,将userid/部门id转成对应的用户名/部门名。具体支持的范围和语法,请查看附录id转译说明。
设置模板
之前设置模板的时候,设置的【审批/汇报模板】还又是设置【应用和模板上线】,结果一直是测试提示模板不合法(改参数调试的一言难尽)。原来模板设置错位置了。
位置
在三方应用详情(我的是关联小程序应用详情)【应用通知模版】添加按钮。
注意:模板需要应用上线后才可设置。
如下图:
添加模板
点击新建模版,输入标题、关键字、示例内容、使用场景描述。
点击【保存】后,返回应用详情出现刚才添加的模板标题和模板ID。
获取企业token
此处不再是使用三方应用的凭证,而是使用授权企业的access_token;因为这里开始调用企业的接口,故使用企业的access_token。
官网文档 -> 获取企业凭证
获取企业凭证 - 接口文档 - 企业微信开发者中心
请求方式
POST(HTTPS)
请求地址
https://qyapi.weixin.qq.com/cgi-bin/service/get_corp_token?suite_access_token=SUITE_ACCESS_TOKEN
Post参数包体
{
"auth_corpid": "auth_corpid_value",
"permanent_code": "code_value"
}
参数说明
参数 | 是否必须 | 说明 |
suite_access_token | 是 | 三方应用token |
auth_corpid | 是 | 授权方企业corpid |
permanent_code | 是 | 永久授权码,通过授权安装应用时获取的授权企业永久码 |
返回结果
{
"errcode":0 ,
"errmsg":"ok" ,
"access_token": "xxxxxx",
"expires_in": 7200
}
返回参数说明
参数 | 说明 |
access_token | 授权方(企业)access_token,最长为512字节 |
expires_in | 授权方(企业)access_token超时时间 |
发送模板消息
请求方式
POST(HTTPS)
请求地址
https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN
请求示例
{
"touser":"zhangsan|lisi",
"agentid":10086,
"msgtype":"template_msg",
"template_msg":{
"template_id":"ttxxlGlgIAwJrCTFjtndfgHPoIySyk6w",
"url":"http://www.qq.com",
"miniprogram":{
"appid":"APPID",
"pagepath":"/index.html"
},
"content_item":[
{
"key":"消息内容",
"value":"您的合同模板已生成成功,点击查看详情"
},
{
"key":"合同名称",
"value":"电子签合同"
},
{
"key":"我方企业",
"value":"甲方"
}
]
}
}
示例效果
参数说明
参数 | 是否必须 | 说明 |
touser | 否 | 指定接收消息的成员,成员ID列表(多个接收者用‘|’分隔,最多支持1000个)。 特殊情况:指定为"@all",则向该企业应用的全部可见成员发送 |
toparty | 否 | 指定接收消息的部门,部门ID列表,多个接收者用‘|’分隔,最多支持100个。 当touser为"@all"时忽略本参数,成员授权模式下不应该传该参数 |
totag | 否 | 指定接收消息的标签,标签ID列表,多个接收者用‘|’分隔,最多支持100个。 当touser为"@all"时忽略本参数,成员授权模式下不应该传该参数 |
msgtype | 是 | 消息类型,此时固定为:template_msg |
template_msg | 是 | 消息内容 |
template_id | 是 | 模板ID。第三方管理端创建模板后获得。对于正式授权的应用,需要审批通过后才可使用。最长64字节 |
url | 否 | 点击模板消息后的跳转链接。最长2048字节。注意,url必须带协议头 "http://" 或 "https://" 。url和miniprogram 至少要填一个,都填时优先miniprogram。 |
content_item | 是 | 消息内容键值对,允许个数范围:1~5,实际由申请的模板样式决定 |
key | 是 | 1~20个utf8字符。注意,必须与template_id对应模板匹配 |
value | 是 | 1~40个utf8字符 |
selected_ticket_list | 否 | 选人sdk或者选人jsapi返回的ticket列表,列表不超过10个。接收者不包含selected_tikcet的操作者,若要发送给操作者,可将操作者填到touser字段。 |
enable_id_trans | 否 | 表示是否开启id转译,0表示否,1表示是,默认0。 |
only_unauth | 否 | 仅向selected_ticket_list中未授权的用户发送模板消息,仅当selected_ticket_list存在时该字段生效。如果该字段为true,则自动忽略touser,toparty,totag |
miniprogram | 否 | 点击后需要跳转的小程序,miniprogram和url至少要填一个,都填时优先miniprogram。 |
miniprogram.appid | 否 | 在miniprogram节点中该字段必填,小程序appid,必须是与当前应用关联的小程序 |
miniprogram.pagepath | 否 | 在miniprogram节点中该字段必填,表示点击消息卡片后的小程序页面,仅限本小程序内的页面。 |
返回结果
{
"errcode":0,
"errmsg":"ok",
"msgid":"WpLDpQFMGSE843kRbNhgXQSuKwNg1AelVDuIPfLpwWzvnRqidF_TfABTDAFK0DZQGdHxI8zDUkgHPOclC88whQ"
}
返回参数说明
参数 | 说明 |
errcode | 返回码 |
errmsg | 对返回码的文本描述内容 |
invaliduser | 不合法的userid,不区分大小写,统一转为小写 |
invalidparty | 不合法的partyid |
invalidtag | 不合法的标签id |
unlicenseduser | 没有基础接口许可(包含已过期)的userid |
msgid | 消息id,用于撤回应用消息 |
response_code | 仅消息类型为“按钮交互型”,“投票选择型”和“多项选择型”的模板卡片消息返回,应用可使用response_code调用更新模版卡片消息接口,72小时内有效,且只能使用一次 |
总结
发送企业微信模板消息,需要应用上线审核后,在应用详情设置模板后获得模板ID,这才是合法的模板ID。其余来说没有什么难度。