登录
基础
连接微信
办公
企业内部开发 服务端API 应用管理 设置工作台自定义展示
设置工作台自定义展示
最后更新：2023/03/27
目录
在企业微信管理端启用工作台自定义展示，可以通过接口配置应用在企业微信移动端工作台的展示类型。具体可设置关键数据型、图片型、列表型以及webview型。如下图所示：
首先需要通过“设置应用在工作台展示的模版”接口设置应用自定义模版类型。然后再通过“设置应用在用户工作台展示的数据”接口设置用户模版数据。
“设置应用在工作台展示的模版”同时也支持设置一个默认的企业级别的模版数据。在用户数据未设置的情况下，会展示企业级别的默认数据。
模版类型数据结构
关键数据型
{
"items":[
{
"key":"待审批",
"data":"2",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"key":"带批阅作业",
"data":"4",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"key":"成绩录入",
"data":"45",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"key":"综合评价",
"data":"98",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
}
]
}
参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| items | 是 | 关键数据型数组，不超过4个 |
| items.key | 否 | 关键数据名称，需要设置在模版中 |
| items.data | 是 | 关键数据 |
| items.jump_url | 否 | 点击跳转url，若不填且应用设置了主页url，则跳转到主页url，否则跳到应用会话窗口 |
| items.pagepath | 否 | 若应用为小程序类型，该字段填小程序pagepath，若未设置，跳到小程序主页 |
type为 "keydata"
在工作台展示效果如下：
图片型
{
"url":"xxxx",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| url | 否 | 图片url。图片的最佳比例为3.35:1 |
| jump_url | 否 | 点击跳转url。若不填且应用设置了主页url，则跳转到主页url，否则跳到应用会话窗口 |
| pagepath | 否 | 若应用为小程序类型，该字段填小程序pagepath，若未设置，跳到小程序主页 |
type为 "image"
在工作台展示效果如下：
列表型
{
"items":[
{
"title":"智慧校园新版设计的小程序要来啦",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"title":"植物百科，这是什么花",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"title":"周一升旗通知，全体学生必须穿校服",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
}
]
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| items | 是 | 列表型数组，不超过3个 |
| items.title | 是 | 列表显示文字，不超过128个字节 |
| items.jump_url | 否 | 点击跳转url，若不填且应用设置了主页url，则跳转到主页url，否则跳到应用会话窗口 |
| items.pagepath | 否 | 若应用为小程序类型，该字段填小程序pagepath，若未设置，跳到小程序主页 |
type为 "list"
在工作台展示效果如下：
webview型
{
"url":"http://www.qq.com",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index",
"height":"single_row",
"hide_title":true,
"enable_webview_click":true
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| url | 否 | 渲染展示的url |
| jump_url | 否 | 点击跳转url。若不填且应用设置了主页url，则跳转到主页url，否则跳到应用会话窗口。如果enable_webview_click为true，则jump_url失效，点击不再跳转。 |
| pagepath | 否 | 若应用为小程序类型，该字段填小程序pagepath，若未设置，跳到小程序主页 |
| height | 否 | 高度。可以有两种选择：single_row与double_row。当为single_row时，高度与关键数据型一致，当为double_row时，高度固定为170px。默认值为double_row |
| hide_title | 否 | 是否要隐藏展示了应用名称的标题部分，默认值为false |
| enable_webview_click | 否 | 是否开启webview内的链接跳转能力，默认值为false。注意：开启之后，会使jump_url失效。链接跳转仅支持以下schema方式：wxwork://openurl?url=xxxx，注意url需要进行编码。参考示例：<a href="wxwork://openurl?url=https%3A%2F%2Fwork.weixin.qq.com%2F">今日要闻</a> |
type为 "webview"
在工作台展示效果如下：
设置应用在工作台展示的模版
请求说明：该接口指定应用自定义模版类型。同时也支持设置企业默认模版数据。若type指定为 "normal" 则为取消自定义模式，改为普通展示模式
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/agent/set_workbench_template?access_token=ACCESS_TOKEN
请求示例
{
"agentid":1000005,
"type":"image",
"image":{
"url":"xxxx",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
"replace_user_data":true
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| type | 是 | 模版类型，目前支持的自定义类型包括 "keydata"、 "image"、 "list"、 "webview" 。若设置的type为 "normal",则相当于从自定义模式切换为普通宫格或者列表展示模式 |
| agentid | 是 | 应用id |
| keydata | 否 | 若type指定为 "keydata"，且需要设置企业级别默认数据，则需要设置关键数据型模版数据,数据结构参考“关键数据型” |
| image | 否 | 若type指定为 "image"，且需要设置企业级别默认数据，则需要设置图片型模版数据,数据结构参考“图片型” |
| list | 否 | 若type指定为 "list"，且需要设置企业级别默认数据，则需要设置列表型模版数据,数据结构参考“列表型” |
| webview | 否 | 若type指定为 "webview"，且需要设置企业级别默认数据，则需要设置webview型模版数据,数据结构参考“webview型” |
| replace_user_data | 否 | 是否覆盖用户工作台的数据。设置为true的时候，会覆盖企业所有用户当前设置的数据。若设置为false,则不会覆盖用户当前设置的所有数据。默认为false |
权限说明：
可设置当前凭证对应的应用；
返回结果 ：
{
"errcode":0,
"errmsg":"ok"
}获取应用在工作台展示的模版
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/agent/get_workbench_template?access_token=ACCESS_TOKEN
请求示例：
{
"agentid":1000005
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| agentid | 是 | 应用id |
权限说明：
可设置当前凭证对应的应用；
返回结果 ：
{
"errcode":0,
"errmsg":"ok"
"type":"image",
"image":{
"url":"xxxx",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
"replace_user_data":true
}设置应用在用户工作台展示的数据
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/agent/set_workbench_data?access_token=ACCESS_TOKEN
请求示例
{
"agentid":1000005,
"userid":"test",
"type":"keydata",
"keydata":{
"items":[
{
"key":"待审批",
"data":"2",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"key":"带批阅作业",
"data":"4",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"key":"成绩录入",
"data":"45",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
},
{
"key":"综合评价",
"data":"98",
"jump_url":"http://www.qq.com",
"pagepath":"pages/index"
}
]
}
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| agentid | 是 | 应用id |
| userid | 是 | 需要设置的用户的userid |
| type | 是 | 目前支持 "keydata"、 "image"、 "list" 、"webview" |
| keydata | 否 | 若type指定为 "keydata"，则需要设置关键数据型模版数据,数据结构参考“关键数据型” |
| image | 否 | 若type指定为 "image"，则需要设置图片型模版数据，数据结构参考“图片型” |
| list | 否 | 若type指定为 "list"，则需要设置列表型模版数据，数据结构参考“列表型” |
| webview | 否 | 若type指定为 "webview"，则需要设置webview型模版数据，数据结构参考“webview数据型” |
权限说明：
可设置当前凭证对应的应用；设置的userid必须在应用可见范围
每个用户每个应用接口限制10次/分钟
修改设置工作台自定义开关事件推送
管理员在管理端应用详情页的自定义工作台页面启用或者停用自定义工作台模式时，会推送接收修改设置工作台自定义开关事件推送到应用的回调url上（如果是第三方应用为数据回调url）。事件推送处理过程详见接收消息与事件。 修改设置工作台自定义开关事件推送XML报文格式如下：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[switch_workbench_mode]]></Event>
<Mode>1</Mode >
<AgentID>1</AgentID>
</xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此处固定为sys |
| CreateTime | 消息创建时间（整型） |
| MsgType | 消息类型，此时固定为：event |
| Event | 事件类型：switch_workbench_mode，切换工作台自定义模式 |
| Mode | 1表示开启工作台自定义模式，0表示关闭工作台自定义模式 |
| AgentID | 企业应用的id，整型。可在应用的设置页面查看 |
