投票选择型和多项选择型卡片仅企业微信3.1.12及以上版本支持
文本通知型、图文展示型和按钮交互型三种卡片仅企业微信3.1.6及以上版本支持（但附件下载功能仍需更新至3.1.12）
微工作台（原企业号）不支持展示模板卡片消息
文本通知型
官网示例效果
参数示例
bash
{
"touser":"UserID1|UserID2|UserID3",
"toparty":"PartyID1 | PartyID2",
"totag":"TagID1 | TagID2",
"msgtype":"template_card",
"agentid":1,
"template_card":{
"card_type":"text_notice",
"source":{
"icon_url":"图片的url",
"desc":"企业微信",
"desc_color":1
},
"action_menu":{
"desc":"卡片副交互辅助文本说明",
"action_list":[
{
"text":"接受推送",
"key":"A"
},
{
"text":"不再推送",
"key":"B"
}
]
},
"task_id":"task_id",
"main_title":{
"title":"欢迎使用企业微信",
"desc":"您的好友正在邀请您加入企业微信"
},
"quote_area":{
"type":1,
"url":"https://work.weixin.qq.com",
"title":"企业微信的引用样式",
"quote_text":"企业微信真好用呀真好用"
},
"emphasis_content":{
"title":"100",
"desc":"核心数据"
},
"sub_title_text":"下载企业微信还能抢红包！",
"horizontal_content_list":[
{
"keyname":"邀请人",
"value":"张三"
},
{
"type":1,
"keyname":"企业微信官网",
"value":"点击访问",
"url":"https://work.weixin.qq.com"
},
{
"type":2,
"keyname":"企业微信下载",
"value":"企业微信.apk",
"media_id":"文件的media_id"
},
{
"type":3,
"keyname":"员工信息",
"value":"点击查看",
"userid":"zhangsan"
}
],
"jump_list":[
{
"type":1,
"title":"企业微信官网",
"url":"https://work.weixin.qq.com"
},
{
"type":2,
"title":"跳转小程序",
"appid":"小程序的appid",
"pagepath":"/index.html"
}
],
"card_action":{
"type":2,
"url":"https://work.weixin.qq.com",
"appid":"小程序的appid",
"pagepath":"/index.html"
}
},
"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 | 是 | 消息类型，此时固定为：template_card |
| agentid | 是 | 企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 [获取企业授权信息](#参数 是否必须 说明 touser 否 成员ID列表（消息接收者，多个接收者用‘|’分隔，最多支持1000个）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送 toparty 否 部门ID列表，多个接收者用‘|’分隔，最多支持100个。当touser为@all时忽略本参数 totag 否 标签ID列表，多个接收者用‘|’分隔，最多支持100个。当touser为@all时忽略本参数 msgtype 是 消息类型，此时固定为：template_card agentid 是 企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 获取企业授权信息 获取该参数值 card_type 是 模板卡片类型，文本通知型卡片填写 "text_notice" source 否 卡片来源样式信息，不需要来源样式可不填写 source.icon_url 否 来源图片的url，来源图片的尺寸建议为72*72 source.desc 否 来源图片的描述，建议不超过20个字，（支持id转译） source.desc_color 否 来源文字的颜色，目前支持：0(默认) 灰色，1 黑色，2 红色，3 绿色 action_menu 否 卡片右上角更多操作按钮 action_menu.desc 否 更多操作界面的描述 action_menu.action_list 是 操作列表，列表长度取值范围为 [1, 3] action_menu.action_list.text 是 操作的描述文案 action_menu.action_list.key 是 操作key值，用户点击后，会产生回调事件将本参数作为EventKey返回，回调事件会带上该key值，最长支持1024字节，不可重复 main_title.title 否 一级标题，建议不超过36个字，文本通知型卡片本字段非必填，但不可本字段和sub_title_text都不填，（支持id转译） main_title.desc 否 标题辅助信息，建议不超过44个字，（支持id转译） quote_area 否 引用文献样式 quote_area.type 否 引用文献样式区域点击事件，0或不填代表没有点击事件，1 代表跳转url，2 代表跳转小程序 quote_area.url 否 点击跳转的url，quote_area.type是1时必填 quote_area.appid 否 点击跳转的小程序的appid，必须是与当前应用关联的小程序，quote_area.type是2时必填 quote_area.pagepath 否 点击跳转的小程序的pagepath，quote_area.type是2时选填 quote_area.title 否 引用文献样式的标题 quote_area.quote_text 否 引用文献样式的引用文案 emphasis_content 否 关键数据样式 emphasis_content.title 否 关键数据样式的数据内容，建议不超过14个字 emphasis_content.desc 否 关键数据样式的数据描述内容，建议不超过22个字 sub_title_text 否 二级普通文本，建议不超过160个字，（支持id转译） horizontal_content_list 否 二级标题+文本列表，该字段可为空数组，但有数据的话需确认对应字段是否必填，列表长度不超过6 horizontal_content_list.type 否 链接类型，0或不填代表不是链接，1 代表跳转url，2 代表下载附件，3 代表点击跳转成员详情 horizontal_content_list.keyname 是 二级标题，建议不超过5个字 horizontal_content_list.value 否 二级文本，如果horizontal_content_list.type是2，该字段代表文件名称（要包含文件类型），建议不超过30个字，（支持id转译） horizontal_content_list.url 否 链接跳转的url，horizontal_content_list.type是1时必填 horizontal_content_list.media_id 否 附件的media_id，horizontal_content_list.type是2时必填 horizontal_content_list.userid 否 成员详情的userid，horizontal_content_list.type是3时必填 jump_list 否 跳转指引样式的列表，该字段可为空数组，但有数据的话需确认对应字段是否必填，列表长度不超过3 jump_list.type 否 跳转链接类型，0或不填代表不是链接，1 代表跳转url，2 代表跳转小程序 jump_list.title 是 跳转链接样式的文案内容，建议不超过18个字 jump_list.url 否 跳转链接的url，jump_list.type是1时必填 jump_list.appid 否 跳转链接的小程序的appid，必须是与当前应用关联的小程序，jump_list.type是2时必填 jump_list.pagepath 否 跳转链接的小程序的pagepath，jump_list.type是2时选填 card_action 是 整体卡片的点击跳转事件，text_notice必填本字段 card_action.type 是 跳转事件类型，1 代表跳转url，2 代表打开小程序。text_notice卡片模版中该字段取值范围为[1,2] card_action.url 否 跳转事件的url，card_action.type是1时必填 card_action.appid 否 跳转事件的小程序的appid，必须是与当前应用关联的小程序，card_action.type是2时必填 card_action.pagepath 否 跳转事件的小程序的pagepath，card_action.type是2时选填 task_id 否 任务id，同一个应用任务id不能重复，只能由数字、字母和“-@”组成，最长128字节，填了action_menu字段的话本字段必填 enable_id_trans 否 表示是否开启id转译，0表示否，1表示是，默认0 enable_duplicate_check 否 表示是否开启重复消息检查，0表示否，1表示是，默认0 duplicate_check_interval 否 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时) 获取该参数值 |
| card_type | 是 | 模板卡片类型，文本通知型卡片填写 "text_notice" |
| source | 否 | 卡片来源样式信息，不需要来源样式可不填写 |
| source.icon_url | 否 | 来源图片的url，来源图片的尺寸建议为72*72 |
| source.desc | 否 | 来源图片的描述，建议不超过20个字，（支持id转译） |
| source.desc_color | 否 | 来源文字的颜色，目前支持：0(默认) 灰色，1 黑色，2 红色，3 绿色 |
| action_menu | 否 | 卡片右上角更多操作按钮 |
| action_menu.desc | 否 | 更多操作界面的描述 |
| action_menu.action_list | 是 | 操作列表，列表长度取值范围为 [1, 3] |
| action_menu.action_list.text | 是 | 操作的描述文案 |
| action_menu.action_list.key | 是 | 操作key值，用户点击后，会产生回调事件将本参数作为EventKey返回，回调事件会带上该key值，最长支持1024字节，不可重复 |
| main_title.title | 否 | 一级标题，建议不超过36个字，文本通知型卡片本字段非必填，但不可本字段和sub_title_text都不填，（支持id转译） |
| main_title.desc | 否 | 标题辅助信息，建议不超过44个字，（支持id转译） |
| quote_area | 否 | 引用文献样式 |
| quote_area.type | 否 | 引用文献样式区域点击事件，0或不填代表没有点击事件，1 代表跳转url，2 代表跳转小程序 |
| quote_area.url | 否 | 点击跳转的url，quote_area.type是1时必填 |
| quote_area.appid | 否 | 点击跳转的小程序的appid，必须是与当前应用关联的小程序，quote_area.type是2时必填 |
| quote_area.pagepath | 否 | 点击跳转的小程序的pagepath，quote_area.type是2时选填 |
| quote_area.title | 否 | 引用文献样式的标题 |
| quote_area.quote_text | 否 | 引用文献样式的引用文案 |
| emphasis_content | 否 | 关键数据样式 |
| emphasis_content.title | 否 | 关键数据样式的数据内容，建议不超过14个字 |
| emphasis_content.desc | 否 | 关键数据样式的数据描述内容，建议不超过22个字 |
| sub_title_text | 否 | 二级普通文本，建议不超过160个字，（支持id转译） |
| horizontal_content_list | 否 | 二级标题+文本列表，该字段可为空数组，但有数据的话需确认对应字段是否必填，列表长度不超过6 |
| horizontal_content_list.type | 否 | 链接类型，0或不填代表不是链接，1 代表跳转url，2 代表下载附件，3 代表点击跳转成员详情 |
| horizontal_content_list.keyname | 是 | 二级标题，建议不超过5个字 |
| horizontal_content_list.value | 否 | 二级文本，如果horizontal_content_list.type是2，该字段代表文件名称（要包含文件类型），建议不超过30个字，（支持id转译） |
| horizontal_content_list.url | 否 | 链接跳转的url，horizontal_content_list.type是1时必填 |
| horizontal_content_list.media_id | 否 | 附件的media_id，horizontal_content_list.type是2时必填 |
| horizontal_content_list.userid | 否 | 成员详情的userid，horizontal_content_list.type是3时必填 |
| jump_list | 否 | 跳转指引样式的列表，该字段可为空数组，但有数据的话需确认对应字段是否必填，列表长度不超过3 |
| jump_list.type | 否 | 跳转链接类型，0或不填代表不是链接，1 代表跳转url，2 代表跳转小程序 |
| jump_list.title | 是 | 跳转链接样式的文案内容，建议不超过18个字 |
| jump_list.url | 否 | 跳转链接的url，jump_list.type是1时必填 |
| jump_list.appid | 否 | 跳转链接的小程序的appid，必须是与当前应用关联的小程序，jump_list.type是2时必填 |
| jump_list.pagepath | 否 | 跳转链接的小程序的pagepath，jump_list.type是2时选填 |
| card_action | 是 | 整体卡片的点击跳转事件，text_notice必填本字段 |
| card_action.type | 是 | 跳转事件类型，1 代表跳转url，2 代表打开小程序。text_notice卡片模版中该字段取值范围为[1,2] |
| card_action.url | 否 | 跳转事件的url，card_action.type是1时必填 |
| card_action.appid | 否 | 跳转事件的小程序的appid，必须是与当前应用关联的小程序，card_action.type是2时必填 |
| card_action.pagepath | 否 | 跳转事件的小程序的pagepath，card_action.type是2时选填 |
| task_id | 否 | 任务id，同一个应用任务id不能重复，只能由数字、字母和"-@"组成，最长128字节，填了action_menu字段的话本字段必填 |
| enable_id_trans | 否 | 表示是否开启id转译，0表示否，1表示是，默认0 |
| enable_duplicate_check | 否 | 表示是否开启重复消息检查，0表示否，1表示是，默认0 |
| duplicate_check_interval | 否 | 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时 |
调用企业微信API
卡片文本通知消息是企业应用消息中的一种类型，也是需要获取授权企业的access_token，
不清楚的可查看《企业微信应用文本》篇的获取【企业凭证】。
参数是根据实际调用设定的，去掉了部分非必须的参数。
实例如下：
php
/**
* 发起企业微信应用消息
* @param $access_token :授权企业access_token
* @param $params :消息参数
* @return array|mixed
*/
public function sendAppMsg($access_token, $params)
{
$url = 'https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=' . $access_token;
$info = $this->linkCurl($url, 'POST', $params);
$res = djson($info);
if (isset($res['errcode']) && $res['errcode'] != 0) {
return toFail($res['errmsg']);
}
return toSuccess('success', $res);
}
/**
* 发送卡片文本消息
* @param $authInfo
* @param $userid
* @param $res
* @return array|bool|mixed|string
*/
public function sendCardTextMsg($authInfo, $userid, $res)
{
$authInfo = [
'corpid' => '授权企业id',
'permanent_code' => '授权企业永久授权码',
'agentid' => '授权应用id'
];
$userid = '企业微信用户userid';
$res = [
'url' => '项目在浏览器中的路径',
'pagepath' => '小程序跳转路径',
'title' => '合同需处理',
'items' => [
'消息内容' => '与河北天翔服务有限公司的合同未完成签署，即将过期，请及时处理！',
'操作人员' => '于总',
'合同编号' => '20231205143706434243',
],
];
$url = $res['url'] ?? '';
$pagepath = $res['pagepath'] ?? '';
$title = $res['title'];
if (empty($res['items'])) {
return toFail('请输入消息内容参数');
}
$get_token = $this->getCompanyToken($authInfo['corpid'], $authInfo['permanent_code']);
if ($get_token['status'] != 1) {
return $get_token;
}
$access_token = $get_token['data']['token'] ?? '';
// 消息体处理
$content_list = [];
foreach ($res['items'] as $k => $v) {
$content_list[] = ['keyname' => $k, 'value' => $v];
}
$params = json([
"touser" => $userid,
"msgtype" => "template_card",
"agentid" => $authInfo['agentid'],
"template_card" => [
"card_type" => "text_notice",
"task_id" => "task_id",
"main_title" => [
"title" => "欢迎使用索服电子签",
"desc" => "您的好友正在邀请您加入索服电子签"
],
"sub_title_text" => $title,
"horizontal_content_list" => $content_list,
"jump_list" => [
[
"type" => 1,
"title" => "打开桌面应用",
"url" => $url,
],
[
"type" => 2,
"title" => "跳转小程序",
"appid" => "跳转小程序的appid",
"pagepath" => $pagepath
]
],
"card_action" => [
"type" => 1,
"url" => "官网地址"
]
]
]);
return $this->sendAppMsg($access_token, $params);
}
/**
* 请求接口返回内容
* @param $url : 请求的URL地址
* @param $method : 请求方式POST|GET
* @param bool $params : 请求的参数
* @param bool $header : 请求头
* @return bool|string
*/
protected function linkCurl($url, $method, $params = false, $header = false)
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_URL, $url);
//curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_FAILONERROR, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
if (strpos("$" . $url, "https://") == 1) {
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
}
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 60);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
if ($method == "POST") {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
} else if ($params) {
curl_setopt($ch, CURLOPT_URL, $url . '?' . http_build_query($params));
}
$response = curl_exec($ch);
if ($response === FALSE) return false;
curl_close($ch);
return $response;
}最终效果
总结
本篇主要是对企业微信应用消息-卡片模板消息的简单介绍和应用。之前项目中要使用应用模板消息通知用户，但是模板消息参数设置是：优先小程序跳转，其次如果没有小程序路径才会执行pc路径跳转；而我们要达到的效果是pc打开pc路径，手机端打开小程序；所以换成模板卡片-通知型消息。