跳到主要内容

WhatsApp 设置

概述​

WhatsApp channel 使用本地或远程 bridge service。Anyy 通过 HTTP 与 bridge 通信，轮询入站消息，并通过同一个 bridge 发送回复。

这不是 WhatsApp Cloud API adapter。请配置你实际运行的 bridge URL。

前提条件​

  • 一个兼容 Anyy bridge API 的 WhatsApp bridge。
  • Bridge URL。
  • 如果 bridge 要求鉴权，准备可选 bridge token。
  • 如果不想开放 pairing，准备允许的 JID 或 group id。

配置​

创建凭据​

先启动 bridge，并按 bridge 的要求完成 WhatsApp 侧 pairing。如果 bridge 使用 auth token，通过 Anyy secret 保存。

配置 Anyy​

默认本地 bridge：

anyy setup channels whatsapp --write-config

自定义 bridge 和 token：

anyy setup channels whatsapp \
  --set bridge_url=http://127.0.0.1:3000 \
  --secret bridge_token='bridge-token' \
  --write-config

setup 默认值：

字段默认值
account_idpersonal
bridge_urlhttp://127.0.0.1:3000
dm_policypairing
group_policymention
poll_interval_ms2000
send_chunk_chars4000
media_max_bytes5242880

启动 Gateway​

anyy gateway start
anyy channels reload

运行 Doctor 检查​

anyy channels doctor whatsapp

访问策略​

私信​

setup 默认 dm_policy: pairing。更严格的部署可以用 allowlist，并在 allow_from 中写已知 sender JID。

群组​

默认 group_policy: mention，group chat 里需要 mention alias。setup helper 会写入 mention_aliases: ["@anyy"]。

只允许特定群时使用 allow_groups。

管理员​

WhatsApp access policy 与 messaging command 授权是两层。

Sessions​

每个被接受的 chat JID 会映射到一个 Anyy session。Adapter 会记录 bridge message id 以避免重复处理。

媒体支持​

入站媒体​

WhatsApp 通过 bridge 声明支持 inbound media。文件大小受 media_max_bytes 限制。

出站媒体​

这个 adapter 没有声明原生 outbound media。

命令​

使用共享 messaging commands。Group 中如 group_policy 是 mention，需要包含配置的 mention alias。

Cron 投递​

anyy cron create \
  --name "WhatsApp reminder" \
  --schedule "30m" \
  --prompt "Remind me to check the oven" \
  --delivery-target current_user_default \
  --delivery-channel whatsapp

故障排查​

  • 没有消息进入：确认 bridge 正在运行，并且 Anyy host 能访问它。
  • 401 或鉴权错误：检查 bridge_token_ref。
  • 群消息被忽略：提到 @anyy 或更新 mention_aliases。
  • 疑似重复消息：检查 bridge retry 行为和 gateway 日志。