# 消息卡片回传交互（旧） **消息卡片回传交互**作用于消息卡片的 **请求回调** 交互组件。当终端用户点击飞书卡片上的回传交互组件后，你在开发者后台应用内注册的回调请求地址将会收到 **卡片回传交互** 回调。该回调包含了用户与卡片之间的交互信息。 你的业务服务器接收到回调请求后，需要在 3 秒内响应回调请求，声明通过弹出 Toast 提示、更新卡片、保持原内容不变等方式响应用户交互。 **注意事项**：本文档提供旧版本的消息卡片回调结构和示例。了解最新版本的回调，参考[卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)。 ## 回调 基本信息 |   ---|--- 回调类型 | card.action.trigger_v1 支持的应用类型 | Custom App、Store App 权限要求
**订阅该事件所需的权限，开启其中任意一项权限即可订阅**
开启任一权限即可 | 暂无 字段权限要求 | **注意事项**：事件结构体中存在 `user_id` 敏感字段，仅当应用开启“获取用户 user ID”权限后才会返回。
获取用户 user ID(contact:user.employee_id:readonly) 推送方式 | [Webhook](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM) ## 回调结构体 字段 | 数据类型 | 描述 ---|---|--- open_id | string | 用户的 open_id。关于用户 open_id、user_id 的介绍，可参见[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。 user_id | string | 用户的 user_id。 tenant_key | string | 租户标识。参数介绍可参见[通用参数](https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/terminology)。 token | string | 更新卡片用的凭证。 open_message_id | string | 消息 ID。 action | object | 交互信息。 value | object/ string | 交互组件绑定的开发者自定义回传数据，对应组件中的 value 属性。类型为 string 或 object，可由开发者指定。 tag | string | 交互组件的标签。 timezone | string | 用户当前所在地区的时区。当用户操作日期选择器、时间选择器、或日期时间选择器时返回。 name | string | 组件的自定义唯一标识，用于识别内嵌在表单容器中的某个组件。 form_value | object | 表单容器内用户提交的数据。示例值：
```JSON
{
"field name 1": [ // 表单容器内某多选组件的 name 和 value
"selectDemo1",
"selectDemo2"
],
"field name 2": "value 2", // 表单容器内某交互组件的 name 和 value
"field name 3": "value 3", // 表单容器内某交互组件的 name 和 value
}
``` input_value | string | 当输入框组件未内嵌在表单容器中时，用户在输入框中提交的数据。 option | string | 当折叠按钮组、下拉选择-单选、人员选择-单选、日期选择器、时间选择器、日期时间选择器组件未内嵌在表单容器中时，用户选择该类组件某个选项时，组件返回的选项回调值。 options | string[] | 当下拉选择-多选组件和人员选择-多选组件未内嵌在表单容器中时，用户选择该类组件某个选项时，组件返回的选项回调值。 checked | bool | 当勾选器组件未内嵌在表单容器中时，勾选器组件的回调数据。 ## 回调结构体示例 ```json { "open_id": "ou_sdfimx9948345", // 卡片操作用户的 open_id "user_id": "eu_sd923r0sdf5", // 卡片操作用户的 user_id "open_message_id": "om_abcdefg1234567890", // 卡片消息的唯一 id "tenant_key": "d32004232", // 卡片消息归属的租户id "token": "c-xxxxx", // 更新卡片用的 Token（凭证） "action": { // 用户操作交互组件回传的数据 "value": { // 交互组件绑定的开发者自定义回传数据，对应组件中的 value 属性。类型为 string 或 object，可由开发者指定。 "key": "value" }, "tag": "button", // 交互组件的标签 "timezone": "Asia/Shanghai", // 用户当前所在地区的时区。当用户操作日期选择器、时间选择器、或日期时间选择器时返回 "form_value": { // 表单容器内用户提交的数据 "field name1": [ // 表单容器内某多选组件的 name 和 value "selectDemo1", "selectDemo2" ], "field name2": "value2", // 表单容器内某交互组件的 name 和 value "DatePicker_bpqdq5puvn4": "2024-04-01 +0800", // 表单容器内日期选择器组件的 name 和 value "DateTimePicker_ihz2d7a74i": "2024-04-29 07:07 +0800", // 表单容器内日期时间选择器组件的 name 和 value "Input_lf4fmxwfrd9": "1234", // 表单容器内输入框组件的 name 和 value "PersonSelect_2ejys7ype7m": "ou_3c14f3a59eaf2825dbe25359f15*****", // 表单容器内人员选择-单选组件的 name 和 value "Select_a2d5b7l3zd": "1", // 表单容器内下拉选择-单选组件的 name 和 value "TimePicker_7ecsf6xkqsq": "00:00 +0800" // 表单容器内时间选择器组件的 name 和 value }, "name": "Button_lvkepfu3" // 用户操作交互组件的名称，由开发者自定义 } } ``` ## 响应回调的结构体 你的业务服务器接收到回调请求后，需要在 3 秒内响应回调请求，声明通过弹出 Toast 提示、更新卡片、保持原内容不变等方式响应用户交互。以下为使用卡片 JSON 代码和卡片模板响应的字段说明。 ### 使用卡片 JSON 代码响应 字段 | 数据类型 | 描述 ---|---|--- toast | object | 客户端的 Toast 弹窗提示。 type | string | 提示类型。可选值：
- info
- success
- error
- warning content | string | 单语言提示文案。要配置多语言提示文案，请使用 `i18n` 字段。 i18n | Map | 多语言提示文案。示例配置：
```json
{
"i18n": {
"zh_cn": "更新成功！",
"en_us": "Successful update"
}
}
``` key | string | 语言。可选值：
- `zh_cn`: 简体中文
- `en_us`: 英文
- `zh_hk`: 繁体中文（香港）
- `zh_tw`: 繁体中文（台湾）
- `ja_jp`: 日语
- `id_id`: 印尼语
- `vi_vn`: 越南语
- `th_th`: 泰语
- `pt_br`: 葡萄牙语
- `es_es`: 西班牙语
- `ko_kr`: 韩语
- `de_de`: 德语
- `fr_fr`: 法语
- `it_it`: 意大利语
- `ru_ru`: 俄语
- `ms_my`: 马来语 value | string | 语言对应的文案。 header | object | 卡片标题。详见[了解卡片结构](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)。 elements/i18n_elements | object | 卡片正文内容。详见[了解卡片结构](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)。 config | object | 卡片配置。详见[了解卡片结构](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)。 card_link | string | 用于指定卡片整体的跳转链接。详见[了解卡片结构](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)。 ### 使用卡片模板响应 字段 | 数据类型 | 描述 ---|---|--- toast | object | 客户端的 Toast 弹窗提示。 type | string | 提示类型。可选值：
- info
- success
- error
- warning content | string | 单语言提示文案。要配置多语言提示文案，请使用 `i18n` 字段。 i18n | Map | 多语言提示文案。示例配置：
```json
{
"i18n": {
"zh_cn": "更新成功！",
"en_us": "Successful update"
}
}
``` key | string | 语言。可选值：
- `zh_cn`: 简体中文
- `en_us`: 英文
- `zh_hk`: 繁体中文（香港）
- `zh_tw`: 繁体中文（台湾）
- `ja_jp`: 日语
- `id_id`: 印尼语
- `vi_vn`: 越南语
- `th_th`: 泰语
- `pt_br`: 葡萄牙语
- `es_es`: 西班牙语
- `ko_kr`: 韩语
- `de_de`: 德语
- `fr_fr`: 法语
- `it_it`: 意大利语
- `ru_ru`: 俄语
- `ms_my`: 马来语 value | string | 语言对应的文案。 type | string | 使用卡片模板 ID 发送卡片消息时该参数必填，且固定取值为 `template`。 data | object | 卡片模板内的数据。使用卡片模板 ID 发送卡片消息时该参数必填。 template_id | string | 搭建工具中创建的卡片（也称卡片模板）的 ID，如 ctp_igYkzabcef。可在搭建工具中通过复制卡片 ID 获取。 template_variable | object | 如果卡片模板内设置了变量，则可以在此处为变量名（key）赋值（value）。详情参考[配置卡片变量](https://open.feishu.cn/document/ukTMukTMukTM/ucTNwUjL3UDM14yN1ATN/configure-card-variables)。 template_version_name | string | 新版搭建工具中创建的卡片的版本号，如 1.0.0。卡片发布后，将生成版本号。可在搭建工具 **版本管理** 处获取。 ## 错误码 在飞书客户端（ 7.28 及以上版本）进行卡片交互时，若交互出错，将返回如下图对应的错误码。错误码说明及解决方案请参考[卡片回传交互-错误码](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication#c98c3220)。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/29558d328f22a099dc8ce5c66bf4e5ba_lAVAomjl4R.png?height=64&lazyload=true&width=285) ## SDK 调用方式说明 你可前往 GtiHub 获取各个语言的卡片回调示例代码： - [Java](https://github.com/larksuite/oapi-sdk-java#%E5%A4%84%E7%90%86%E5%8D%A1%E7%89%87%E8%A1%8C%E4%B8%BA%E5%9B%9E%E8%B0%83) - [Python](https://github.com/larksuite/oapi-sdk-python#%E5%A4%84%E7%90%86%E5%8D%A1%E7%89%87%E8%A1%8C%E4%B8%BA%E5%9B%9E%E8%B0%83) - [Golang](https://github.com/larksuite/oapi-sdk-go#%E5%A4%84%E7%90%86%E5%8D%A1%E7%89%87%E8%A1%8C%E4%B8%BA%E5%9B%9E%E8%B0%83) - [Node.js](https://github.com/larksuite/node-sdk/blob/main/README.zh.md#%E6%B6%88%E6%81%AF%E5%8D%A1%E7%89%87-1)