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 控制台)打印出确切的后续操作说明。
本页其余部分是手动参考文档。
前提条件
- 一个 Meta Business 账号。在 business.facebook.com 创建。
- 一个启用了 WhatsApp 的 Meta 应用。参见下文"创建 Meta 应用"。
- 一种通过 HTTPS 将本地端口暴露到公网的方式。推荐使用 Cloudflare Tunnel (
cloudflared)——免费、无需端口转发、无需域名。ngrok、你自己的域名配合反向代理 + TLS,或者直接将网关绑定到公网 IP 的 VPS 也都可行。 - 可选但推荐:在
PATH上安装 ffmpeg,这样出站语音消息会渲染为原生 WhatsApp 语音消息气泡(绿色波形),而不是 MP3 音频附件。如果没有安装,Kopi Agent 会优雅降级。
创建 Meta 应用
- 前往 developers.facebook.com/apps → Create App。
- 选择用例:"Connect with customers through WhatsApp" → Next。
- 选择或创建一个业务资产组合(business portfolio)。查看发布要求。确认 → Create app。
- 创建完成后,你会进入 Customize use case → Connect on WhatsApp → Quickstart。点击 Start using the API → 现在你进入了 API Setup 页面。
- 确认已关联 WhatsApp Business Account (WABA)。如果你在第 3 步创建了新的资产组合,系统会自动创建一个。请在 API Setup 页面中验证。
你需要从控制台获取以下值——向导会按此顺序提示你输入:
| 值 | 在控制台中的位置 | 字段格式 | 备注 |
|---|---|---|---|
| Phone Number ID | App Dashboard → WhatsApp → API Setup → "From" 下拉框下方 | 数字,15-17 位 | 不是电话号码本身。最常见的设置错误就是把实际电话号码粘贴到这里。 |
| Access Token | App Dashboard → WhatsApp → API Setup → "Generate access token" | 以 EAA 开头,100+ 字符 | 临时 token 有效期为 24 小时——生产环境请参见下文"永久 token"。 |
| App Secret | App 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:
- 前往 business.facebook.com/latest/settings → System users(左侧边栏)。
- Add → 名称(例如
kopi-bot)→ 角色:Admin。 - 选中新用户 → Assign Assets:
- 选择你的应用 → 在 Full control 下开启 Manage app。
- 选择你的 WhatsApp 账号 → 在 Full control 下开启 Manage WhatsApp Business Accounts。
- 点击 Assign assets。
- Generate token,勾选以下权限:
business_managementwhatsapp_business_messagingwhatsapp_business_management
- 设置 token expiration: Never。
- 复制该 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 每次重启 cloudflared 时都会改变。若要获得稳定的 URL,请使用 cloudflared tunnel login 登录并创建命名隧道。免费的 Cloudflare 账号可创建不限数量的命名隧道——命名隧道的操作流程请参阅 Cloudflare 的文档。
ngrok
ngrok http 8090
免费版每次重启都会显示不同的 URL。付费版可以提供稳定的子域名。
自有域名 + 反向代理
如果你已有一台带 TLS 证书的服务器(Caddy、nginx 等),将一条路由指向 localhost:8090 即可。这是生产环境最稳定的方案,但需要你已有相应的基础设施。
在 Meta 侧配置 webhook
隧道启动后:
- 记下隧道打印出的公网 URL——假设是
https://abc123.trycloudflare.com。 - 生成一个 Verify Token——向导会用
secrets.token_urlsafe(32)自动完成;如果你是手动配置,请运行:将其保存为python -c "import secrets; print(secrets.token_urlsafe(32))"~/.kopi/.env中的WHATSAPP_CLOUD_VERIFY_TOKEN。 - 启动 Kopi Agent 网关:
kopi gateway。 - 在 Meta App Dashboard → WhatsApp → Configuration(或根据 UI 版本选择 Use cases → Customize → Configuration)中,点击 Webhook 区域的 Edit。
- 填写:
- Callback URL:
https://abc123.trycloudflare.com/whatsapp/webhook - Verify Token:第 2 步中的字符串(必须完全一致)
- Callback URL:
- 点击 Verify and save。Meta 会向你的 URL 发起 GET 请求,网关原样回显 challenge,Meta 随后将该 webhook 标记为已验证。
- 在 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 会限制你的机器人可以给哪些号码发消息:
- App Dashboard → WhatsApp → API Setup → To 下拉框。
- 点击 Manage phone number list。
- 添加你想要发消息的电话号码(你自己、团队成员或友好的测试人员)。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_USERS | false | 设置为 true 可绕过允许列表。 |
WHATSAPP_CLOUD_APP_ID | — | 可选项,用于未来的数据分析集成。 |
WHATSAPP_CLOUD_WABA_ID | — | 可选项,用于未来的数据分析集成。 |
WHATSAPP_CLOUD_WEBHOOK_HOST | 0.0.0.0 | webhook 服务器绑定的网络接口。 |
WHATSAPP_CLOUD_WEBHOOK_PORT | 8090 | webhook 服务器绑定的端口。必须与隧道转发的端口一致。 |
WHATSAPP_CLOUD_WEBHOOK_PATH | /whatsapp/webhook | Meta 发送 POST 请求的 URL 路径。 |
WHATSAPP_CLOUD_API_VERSION | v20.0 | Meta 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:使用包管理器
- Windows:
- 没有 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 |
| 出站 | 本地桥接 → Baileys | HTTPS 到 graph.facebook.com |
| 群组 | 完整支持 | 仅私信(v1) |
| 24 小时窗口 | 无限制 | 硬性规则 — 超时后必须使用模板 |
| 语音消息(发出) | 原生 | 原生支持(需 ffmpeg),否则回退为 MP3 |
| 已读回执 | 否 | 是(蓝色双勾) |
| 正在输入指示 | 否 | 是(响应后自动消失) |
| 交互式按钮 | 仅文本回退 | 原生支持(clarify、approval、slash-confirm) |
| 生产环境使用 | 有风险(Meta 可能封号) | 专为此设计 |
大多数为个人项目运行 Kopi Agent 的用户偏好 Baileys。大多数运行面向客户的机器人的用户偏好 Cloud API。
另请参阅
- Meta 官方 WhatsApp Business Cloud API 文档 — 底层平台、定价、App 审核和 Meta 侧速率限制的权威参考。
- WhatsApp(Baileys bridge)设置 — 面向个人项目的替代集成方案。
- 消息平台概览 — 一览所有消息集成。