WhatsApp 集成

通过关联设备扫码（Linked Device）或 Meta WhatsApp Business Cloud API 将 WhatsApp 接入 Mopheus。

WhatsApp 集成支持两种接入模式，将智能体或团队连接到 WhatsApp：

关联设备扫码（Linked Device）（linked_device）：基于 WhatsApp 多设备 WebSocket 协议（whatsmeow）将 Mopheus 作为从属设备配对，Signal 端到端加密密钥加密持久化在 PostgreSQL 中，无需公网 Webhook 回调地址。
Meta Business Cloud API（cloud_api）：通过 HTTPS Webhook（/api/v1/whatsapp/callback/{installationId}）与 Graph API v21.0 接入官方 Meta WhatsApp Business 平台号码。

配置完成后，智能体可以直接回复 WhatsApp 消息，工单状态变更和评论也会自动推送回来源 WhatsApp 会话。

接入方式对比

能力	关联设备（`self_chat` 自聊模式）	关联设备（`bot` 独立号模式）	Meta Business Cloud API（`cloud_api`）
公网回调地址	不需要	不需要	需要（`/api/v1/whatsapp/callback/{installationId}`）
私聊消息	仅处理「发给自己（Message Yourself）」会话（`FromMe && Chat == OwnJID`）	处理外部联系人私聊（`!FromMe`，带防环回保护）	处理外部联系人私聊（`messages[]` Webhook）
群聊消息	忽略（仅限个人自聊）	需 `@` 提及、引用回复机器人或 `/` 命令触发	仅支持 1:1 私聊
入站媒体	图片、文档、语音/音频、视频（Signal E2E 解密）	图片、文档、语音/音频、视频（Signal E2E 解密）	图片、文档、语音/音频、视频（Graph API 下载）
处理中提示	正在输入状态（Composing）	正在输入状态（Composing）	已读回执（`status: read`）+ 输入指示器（`typing_indicator`）
多副本支持	单实例租约（Supervisor Lease）	单实例租约（Supervisor Lease）	无状态 HTTP Webhook + 外发队列

在 管理后台 → 系统配置 中设置：

配置项	值
启用 WhatsApp（`whatsapp_enabled`）	`true`
WhatsApp 密钥（`whatsapp_secret_key`）	Base64 编码的 32 字节 AES 密钥，用于加密存储 WhatsApp Cloud API 凭据及每实例 `device_dek` 信封密钥（后者加密 `whatsapp_device_state.state_value`）。可通过系统配置页面的生成按钮一键生成或轮换。

通过系统配置中的生成按钮轮换 whatsapp_secret_key 时，Mopheus 会在同一事务内重加密所有已有的 WhatsApp 安装凭据和信封 DEK。

打开智能体或团队详情页 → 集成 → 连接 WhatsApp。
选择 关联设备扫码（Linked Device），并选择 消息处理模式：
- 仅自聊模式（self_chat，推荐）：仅处理你在 WhatsApp「发给自己（Message Yourself）」对话框中发送的消息（FromMe == true 且会话 JID 等于自身账号 JID/LID）。发给外部联系人的日常聊天与群聊消息会被自动忽略，配对成功时自动完成本人账号绑定。
- 独立机器人号码（bot）：处理外部用户发来的私聊消息（!FromMe）以及群聊中 @ 提及、引用回复或 / 命令触发机器人号码的消息，并通过外发消息 ID 追踪器自动拦截自身回复以防止死循环。
点击 生成二维码。
在手机上打开 WhatsApp → 设置 → 已关联的设备 → 关联设备，扫描 Mopheus 页面上显示的二维码。等待扫描期间二维码每 20 秒自动刷新。
配对成功后，Mopheus 将设备的 Signal 密钥库加密保存在 PostgreSQL 中，并由渠道 Supervisor 租约自动维持长连接。

在 Meta 开发者后台为企业应用配置 WhatsApp 产品，并获取：
- Phone Number ID（phoneNumberId，纯数字）
- WhatsApp Business Account ID（wabaId，可选）
- 永久系统用户访问令牌（accessToken）
- App Secret（appSecret，用于校验 X-Hub-Signature-256 签名）
在 Mopheus 中打开智能体或团队详情页 → 集成 → 连接 WhatsApp，选择 Business Cloud API 并填写凭据。
Mopheus 会生成 Webhook 回调地址（{APP_URL}/api/v1/whatsapp/callback/{installationId}）和 Verify Token（若未自定义则自动生成）。
将 回调地址 和 Verify Token 复制到 Meta 开发者后台的 WhatsApp → Configuration → Webhook 中完成验证，并订阅 messages 字段。

当外部 WhatsApp 用户首次向已连接的智能体或团队发送消息时，Mopheus 会回复一次性账号绑定链接（/whatsapp/bind?token=...）。登录 Mopheus 并确认绑定后，该 WhatsApp 用户的后续消息将自动路由给对应的智能体或团队。

入站与外发 Markdown 会自动转换为 WhatsApp 原生格式（*粗体*、_斜体_、~删除线~、三反引号代码块），超出 4000 字符时自动安全分片。
入站媒体附件（最大 20 MiB）会自动下载、校验并作为附件挂载到 Mopheus 聊天会话中。