跳到主要内容

WhatsApp Business Cloud API 设置

Kopi Agent 可以通过 Meta 官方的 WhatsApp Business Cloud API 连接到 WhatsApp。这是一条生产级路径:无需 Node.js bridge 子进程,无需二维码,没有账号被封禁的风险。

作为交换条件:

  • 你需要一个 Meta Business 账号(不是个人 WhatsApp)。
  • 机器人使用专门的商务电话号码运行,而不是你的个人号码。
  • Kopi Agent 网关需要一个公开的 HTTPS URL,以便 Meta 通过 webhook 投递入站消息。
  • 距离用户最后一条消息超过 24 小时的回复,需要使用预先批准的模板(这是 Meta 的"客服窗口"规则,不是 Kopi Agent 的限制)。

如果这些限制不适合你的用例,Baileys bridge 集成是替代方案——使用个人账号,无需公开 URL,但属于非官方方式,且容易被封禁。

我应该用哪一个?
  • Cloud API(本指南)——运行真正的业务机器人,追求稳定性,能够接受 Meta 验证 + 模板审批的流程
  • Baileys bridge——个人项目、快速演示、单用户场景,愿意冒着机器人电话号码账号被封的风险

快速开始​

kopi whatsapp-cloud

该向导会引导你完成每一项凭据的填写,在你粘贴时逐一验证(能捕获最常见的设置陷阱——把电话号码粘贴到 Phone Number ID 字段中),并对需要在向导之外完成的部分(启动 cloudflared、配置 Meta 的 webhook 控制台)打印出确切的后续操作说明。

本页其余部分是手动参考文档。


前提条件​

  1. 一个 Meta Business 账号。在 business.facebook.com 创建。
  2. 一个启用了 WhatsApp 的 Meta 应用。参见下文"创建 Meta 应用"。
  3. 一种通过 HTTPS 将本地端口暴露到公网的方式。推荐使用 Cloudflare Tunnel (cloudflared)——免费、无需端口转发、无需域名。ngrok、你自己的域名配合反向代理 + TLS,或者直接将网关绑定到公网 IP 的 VPS 也都可行。
  4. 可选但推荐:在 PATH 上安装 ffmpeg,这样出站语音消息会渲染为原生 WhatsApp 语音消息气泡(绿色波形),而不是 MP3 音频附件。如果没有安装,Kopi Agent 会优雅降级。

创建 Meta 应用​

  1. 前往 developers.facebook.com/apps → Create App。
  2. 选择用例:"Connect with customers through WhatsApp" → Next。
  3. 选择或创建一个业务资产组合(business portfolio)。查看发布要求。确认 → Create app。
  4. 创建完成后,你会进入 Customize use case → Connect on WhatsApp → Quickstart。点击 Start using the API → 现在你进入了 API Setup 页面。
  5. 确认已关联 WhatsApp Business Account (WABA)。如果你在第 3 步创建了新的资产组合,系统会自动创建一个。请在 API Setup 页面中验证。

你需要从控制台获取以下值——向导会按此顺序提示你输入:

值在控制台中的位置字段格式备注
Phone Number IDApp Dashboard → WhatsApp → API Setup → "From" 下拉框下方数字,15-17 位不是电话号码本身。最常见的设置错误就是把实际电话号码粘贴到这里。
Access TokenApp Dashboard → WhatsApp → API Setup → "Generate access token"以 EAA 开头,100+ 字符临时 token 有效期为 24 小时——生产环境请参见下文"永久 token"。
App SecretApp Dashboard → Settings → Basic → 点击 App secret 旁的 "Show"32 位小写十六进制用于验证传入的 webhook 签名。缺少它时,入站投递会以 503 拒绝。
App ID(可选)App Dashboard → Settings → Basic数字,15-16 位消息收发不需要,但对数据分析有用。
WABA ID(可选)App Dashboard → WhatsApp → API Setup → 靠近顶部数字,15+ 位消息收发不需要,但对数据分析有用。

永久 token(生产环境)​

临时 access token 在 24 小时后过期,这意味着今天生成的 token 明天就会失效。生产部署请使用 System User 永久 token:

  1. 前往 business.facebook.com/latest/settings → System users(左侧边栏)。
  2. Add → 名称(例如 kopi-bot)→ 角色:Admin。
  3. 选中新用户 → Assign Assets:
    • 选择你的应用 → 在 Full control 下开启 Manage app。
    • 选择你的 WhatsApp 账号 → 在 Full control 下开启 Manage WhatsApp Business Accounts。
    • 点击 Assign assets。
  4. Generate token,勾选以下权限:
    • business_management
    • whatsapp_business_messaging
    • whatsapp_business_management
  5. 设置 token expiration: Never。
  6. 复制该 token → 在 CODE_17 中更新 WHATSAPP_CLOUD_ACCESS_TOKEN → 重启网关。

