飞书卡片交互排障手册

问题描述

在飞书与 Hermes 集成中，交互卡片（带按钮的卡片消息）能正常显示，但用户点击按钮时回调失败，报错码 200340。

这个问题在官方文档中信息分散，排查容易走弯路。经过多次实战，沉淀出标准三步排查法。

三步排查法

第一步：检查事件订阅

进入飞书开放平台 → 事件订阅，确认以下事件已订阅：

• card.action.trigger — 卡片按钮点击事件

这一步最容易漏。卡片能显示 ≠ 能交互，必须显式订阅此事件。

第二步：检查 Bot 能力

进入飞书开放平台 → 应用能力，确认：

• 机器人 → 交互卡片 已启用

飞书默认不开启 Bot 的交互卡片能力，需要手动打开。

第三步：检查 Webhook 回调地址

如果使用 Webhook 模式（非 WebSocket 长连接），还需确认：

• 消息卡片请求网址（Message Card Request URL）指向与 Webhook 相同的地址

Webhook 收到消息和卡片回调是同一个入口，卡片 URL 没配，回调就到不了后端。

补充排查

以上三步都查了还没解决：检查飞书应用是否已发布（体验版可能未生效）；确认 NO_PROXY 环境变量包含飞书相关域名（代理可能阻断回调）；查看 Hermes gateway 日志中是否有回调请求到达。

教训

遇到飞书集成问题，先查官方文档再看日志。飞书的错误码体系成熟，200340 有明确的配置对应关系，猜原因不如查文档。