飞书（Lark）桥接 #

Meldry 自研的 飞书 桥接——字节跳动旗下的办公通讯套件（海外版叫 Lark）。与钉钉桥接类似，飞书协议是私有的，所以本桥接采用 webhook + 开放 API 模式，而非完整会话模拟。

国内版（feishu.cn）和国际版（larksuite.com）均支持——配置凭据时选择对应的 region 即可。

前置条件 #

  • Meldry 套餐： Business
  • 飞书 / Lark 工作区的管理员权限
  • 一个飞书应用：你可以在 飞书开放平台 创建（或使用已有的）并启用了 机器人能力
  • 应用的 app_id、app_secret 和 verification_token

启用桥接 #

  1. 仪表板 → 服务器 → 桥接 → 飞书 → 启用。
  2. 等约 10 秒。机器人出现在 @feishubot:<你的名称>.meldry.com。
  3. 仪表板显示 webhook URL：https://<你的名称>.meldry.com/bridges/feishu/webhook。复制下来。

配置飞书 #

第 1 步——创建飞书应用 #

  1. 访问 open.feishu.cn（国际版：open.larksuite.com）并登录。
  2. 开发者后台 → 创建企业自建应用。
  3. 填写名称、图标、说明。保存。
  4. 打开新创建的应用，复制 App ID 和 App Secret。

第 2 步——启用机器人能力 + 事件订阅 #

  1. 左侧边栏 能力配置 → 机器人 → 启用。
  2. 事件与回调 → 事件订阅：粘贴 Meldry 仪表板给的 webhook URL。
  3. 飞书会校验 URL（Meldry 的桥接 endpoint 会返回飞书要求的 challenge token）。
  4. 订阅以下事件：
    • im.message.receive_v1（接收消息）
    • im.chat.member.user.added_v1
    • im.chat.member.user.deleted_v1
    • im.chat.updated_v1
  5. 保存。页面顶部会显示 verification_token 和 encrypt_key，两个都复制下来。

第 3 步——开通必要的 API 权限 #

在开发者后台 权限管理 下启用：

  • im:message（收发消息）
  • im:chat（读取群元数据）
  • im:chat:readonly
  • im:message.group_at_msg（如果你要支持 @ 提及）
  • im:resource（上传图片/文件）

保存后提交给工作区管理员审批。

第 4 步——把应用关联到 Meldry #

给 @feishubot:<你的名称>.meldry.com 发私聊：

login <app_id> <app_secret> <verification_token> <encrypt_key> <region>

其中 <region> 为 cn（feishu.cn）或 intl（larksuite.com）。

机器人会去飞书开放 API 校验，然后回复 Logged in: <工作区名称>。

第 5 步——把应用装进目标群 #

  1. 在飞书里打开目标会话（群或 1 对 1）。
  2. 点 设置 → 添加机器人 → 自定义机器人。
  3. 选你刚创建的应用。
  4. 机器人在群里发一条确认消息。桥接检测到后即开始镜像这个群的消息。

会被桥接什么 #

  • 群聊 → Matrix 房间（每个飞书会话对应一个）。
  • 1 对 1 DM → Matrix DM 房间。
  • 文本、富文本、markdown、@ 提及、回复 → 双向。
  • 图片和文件 → 双向。
  • 飞书卡片（交互式 JSON 卡片） → 以 Matrix markdown + 附件链接形式展示。
  • 表情反应 → 双向（飞书较新租户已支持 reaction）。
  • 视频会议 / 妙记 / 云文档 → 不桥接（各自是独立产品，独立 API）。

命令列表 #

命令作用
login <app_id> <app_secret> <verification_token> <encrypt_key> <region>关联飞书应用
logout解绑
status查看最后事件 + API 状态
chats列出已桥接的会话
help完整命令列表

限制 #

  • 按会话启用。 和钉钉类似，机器人必须被显式加到每一个要桥接的会话里——没有"发现所有会话"的 API。
  • 编辑。 飞书允许发送后一小时内编辑消息。这段时间内的编辑会桥接；超时的编辑（很罕见）不会。
  • 删除。 删除事件会桥接，对应的 Matrix 消息会被撤回。
  • 已读回执。 飞书开放 API 不返回已读回执，因此不会同步到 Matrix。
  • 切换工作区。 一个桥接登录只绑定一个飞书租户。在多个租户里就登录多次。

故障排查 #

"事件验证失败"——飞书在设置事件时会用一个一次性 token 挑战 webhook。如果 Meldry endpoint 不可达（防火墙、工作区暂停等）就会失败。修好网络后再次保存事件订阅。

"应用权限缺失"——登录飞书开发者后台，检查所有必需权限都被工作区管理员批准了。新增的权限需要重新审批。

消息只能单向流动——确认应用确实装到了会话里（第 5 步）。如果机器人不在群里，从 Matrix 发出的消息就没地方落。

login 失败提示 invalid region——cn 对 feishu.cn，intl 对 larksuite.com，其他都不接受。

隐私提示 #

  • Meldry 与飞书之间的所有 API 流量都走 HTTPS，并用你提供的 encrypt_key 加密。
  • app_secret 和 encrypt_key 在你工作区内加密存储。
  • 解除关联会删除所存凭据并停止处理事件。

下一步 #