企业微信应用模板消息

是在发送应用消息接口的基础上，第三方应用支持一种新的消息类型：模板消息，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。其余来说没有什么难度。