钉钉桥接 #

Meldry 自研的钉钉桥接——钉钉是阿里巴巴旗下被中国企业广泛使用的办公通讯平台。由于钉钉协议是封闭的私有协议，本桥接采用 webhook 模式，而非完整会话模拟。功能比 Telegram 或 Slack 桥接少一些，但消息双向投递稳定可靠。

前置条件 #

  • Meldry 套餐： Business
  • 一个你有管理员权限的钉钉工作区，能创建"自定义机器人"和"企业内部应用"
  • 钉钉应用凭据：AppKey、AppSecret、AgentID——均可在 钉钉开放平台 获取

启用桥接 #

  1. 仪表板 → 服务器 → 桥接 → 钉钉 → 启用。
  2. 桥接容器启动。机器人出现在 @dingtalkbot:<你的名称>.meldry.com。
  3. 仪表板会显示一个 webhook URL，类似 https://<你的名称>.meldry.com/bridges/dingtalk/webhook。复制下来。

配置钉钉 #

第 1 步——创建钉钉企业内部应用 #

  1. 访问 open-dev.dingtalk.com 并登录。
  2. 应用开发 → 企业内部应用 → 创建应用。
  3. 填写应用名称、图标和说明。能力：选择 机器人（Bot）。
  4. 保存。平台返回 AppKey 和 AppSecret。

第 2 步——填入桥接凭据 #

  1. 给 @dingtalkbot:<你的名称>.meldry.com 发私聊：
    login <AppKey> <AppSecret> <AgentID>
  2. 机器人会去钉钉开放 API 校验并回复 Logged in: <你的工作区名称>。

第 3 步——把 webhook URL 配到钉钉 #

  1. 回到钉钉开发控制台，在 事件订阅 里粘贴 Meldry 仪表板上那个 webhook URL。
  2. 订阅：chat_message、chat_add_member、chat_remove_member、user_add_org。
  3. 保存。钉钉会校验这个 endpoint——成功后出现绿色对勾。

会被桥接什么 #

  • 群聊 → Matrix 房间。
  • 1 对 1 DM → Matrix DM 房间。
  • 文本、markdown 卡片、@ 提及 → 双向。
  • 图片和文件 → 双向，通过 Meldry 媒体库再次上传。
  • 卡片消息 → 以 Matrix markdown 形式渲染。
  • 语音消息 → 只从钉钉到 Matrix 单向（钉钉的入站消息 API 不接受第三方应用发送的语音二进制）。
  • 视频通话 → 不桥接（钉钉用的是自己的 RTC）。
  • 考勤、审批、日程卡片 → 在 Matrix 里以只读卡片消息显示。

命令列表 #

命令作用
login <AppKey> <AppSecret> <AgentID>关联钉钉应用
logout解绑当前工作区
status检查桥接状态 + 最后收到的事件
groups列出已桥接的群
bridge <matrix-room> <dingtalk-chat-id>手动桥接一个群
help完整命令列表

按需桥接某个群聊 #

钉钉不提供"群列表"查询 API 给机器人——每个群都需要在机器人被加入时手动桥接。操作步骤：

  1. 在钉钉里，把你在第 1 步创建的自定义机器人加到目标群。
  2. 机器人发送一条一次性确认消息。从那条消息里复制 chat ID。
  3. 在 Matrix 桥接 DM 里运行 bridge !matrix-room-id dingtalk-chat-id。

限制 #

  • Webhook 模式 意味着桥接只收到钉钉事件订阅转发的消息。一些高级消息类型（自定义卡片 schema）可能不支持。
  • 不支持消息编辑或删除——钉钉开放 API 在入站事件里不支持。
  • 没有表情反应（钉钉本身没有这个功能）。
  • 历史回填最多 7 天，因为事件订阅从"现在"开始向前。
  • 从 Matrix 发到钉钉的消息 由你创建的自定义机器人发出——钉钉用户看到的是"来自 [BotName]"，前缀是 [@Alice via Matrix]。

故障排查 #

login 返回 Invalid AppKey/AppSecret——仔细对照复制粘贴，钉钉区分大小写。

钉钉控制台里 webhook 显示"不可达"——你的 Meldry 工作区必须能从公网访问。从外部 curl https://<你的名称>.meldry.com/bridges/dingtalk/webhook 应该返回 200。

收不到消息——确认事件订阅是已启用状态，并指向当前的 webhook。钉钉在长时间故障后有时会默默暂停订阅。

机器人无法向 Matrix 发消息——桥接机器人需要房间的邀请权限。邀请 @dingtalkbot:<你的名称>.meldry.com 到目标房间并给它 50 级（moderator）权限。

隐私提示 #

  • 钉钉事件 payload 里包含发送者信息、会话元数据和消息内容。这些会经 HTTPS 发送到 Meldry webhook endpoint 并存入你的工作区数据库。
  • AppSecret 以加密形式存储在你工作区的私有存储中。
  • 解除桥接会删除凭据并停止处理事件订阅。

下一步 #