System User token 除非你明确吊销,否则永不过期。

将 Kopi Agent 暴露到互联网​

Cloud API 通过 HTTPS POST 将入站消息推送到你的 webhook URL——也就是说,Kopi Agent 网关必须能被 Meta 的服务器访问到。常见的三种方式:

Cloudflare Tunnel(推荐)​

免费、无需端口转发,可在 Windows / macOS / Linux 上运行。作为独立进程与网关并行运行。

安装:

# Windows
winget install Cloudflare.cloudflared

# macOS
brew install cloudflared

# Linux
# Download the binary from https://github.com/cloudflare/cloudflared/releases

运行快速隧道(无需 Cloudflare 账号——会给你一个 https://<random>.trycloudflare.com URL):

cloudflared tunnel --url http://localhost:8090

记下打印出来的 URL——这就是你要提供给 Meta 的地址。

快速隧道的 URL 会轮换

免费的快速隧道 URL 每次重启 cloudflared 时都会改变。若要获得稳定的 URL,请使用 cloudflared tunnel login 登录并创建命名隧道。免费的 Cloudflare 账号可创建不限数量的命名隧道——命名隧道的操作流程请参阅 Cloudflare 的文档。

ngrok​

ngrok http 8090

免费版每次重启都会显示不同的 URL。付费版可以提供稳定的子域名。

自有域名 + 反向代理​

如果你已有一台带 TLS 证书的服务器(Caddy、nginx 等),将一条路由指向 localhost:8090 即可。这是生产环境最稳定的方案,但需要你已有相应的基础设施。


在 Meta 侧配置 webhook​

隧道启动后:

  1. 记下隧道打印出的公网 URL——假设是 https://abc123.trycloudflare.com。
  2. 生成一个 Verify Token——向导会用 secrets.token_urlsafe(32) 自动完成;如果你是手动配置,请运行:
    python -c "import secrets; print(secrets.token_urlsafe(32))"
    将其保存为 ~/.kopi/.env 中的 WHATSAPP_CLOUD_VERIFY_TOKEN。
  3. 启动 Kopi Agent 网关:kopi gateway。
  4. 在 Meta App Dashboard → WhatsApp → Configuration(或根据 UI 版本选择 Use cases → Customize → Configuration)中,点击 Webhook 区域的 Edit。
  5. 填写:
    • Callback URL:https://abc123.trycloudflare.com/whatsapp/webhook
    • Verify Token:第 2 步中的字符串(必须完全一致)
  6. 点击 Verify and save。Meta 会向你的 URL 发起 GET 请求,网关原样回显 challenge,Meta 随后将该 webhook 标记为已验证。
  7. 在 Webhook fields 下点击 Manage → 订阅 messages 字段。只有这样,Meta 才会真正把入站消息投递到你的 webhook。

手动验证整条链路(在第三个终端中执行):

TUNNEL="https://abc123.trycloudflare.com"
VERIFY="<your verify token>"

# Should print HTTP 200 with body "hello"
curl -i "$TUNNEL/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=$VERIFY&hub.challenge=hello"

# Health endpoint — should show verify_token_configured: true and app_secret_configured: true
curl "$TUNNEL/health"

接收方白名单(Meta 侧)​

在开发模式下(应用尚未通过 App Review 之前),Meta 会限制你的机器人可以给哪些号码发消息:

  1. App Dashboard → WhatsApp → API Setup → To 下拉框。
  2. 点击 Manage phone number list。
  3. 添加你想要发消息的电话号码(你自己、团队成员或友好的测试人员)。Meta 会通过 SMS 或 WhatsApp 向每个号码发送一个 6 位验证码。

开发模式下最多可添加 5 个号码。通过 App Review 后即可解除该限制。


允许列表(Kopi Agent 侧)​

除了 Meta 的接收方白名单之外,Kopi Agent 还有自己的按平台划分的允许列表,用于控制处理哪些入站消息。将其添加到 ~/.kopi/.env:

# Comma-separated phone numbers, country code, no '+' / spaces / dashes
WHATSAPP_CLOUD_ALLOWED_USERS=15551234567,15557654321

# Or allow everyone (only safe in combination with Meta's recipient whitelist)
# WHATSAPP_CLOUD_ALLOW_ALL_USERS=true

向导会在第 6 步设置此项。如果没有允许列表,所有入站消息都会被拒绝——这是有意为之:即使接收方白名单日后被放宽,机器人也不会被随机号码唤起。


完善机器人的 WhatsApp 资料​

WhatsApp 会在聊天标题和联系人列表中显示机器人的名称和头像。这些无法通过 Cloud API 设置——它们保存在 Meta 的 Business Manager 中。

机器人运行正常后,前往 business.facebook.com/wa/manage/phone-numbers,点击你的电话号码,即可找到:

项目位置说明
显示名称电话号码页面顶部修改需经过 Meta 的名称审核流程(约 24–48 小时)。
头像电话号码页面顶部方形图片,建议 ≥640×640px。即时生效。
关于 / 简介 / 网站 / 邮箱 / 营业时间 / 类别“Edit profile”按钮当用户点击机器人名称时,这些信息会显示在信息面板中。属于装饰性内容。
认证徽章(绿色对勾)Business Manager → Security Center → Start Verification需要经过 Meta 单独的企业认证流程。

kopi whatsapp-cloud 向导会在设置完成时打印出这些链接。以上内容都不是机器人运行所必需的——纯粹是为了让机器人在用户面前的呈现效果更完善。


配置参考​

所有设置都保存在 ~/.kopi/.env 中。必填值以粗体显示。

变量默认值说明
WHATSAPP_CLOUD_PHONE_NUMBER_ID—来自 API Setup 的 15-17 位 ID。不是电话号码。
WHATSAPP_CLOUD_ACCESS_TOKEN—Meta access token(以 EAA 开头)。可使用 24 小时的临时 token,或 System User 的永久 token。
WHATSAPP_CLOUD_APP_SECRET—来自 Settings → Basic 的 32 位十六进制字符串。缺少它时,入站请求会返回 503 并被拒绝。
WHATSAPP_CLOUD_VERIFY_TOKEN—用于 GET 握手的共享密钥。由向导自动生成。
WHATSAPP_CLOUD_ALLOWED_USERS—以逗号分隔的、允许给机器人发消息的 wa_id 列表。
WHATSAPP_CLOUD_ALLOW_ALL_USERSfalse设置为 true 可绕过允许列表。
WHATSAPP_CLOUD_APP_ID—可选项,用于未来的数据分析集成。
WHATSAPP_CLOUD_WABA_ID—可选项,用于未来的数据分析集成。
WHATSAPP_CLOUD_WEBHOOK_HOST0.0.0.0webhook 服务器绑定的网络接口。
WHATSAPP_CLOUD_WEBHOOK_PORT8090webhook 服务器绑定的端口。必须与隧道转发的端口一致。
WHATSAPP_CLOUD_WEBHOOK_PATH/whatsapp/webhookMeta 发送 POST 请求的 URL 路径。
WHATSAPP_CLOUD_API_VERSIONv20.0Meta Graph API 版本。仅当 Meta 文档推荐了更新版本时才需要覆盖。
WHATSAPP_CLOUD_HOME_CHANNEL—用作机器人主频道的 wa_id(用于 cron 任务等)。

你可以同时启用 Baileys(whatsapp)和 Cloud(whatsapp_cloud)适配器,分别对应不同的电话号码。


功能​

入站​

  • 文本消息 —— 直接传递给 agent。
  • 图片 —— 自动下载并附加到 agent 的输入中。具备原生视觉能力的模型(Claude、GPT-4o、Gemini 等)会直接读取图片;非视觉模型则会收到自动生成的文本描述。
  • 语音消息 —— 自动下载为 .ogg,通过你配置的 STT provider(本地 faster-whisper、OpenAI/Nous、Groq 等)转录,然后以文本形式交给 agent。
  • 文档 —— 自动下载。可读取文本的小型文件(.txt、.md、.json、.py、.csv 等),最大 100KB,会被内联到 agent 的输入中,使其无需工具调用即可阅读。较大的文件会被缓存到本地,供 agent 的其他工具访问。
  • 按钮点击 —— 当用户点击机器人此前发送的按钮(澄清选项、命令审批、斜杠命令确认)时,该点击会被直接路由到对应的处理程序。过期的点击会回退为按普通文本输入处理。
  • 回复上下文 —— 当用户回复之前的机器人消息时,agent 会看到原始消息作为上下文。

出站​

  • 文本 —— markdown 会自动转换为 WhatsApp 风格的语法(**bold** → *bold*、~~strike~~ → ~strike~、标题 → 加粗、[link](url) → link (url))。长消息会按每段 4096 个字符进行拆分。
  • 图片 —— 同时支持 agent 生成的图片和本地图片文件,均以原生照片附件的形式发送。
  • 语音消息 —— 文本转语音的输出会通过 ffmpeg 转换为原生的 WhatsApp 语音消息气泡(绿色波形)。未安装 ffmpeg 时,会回退为 MP3 音频附件。详见下文的“语音消息”。
  • 视频 / 文档 —— 两者均支持,以原生附件形式发送。

交互式 UX​

当 agent 调用以下任意流程时,Kopi Agent 会使用 WhatsApp 的原生交互式消息 —— 用点击选择的按钮代替“请回复数字”的提示:

  • clarify 工具 —— 多选问题会渲染为快捷回复按钮(1–3 个选项)或点击展开的列表面板(4 个及以上选项)。选择“✏️ Other”后,用户可以输入自由格式的回答,agent 会将其作为最终选择接收。
  • 危险命令审批 —— 当 agent 的终端/代码执行触发受管控命令时,用户会看到 ✅ Approve / ❌ Deny 按钮,而无需输入 /approve 或 /deny。
  • 斜杠命令确认 —— 像 /reload-mcp 这样的特权命令会显示 ✅ Approve Once / 🔒 Always / ❌ Cancel 按钮。

如果按钮渲染失败(例如在旧版 WhatsApp 客户端上),所有交互式提示都会优雅地降级为纯文本。

已读回执和输入状态指示​

Kopi Agent 会立即确认收到的入站消息:

  • 网关一收到你的消息,你的消息就会显示蓝色双勾。
  • 在 agent 准备回复期间,你在 WhatsApp 聊天中看到的机器人名称会显示 “typing…”(正在输入…)。
  • 当机器人的第一条回复消息送达时,输入状态指示会自动消失。

这样就能清楚地区分机器人何时已看到你的消息、何时仍在处理回复。

语音消息​

WhatsApp 会区分“语音消息”(绿色波形气泡)和普通的音频文件附件。两者的差别纯粹在于编解码器:语音消息必须是采用 opus 编码的 audio/ogg。

Kopi Agent 的 TTS 输出为 MP3。有两种处理路径:

  • PATH 中有 ffmpeg(推荐) —— 出站 TTS 会被转换后以正规语音消息送达。安装方式:
    • Windows:winget install Gyan.FFmpeg
    • macOS:brew install ffmpeg
    • Linux:使用包管理器
  • 没有 ffmpeg —— 出站 TTS 会以 MP3 音频附件的形式送达。播放效果正常,只是看起来不像语音消息。网关日志中会触发一次一次性警告,让你知晓这一情况。

你可以通过健康检查端点查看网关是否找到了 ffmpeg:

curl http://localhost:8090/health
# look for "ffmpeg_present": true

已知限制​

24 小时会话窗口​

Meta 仅允许在用户最后一条入站消息之后的 24 小时窗口内发送自由格式消息。超出该窗口后,Meta 的 API 只接受预先审批的消息模板。

在实践中这意味着:

  • 响应式对话(用户私信 → 机器人在 24 小时内回复 → 用户再回复 → ……)可以无限期进行。这涵盖了超过 95% 的正常机器人使用场景。
  • 间隔超过 24 小时后向 WhatsApp 投递的**定时任务(cron jobs)**会失败,并返回 Graph 错误码 131047("Re-engagement message")。
  • 耗时超过 24 小时的长时间运行的 delegate_task 异步结果会以同样方式失败。
  • 将外部事件路由到 WhatsApp 的 Webhook 订阅者会在用户近期没有私信机器人时失败。

Kopi Agent 会在其系统提示中向 agent 说明这一窗口,因此模型在安排延迟消息时会知道要提及这一点。

消息模板支持(用于窗口外发送的变通方案)尚未在 Kopi Agent 中实现。如果你需要该功能,请提交 issue —— 该功能已列入计划,但还在等待明确的需求信号。

群聊​

Cloud API 对群聊的支持有限(由 Meta 按能力层级进行管控)。Kopi Agent 的 whatsapp_cloud 适配器在 v1 中目前仅处理私聊消息。如果你需要群聊,请使用 Baileys 桥接。

出站速率限制​

Meta 的默认吞吐量为每个企业电话号码每秒 80 条消息,并可申请提升。Kopi Agent 目前不在客户端强制执行该限制 —— 极高发送量的情况可能会触及 Meta 的限制。

故障排查​

设置验证失败(Meta 控制台显示 "URL couldn't be validated")​

几乎都是以下原因之一:

  • Tunnel URL 错误或已过期 — cloudflared 快速隧道会轮换 URL。获取一个新的 URL,并同时更新 .env 和 Meta 控制台。
  • Verify token 不匹配 — ~/.kopi/.env 的 WHATSAPP_CLOUD_VERIFY_TOKEN 中的 token 必须与你输入 Meta 控制台的内容完全一致。先运行上面的 curl 探测命令,确认网关的 verify 握手在本地正常工作。
  • 网关未运行 — 检查 kopi gateway 是否已启动。
  • App Secret 未设置 — 没有它,Kopi Agent 会以 503 拒绝入站 POST 请求。Meta 会将其解读为"无法验证"。

graph error 100:Object with ID '...' does not exist​

你把电话号码(10-11 位数字)粘贴到了 WHATSAPP_CLOUD_PHONE_NUMBER_ID,而不是 Phone Number ID(Meta 的 15-17 位内部 ID)。请重新检查 API Setup 页面 — Phone Number ID 显示在 "From" 下拉框下方。

向导现在会通过验证器捕获这个问题,但如果你是手动配置,仍值得了解这一点。

graph error 190:Authentication Error​

你的 access token 无效。子错误码:

  • subcode 463 — token 已过期。临时 token 有效期为 24 小时。重新生成,或改用 System User 永久 token(见上文)。
  • subcode 467 — token 已失效(被撤销或密码已更改)。
  • 其他 190 — 生成 token 时没有所需权限。确保三个权限(business_management、whatsapp_business_messaging、whatsapp_business_management)都已勾选。

graph error 131047:Re-engagement message​

24 小时会话窗口已过期(参见"已知限制")。可以:

  • 请用户先给机器人发私信,以重新打开窗口。
  • 等待 Kopi Agent 支持消息模板。

入站消息:media metadata fetch failed (status=401)​

与出站(graph error 190)相同的 401 根源 — access token 无效或已过期。修复 token 即可。

机器人回复显示为原始 JSON / 工具调用泄露​

常见原因:为 whatsapp_cloud 配置的 toolset 缺少 agent 想要调用的工具。检查 kopi tools list,确认平台使用的是 kopi-whatsapp(默认的 Cloud adapter toolset,与 Baileys 相同)。

如果模型输出的是工具调用形式的文本而非结构化调用,通常意味着 toolset 实际上是空的。参见 kopi_cli/platforms.py 了解平台 → 默认 toolset 的映射关系。

STT(语音消息转写)返回空结果 / "could not transcribe"​

默认的 stt.provider: local 需要 pip install faster-whisper。如果你是 Nous 订阅用户,可以改为通过 Meta 的托管音频网关路由 STT:

kopi config set stt.provider openai
kopi config set stt.use_gateway true
kopi gateway restart

这会使用你的 KOPI Proxy access token,而无需单独的 OpenAI key。


安全注意事项​

  • 像对待密码一样对待 App Secret — 任何拥有它的人都可以伪造 webhook 载荷,而 Kopi Agent 会将其视为真实请求。
  • verify token 是共享密钥 — 泄露的后果相对较轻(最坏情况是有人把 Meta 的 webhook 重新订阅到他们自己的 URL),但仍应避免将其提交到代码仓库。
  • access token 是你机器人的身份凭证 — System User token 等同于长期 API key。如果部署环境被入侵,请立即轮换。
  • 当 WHATSAPP_CLOUD_APP_SECRET 已设置时,webhook 端点只接受签名请求 — 即使在开发环境中也请保持设置。没有它,网关会以 HTTP 503 拒绝入站投递。
  • /health 端点无需认证 — 暴露它是安全的,因为它只报告配置是否存在(布尔值),不包含具体值。但如果你不想暴露它,可以在反向代理 / tunnel 层限制访问。

与 Baileys bridge 的对比​

Baileys (kopi whatsapp)Cloud API (kopi whatsapp-cloud)
账号类型个人账号企业账号
设置方式扫描二维码Meta 应用 + WABA + token
依赖项Node.js + npm纯 Python(httpx + aiohttp)
进程托管的 Node 子进程aiohttp webhook 服务器
是否需要公网 URL否是
账号被封风险有(非官方 API)无(官方支持)
入站轮询 Node 桥接来自 Meta 的 Webhook POST
出站本地桥接 → BaileysHTTPS 到 graph.facebook.com
群组完整支持仅私信(v1)
24 小时窗口无限制硬性规则 — 超时后必须使用模板
语音消息(发出)原生原生支持(需 ffmpeg),否则回退为 MP3
已读回执否是(蓝色双勾)
正在输入指示否是(响应后自动消失)
交互式按钮仅文本回退原生支持(clarify、approval、slash-confirm)
生产环境使用有风险(Meta 可能封号)专为此设计

大多数为个人项目运行 Kopi Agent 的用户偏好 Baileys。大多数运行面向客户的机器人的用户偏好 Cloud API。


另请参阅​