添加卡片回传交互
1. 配置回调地址
消息卡片支持回传交互，指用户操作交互组件后，向开发者的服务端提交用户操作数据的交互。开发者可以根据收到用户提交的信息，请求更新卡片内容，及时对用户的交互行为进行反馈。
如果需要配置卡片回调，则需要在开发者后台 api 发送页配置卡片回调地址，回调地址要求为公网可以访问到的地址。
注意：配置后该地址无法删除，只能修改。目前并没有对地址进行合法性校验，接入方需自己保证地址可用。
回传方式：POST 方式，将内容放在 body 回传。回传请求会加上 WPS-4 签名认证。
当接入方应用收到回传内容后，返回{"result":"ok"}代表成功。
2. 发送消息
调用 发送消息接口 发送带有交互组件的卡片消息，action 中的 key 字段，用于在回调时使第三方区分具体的 action 事件。以审批卡片为例：
{
"to_users": {
"company_id": "11111",
"company_uids": ["11111"]
},
"app_key": "WK202xxxx3141501",
"biz_type": "test",
"ctx_id": "11111",
"company_id": "11111",
"company_uid": "11111",
"utype": 1,
"msg_type": 23,
"content": {
"type": 23,
"content": {
"header": {
"title": {
"tag": "text",
"content": {
"type": "plainText",
"text": "发起申请-林亮的请假申请：带薪年假/福利年假"
}
}
},
"elements": [
{
"tag": "text",
"content": {
"type": "markdown",
"text": "开始时间：2021-11-18 09:00:00 \n 结束时间：2021-11-19 18:00:00 \n请假原因：带薪年假\n\n"
}
},
{
"tag": "text",
"content": {
"type": "markdown",
"text": "[查看详情]($url_val)"
},
"href": {
"url_val": {
"url": "https://xz.wps.cn/",
"android_url": "https://xz.wps.cn/",
"ios_url": "https://xz.wps.cn/",
"pc_url": "https://xz.wps.cn/"
}
}
},
{
"tag": "action",
"actions": [
{
"tag": "button",
"content": {
"type": "plainText",
"text": "拒绝"
},
"key": "key1",
"style": "secondary"
},
{
"tag": "button",
"content": {
"type": "plainText",
"text": "同意"
},
"key": "key2",
"style": "normal"
}
]
}
]
}
}
}
配置卡片消息更新方式
卡片消息分为独享和共享，其含义如下：
共享： 当将一个卡片发送给多个用户时，多个用户共享该卡片，即业务方或某一用户对卡片进行修改，则所有用户的卡片均会改变。
独享： 开启独享功能后，当将一个卡片发送给多个用户时，多个用户对该卡片状态相互独立，即某一用户对卡片进行修改，只会影响到该用户的卡片状态。发送消息时，卡片内容config中添加update_single=true即可发送独享卡片。若不配置该选项，则默认为共享卡片。
注意： 独享卡片，目前仅支持立即更新实现卡片修改。
{
"header": {
...
},
"elements": [
...
],
"config": {
"update_single": true // 是否开启独享功能
}
}
3. 回调消息
用户点击交互组件时触发回调，会将组件携带 key 和其余信息回传。在此例中，用户点击同意/拒绝按钮时，服务端会将对应的按钮 key 数据取出拼接数据，作为请求 body 传输。以下分别为用户点击同意、拒绝时回传请求 body 数据举例：
{
"company_id": "11111", // 企业id
"app_ctx_id": "11111", // 消息上下文id
"content": {
// 回传具体内容
"action": "key2" // 同意
},
"company_uid": "11111" // 操作用户id
}
{
"company_id": "11111", // 企业id
"app_ctx_id": "11111", // 消息上下文id
"content": {
// 回传具体内容
"action": "key1", // 拒绝
"input": "输入框内容" // 当有弹框组件时，会以tag=modal中name值作为字段名
},
"company_uid": "11111" // 操作用户id
}
4. 更新消息
当通过回调接口发送信息给业务方后，业务方有两种方式更新卡片消息，回调接口响应更新、或者更新接口更新。
回调接口响应更新： 只能更新独享卡片，无需业务方再调用"更新接口"，减少请求次数。
更新接口更新： 目前只能更新共享卡片，业务方可自由控制更新时间，较为灵活。
（1）回调接口更新
当通过回调接口发送信息给业务方后，业务方可以立即响应该请求，返回要更新的卡片内容。只允许更新 tag=action 元素内容。具体格式如下：
{
"result": "ok",
"update_card": {
"tag_action_index": [2],
"i18n_tag_action_index": {
"zh-TW": [2],
"en-US": [2]
},
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"content": {
"type": "plainText",
"text": "已同意"
},
"style": "disable",
"key": "key3"
}
]
}
],
"i18n": {
"zh-TW": {
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"content": {
"type": "plainText",
"text": "已同意"
},
"style": "disable",
"key": "key3"
}
]
}
]
},
"en-US": {
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"content": {
"type": "plainText",
"text": "Granted"
},
"style": "disable",
"key": "key3"
}
]
}
]
}
}
}
}
update_card 中具体字段说明：
- tag_action_index 代表原发送消息 elements 中需要更新组件索引
- elements 代表需要替换的的 tag=action 组件内容
- i18n_tag_action_index 代表原发送消息多语言内容 各多语言 elements 中需要更新组件索引
- i18n 代表需要替换的多语言组件内容, map 类型，key 为多语言标识 简体中文 zh-CN 繁体中文 zh-TW 英文 en-US，values 格式 {"elements": [...]}, elements 为对应多语言需要替换的的 tag=action 组件内容
（2）调用更新消息接口更新
当需要对卡片消息进行修改时，可调用 更新消息接口 进行卡片消息修改，由业务方自己控制更新时间，更新消息接口只允许更新 tag=action 元素内容。请求 body 示例：
{
"app_key": "WK202xxxx3141501",
"ctx_id": "11111",
"utype": 1,
"operator": "123",
"content": {
"body": {
"tag_action_index": [2],
"i18n_tag_action_index": {
"zh-TW": [2],
"en-US": [2]
},
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"content": {
"type": "plainText",
"text": "已同意"
},
"style": "disable",
"key": "key3"
}
]
}
],
"i18n": {
"zh-TW": {
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"content": {
"type": "plainText",
"text": "已同意"
},
"style": "disable",
"key": "key3"
}
]
}
]
},
"en-US": {
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"content": {
"type": "plainText",
"text": "Granted"
},
"style": "disable",
"key": "key3"
}
]
}
]
}
}
}
}
}
- tag_action_index 代表原发送消息 elements 中需要更新组件索引
- elements 代表需要替换的的 tag=action 组件内容
- i18n_tag_action_index 代表原发送消息多语言内容 各多语言 elements 中需要更新组件索引
- i18n 代表需要替换的多语言组件内容, map 类型，key 为多语言标识 简体中文 zh-CN 繁体中文 zh-TW 英文 en-US，values 格式 {"elements": [...]}, elements 为对应多语言需要替换的的 tag=action 组件内容