把 Moltbot 接到 WhatsApp 上

WhatsApp 的接入流程比 Telegram 复杂不少。Telegram 几分钟即可完成的配置，WhatsApp 可能需要一到两个小时。

不过，如果你的主要联系人都在 WhatsApp 上，这个时间投入是值得的。

为什么 WhatsApp 配置更复杂

Telegram 创建 Bot 只需与 BotFather 对话。WhatsApp 则需要通过 WhatsApp Business API，由 Meta 统一管理，流程更为正式。

你需要准备：

1. 一个 Meta 开发者账号
2. 一个 Meta Business 应用
3. 一个能接收短信的手机号（用于注册 WhatsApp Business）
4. 配置 Webhook 接收消息推送

步骤虽多，逐一完成并不困难。

注册 Meta 开发者账号

前往 developers.facebook.com 注册开发者账号。如果已有 Facebook 账号，登录后即可开通开发者身份。

注册过程中可能需要身份验证，按提示操作即可。

创建 Business 应用

1. 登录 Meta 开发者后台
2. 点击「创建应用」
3. 选择「Business」类型
4. 填写应用名称
5. 创建完成后，在应用面板中找到「WhatsApp」，点击「设置」

此时会获得一个测试用手机号和一个临时的 Access Token。

临时 Token 有效期为 24 小时。正式使用需要生成永久 Token，在「系统用户」中操作。这部分可参考 Meta 官方文档。

获取关键信息

需要记录以下三项：

• Phone Number ID — 在 WhatsApp 设置页面查看
• Access Token — 上一步获取的
• Webhook Verify Token — 自定义的字符串，用于后续 Webhook 配置

配置 Moltbot

moltbot configure --section whatsapp

按提示填入上述三项信息。

也可以使用环境变量：

export WHATSAPP_PHONE_NUMBER_ID=1234567890
export WHATSAPP_ACCESS_TOKEN=EAAxxxxxxxxxxxxx
export WHATSAPP_VERIFY_TOKEN=my_secret_verify_string

或者直接编辑配置文件：

# ~/.moltbot/config.yaml
channels:
  whatsapp:
    phoneNumberId: "1234567890"
    accessToken: "EAAxxxxxxxxxxxxx"
    verifyToken: "my_secret_verify_string"

配置 Webhook

WhatsApp 不支持长轮询，必须使用 Webhook，因此需要一个公网可访问的 HTTPS 地址。

如果没有服务器，可以使用 Cloudflare Tunnel：

# 安装 cloudflared
brew install cloudflare/cloudflare/cloudflared

# 创建隧道（会生成一个公网 URL）
cloudflared tunnel --url http://localhost:3000

获取公网 URL 后，在 Meta 开发者后台的 WhatsApp 设置中填入 Webhook URL：

https://your-tunnel-url.trycloudflare.com/whatsapp/webhook

Verify Token 填写你之前自定义的字符串。

点击验证。如果 Moltbot 正在运行，验证应当通过。

启动和配对

moltbot start

用你的 WhatsApp 向该 Business 号码发送一条消息。终端会显示配对码，流程与 Telegram 一致：

moltbot pairing approve whatsapp YOUR_CODE

配对完成。

需要注意的限制

24 小时消息窗口。 WhatsApp Business API 规定：用户发送消息后，Bot 有 24 小时的回复窗口。超过 24 小时后，不能主动向用户发送消息（除非使用模板消息，那是另一套流程）。

对于即时对话场景影响不大，但如果需要 Moltbot 主动推送消息（如早间简报），需要额外配置模板消息。

测试号码限制。 Meta 提供的测试号码只能向最多 5 个预设号码发送消息。面向更多用户使用需要通过 Meta 的 Business 验证。

消息格式。 WhatsApp 支持的格式比 Telegram 少。部分 Markdown 语法无法渲染，代码块的显示效果也较为简陋。可以使用，但体验不如 Telegram。

Access Token 过期。 如果使用的是临时 Token，过期后 Bot 将无法正常工作。建议尽早在后台生成永久 Token。

渠道选择建议

如果没有必须使用 WhatsApp 的需求，推荐优先接入 Telegram。配置简单、功能完整、无需 Business 验证。

如果确实需要 WhatsApp，按照上述步骤完成一次配置后，后续无需再次操作。

常见问题

Webhook 验证失败？

检查以下三点：

• Moltbot 是否正在运行
• Webhook URL 是否可从公网访问
• Verify Token 是否填写正确

收到消息但 Bot 不回复？

查看终端日志。大多数情况是 Access Token 过期或权限不足。

收到回复但格式混乱？

WhatsApp 的消息格式支持有限，Moltbot 会尽量适配，但部分复杂格式（如表格）可能显示不佳。目前暂无更好的解决方案。