WhatsApp 桥接 #

基于 mautrix-whatsapp——目前最完整的 Matrix ↔ WhatsApp 桥接。使用与 WhatsApp Web / WhatsApp Desktop 相同的多设备配对机制，不需要重新注册手机号。

WhatsApp 原生采用 Signal 协议的 E2EE。桥接参与 WhatsApp 侧的加密，同时你的 Matrix 房间可以独立开启 E2EE——消息在每一跳都是加密的。

前置条件 #

  • Meldry 套餐： Business
  • 手机上能正常使用的 WhatsApp 账户——桥接把手机作为"主设备"，和关联 WhatsApp Web 是同一个机制
  • 配对时手机在线（之后如果手机下线，消息仍可继续同步，但首次配对要求手机能被访问）

启用桥接 #

  1. 仪表板 → 服务器 → 桥接 → WhatsApp → 启用。
  2. 等约 10 秒。机器人出现在 @whatsappbot:<你的名称>.meldry.com。

关联 WhatsApp 账户 #

  1. 在 Matrix 客户端给 @whatsappbot:<你的名称>.meldry.com 发私聊。
  2. 发送 login。
  3. 机器人回复一张 二维码图片。在 Matrix 客户端里放大显示。
  4. 在手机打开 WhatsApp → 设置 → 关联设备 → 关联新设备。摄像头对准二维码。
  5. WhatsApp 会把 Meldry 桥接注册为关联设备。机器人回复 Successfully logged in as +8613912345678。
  6. 桥接会在一分钟内把你最近的聊天回填为 Matrix 房间。

会被桥接什么 #

  • 1 对 1 聊天 → Matrix DM 房间，联系人的显示名和头像被傀儡化。
  • 群组 → 一个 WhatsApp 空间下的 Matrix 房间。
  • 媒体——照片、视频、语音消息、文件、贴纸。全部下载，重新加密后上传到 Matrix。
  • 表情反应、回复、编辑、删除 → 双向。
  • 已读回执 → 双向，遵循你的 WhatsApp 隐私设置。
  • 状态动态 → 不桥接（WhatsApp 的 Stories 不在多设备 API 里）。
  • 社群和广播列表 → 部分支持。
  • 语音/视频通话 → 不桥接（WhatsApp 基于 Signal 协议的通话无法被代理）。

命令列表 #

命令作用
login启动二维码配对
logout解绑（同时从手机"关联设备"列表中移除）
status查看关联状态
list-contacts列出 WhatsApp 联系人
pm <+国家代码号码>给某个 WhatsApp 号码发 DM
sync强制重新同步所有聊天
help完整命令列表

关联设备上限 #

WhatsApp 允许每个手机号最多 4 台关联设备（加上手机本身共 5 台）。如果你已经在电脑上用 WhatsApp Web、WhatsApp Desktop 和 iPad 版 WhatsApp，桥接的登录会占满第四个位置。在手机 设置 → 关联设备 里查看当前占用情况。

手机离线时的表现 #

老版（非多设备）WhatsApp 桥接要求手机一直在线。现在的多设备桥接在手机关机时也能继续运行——但有两点：

  • 在刚关联后的 约 14 天内，WhatsApp 可能要求手机每隔几天联网一次，否则关联会失效。
  • 过了"适应期"后，桥接可独立运行。

如果手机长时间离线导致关联被撤销，重新运行 login 扫一次新二维码即可。

故障排查 #

二维码过期——WhatsApp 每约 30 秒刷新一次二维码。错过时间窗再跑一次 login。

"WhatsApp 说这个设备已经关联过"——在手机 设置 → 关联设备 里移除旧的 Meldry 条目，再重新 login。

消息突然停止同步——关联被撤销。常见原因是手机系统升级或长时间离线。重新 login。

联系人名字缺失——WhatsApp 多设备 API 只给你手机已同步过的联系人。先在手机上打开那个聊天，然后在桥接私聊里运行 sync。

媒体下载不下来——Meldry 桥接会把媒体下载到你工作区的媒体库。查看存储配额（仪表板 → 服务器 → 资源）。

隐私提示 #

  • 桥接期间你的 WhatsApp 消息会经过 Meldry 基础设施。两端都是 E2EE，但在桥接进程里会被瞬时解密再重新加密给 Matrix。
  • 手机号保存在桥接数据库中。删除桥接会一并删除凭据。
  • 除 Matrix 房间状态所需的内容外，Meldry 不记录或保留消息内容。

下一步 #