完整设置指南 - WhatsApp Business Cloud API从零开始直到在生产环境发送第一条消息。预计时间1-2 小时无商家验证| 3-7 天含验证前置条件有效的电子邮箱最好是企业邮箱个人身份证件一个未注册个人 WhatsApp 的电话号码CNPJ 或公司文件用于商家验证最新浏览器推荐 Chrome第 1 步 - 在 Meta Business Suite 创建账号URLhttps://business.facebook.com/overview操作步骤访问https://business.facebook.com/overview点击**“创建账号”**如果你已有个人 Facebook先登录。否则系统会要求你创建一个填写字段公司名称使用你业务的公司全名/商号你的姓名账号管理员姓名商务邮箱最好是企业邮箱例如contatosuaempresa.com.br点击**“提交”**访问你的邮箱点击 Meta 发送的确认链接确认后你会被重定向到 Meta Business Suite 面板常见错误错误解决方案“此邮箱已关联到其他账号”使用其他邮箱或在business.facebook.com/settings恢复现有账号的访问权限“无法创建账号”停用广告拦截扩展uBlock、AdBlock后重试未收到确认邮件检查垃圾邮件文件夹。5 分钟后尝试重新发送。如果仍失败换一个邮箱创建后立即被封号近期 Facebook 个人资料上的新账号可能被标记。等待 24 小时再试完成标志你应该拥有访问business.facebook.com面板的权限在Business Settings Business Info中可见的业务 ID类似123456789012345的数字已确认的邮箱第 2 步 - 在 Meta for Developers 创建应用URLhttps://developers.facebook.com/apps操作步骤访问https://developers.facebook.com/apps如果是首次使用点击**“开始”**并接受开发者条款点击**“创建应用”**按钮选择应用类型“企业”Business不要选择无、“消费者或游戏”填写应用名称例如MeuApp WhatsApp API联系邮箱你的企业邮箱企业账号选择第 1 步创建的账号点击**“创建应用”**系统可能会要求你再次输入 Facebook 密码常见错误错误解决方案“你已达到应用数量上限”新账号有数量限制。在developers.facebook.com/apps删除旧的测试应用企业类型不出现确保第 1 步中的 Business 账号创建正确“未找到企业账号”回到第 1 步确认 Business 账号处于活动状态。尝试在 Business Settings Accounts Apps 中手动绑定创建时权限错误确认你是 Business 账号的管理员完成标志你应该拥有应用已创建并在developers.facebook.com/apps可见一个应用 ID类似1234567890123456的数字应用状态为**“开发中”**第 3 步 - 添加 WhatsApp 产品URLhttps://developers.facebook.com/apps/{SEU_APP_ID}/dashboard/操作步骤在应用面板中滚动到**“向应用添加产品”**部分找到**“WhatsApp卡片点击配置”**接受WhatsApp Business 服务条款选择绑定的企业账号与第 1 步相同点击**“继续”**你会被重定向到应用内的 WhatsApp 面板常见错误错误解决方案WhatsApp 卡片不出现确认应用类型为企业。如果不是用正确的类型创建新应用“你没有权限”确认你是绑定 Business 账号的管理员服务条款无法加载清除浏览器缓存或尝试无痕模式“无法创建 WhatsApp Business Account”你的 Business 账号可能有限制。检查business.facebook.com中的通知完成标志你应该拥有侧边菜单中有**“WhatsApp 配置”**或Getting Started选项自动创建的WhatsApp Business AccountWABA可访问 WhatsApp 的 Getting Started 页面第 4 步 - 获取 Phone Number ID 和 WABA IDURLhttps://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/操作步骤在应用的侧边菜单中点击**“WhatsApp” “API 配置”**或API Setup在**“电话号码信息”**部分你会找到Phone Number ID号码的唯一标识符例如109876543210987WhatsApp Business Account IDWABA IDWhatsApp Business 账号的标识符例如102345678901234记下这两个值。所有 API 调用都需要它们每个 ID 在哪里找App Dashboard └── WhatsApp └── API 配置API Setup ├── Phone Number ID .... 字段 Phone number ID 或 ID do numero └── WABA ID ........... 字段 WhatsApp Business Account IDWABA ID 的替代查找方式https://business.facebook.com/settings/whatsapp-business-accounts/点击账号后 ID 会出现在 URL 中或详情列中。常见错误错误解决方案Phone Number ID 不出现确认已完成第 3 步。尝试刷新页面WABA ID 不可见通过 Business Settings Accounts WhatsApp Business Accounts 访问不同页面上的值不同始终使用应用 API Setup 页面上显示的 ID“没有电话号码”测试号码尚未配置。等待几分钟后刷新完成标志你应该已记下Phone Number ID___________________________WABA ID___________________________应用 ID___________________________来自第 2 步第 5 步 - 生成临时测试令牌URLhttps://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/操作步骤在**“API 配置”API Setup页面找到临时访问令牌**部分点击**“生成访问令牌”**或令牌字段旁边的按钮系统可能要求额外的登录或确认令牌会显示出来 -立即复制关于临时令牌重要 - 24 小时后过期有时 1 小时 - 仅用于初始测试 - 不要在生产环境使用 - 永久令牌见第 9 步通过 cURL 测试令牌curl-XGET\https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}\-HAuthorization: Bearer {SEU_TOKEN_TEMPORARIO}预期响应摘要{id:109876543210987,display_phone_number:1 555-XXX-XXXX,verified_name:Seu Nome de Teste}常见错误错误解决方案点击后令牌不出现停用弹窗拦截器。尝试其他浏览器“Error validating access token”令牌已过期。重新生成“Invalid OAuth access token”重新复制令牌开头/结尾不要有多余空格生成按钮不可用确认 WhatsApp 产品已正确添加第 3 步完成标志你应该拥有一个已复制并保存在安全位置的临时访问令牌通过 cURL 确认令牌可用第 6 步 - 使用测试号码沙盒测试URLhttps://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/操作步骤Meta 提供一个测试号码让你无需真实号码即可发送消息。在 API Setup 页面找到**“发送和接收消息”**部分**“从”**字段应已显示 Meta 的测试号码在**“到部分点击管理电话号码列表”**或Manage phone number list点击**“添加电话号码”**输入带国家代码的收件人号码例如5511999998888你会在该号码上收到一个WhatsApp 验证码输入验证码确认现在点击**“发送消息”**发送测试消息通过 cURL 发送curl-XPOST\https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages\-HAuthorization: Bearer {SEU_TOKEN}\-HContent-Type: application/json\-d{ messaging_product: whatsapp, to: 5511999998888, type: template, template: { name: hello_world, language: { code: en_US } } }预期响应{messaging_product:whatsapp,contacts:[{input:5511999998888,wa_id:5511999998888}],messages:[{id:wamid.XXXXXXXXXXXXXXXX}]}沙盒限制最多可注册5 个收件人号码仅限预先批准的模板如hello_world发送方号码是 Meta 的测试号码不可自定义消息可能需要最多 1 分钟才能送达常见错误错误解决方案131030- “User’s phone number is part of an experiment”收件人号码可能有限制。尝试其他号码131026- “Message failed to send”确认收件人号码有活跃的 WhatsApp100- “Invalid parameter”检查号码格式只有数字、带国家代码、JSON 中不带130429- “Rate limit hit”等待 1 分钟重试。沙盒限制严格验证码收不到目标号码必须安装并活跃使用 WhatsApp找不到hello_world模板确认语言为en_US。此模板是预装的完成标志你应该拥有在收件人的 WhatsApp 中收到测试消息API 返回的message_idwamid确认 API 正常工作第 7 步 - 添加真实电话号码URLhttps://business.facebook.com/settings/whatsapp-business-accounts/{WABA_ID}/phone-numbers或通过应用面板https://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/关键前置条件你要添加的电话号码 - 不能注册在个人 WhatsApp 上 - 不能注册在 WhatsApp Business App 上 - 必须能够接收短信或语音电话 - 可以是固定电话通过电话验证或手机短信或电话 如果号码在个人 WhatsApp 上 1. 在手机上打开 WhatsApp 2. 进入 设置 账号 删除账号 3. 确认删除 4. 等待 5 分钟后再继续操作步骤在 API Setup 页面点击**“添加电话号码”**或通过 Business Settings 的 URL填写商家资料信息显示名称将出现在 WhatsApp 中的名称例如Minha Empresa类别选择你的业务类别描述可选公司简介点击**“下一步”**输入带国家代码的号码55 11 99999-8888选择验证方式第 8 步显示名称规则必须清晰代表你的公司不能只包含通用字符“Teste”、“Admin”不能侵犯注册商标长度必须在 3 到 512 个字符之间Meta 可能拒绝并要求修改常见错误错误解决方案“此号码已注册”号码仍在个人 WhatsApp 上。按上述说明删除账号并等待“号码无效”使用带国家代码的完整国际格式“显示名称被拒绝”使用公司官方名称。避免过度缩写“已达到号码数量上限”未验证的账号只能有 2 个号码。完成第 10 步不接受固定电话接受固定电话。选择语音电话作为验证方式完成标志你应该拥有号码已添加到 WABA 的电话列表下一步通过 OTP 验证第 8 步第 8 步 - 通过 OTP 验证号码操作步骤直接从第 7 步继续选择验证方式短信SMS推荐用于手机号码语音电话固定电话必需点击**“发送验证码”**等待接收 6 位验证码在验证字段中输入验证码点击**“验证”**通过 API 验证替代方案请求验证码curl-XPOST\https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/request_code\-HAuthorization: Bearer {SEU_TOKEN}\-HContent-Type: application/json\-d{ code_method: SMS, language: pt_BR }确认验证码curl-XPOST\https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/verify_code\-HAuthorization: Bearer {SEU_TOKEN}\-HContent-Type: application/json\-d{ code: 123456 }常见错误错误解决方案短信收不到验证码尝试语音电话。确认号码没有屏蔽服务消息“验证码无效”确认输入正确。验证码 10 分钟内过期“尝试次数过多”等待 1 小时再试。每个时段有次数限制语音电话收不到确认号码能接听国际来电“电话号码验证失败”确认该号码没有注册在另一个 WhatsApp Business Account完成标志你应该拥有面板中号码状态为**“已验证”**或Connected真实号码的新Phone Number ID不同于测试号码使用自己的号码发送消息的能力第 9 步 - 创建 System User 和永久令牌URLhttps://business.facebook.com/settings/system-users为什么需要 System User第 5 步的临时令牌很快过期。生产环境需要一个绑定到System User系统用户的永久令牌它不依赖个人登录。操作步骤9.1 - 创建 System User访问https://business.facebook.com/settings在侧边菜单中点击**“用户” “系统用户”**System Users点击**“添加”**填写名称例如whatsapp-api-bot角色选择**“管理员”**完整权限必需点击**“创建系统用户”**9.2 - 为 System User 分配资产点击创建的 System User点击**“分配资产”**Assign Assets在侧边菜单选择**“应用”**找到你的应用第 2 步创建并选中启用**“完全控制”**Full Control点击**“保存更改”**对**“WhatsApp 账号”**重复操作选择你的 WABA启用**“完全控制”**保存9.3 - 生成永久令牌在 System User 页面点击**“生成新令牌”**选择应用第 2 步创建在**“可用权限”**中勾选whatsapp_business_messaging- 用于发送和接收消息whatsapp_business_management- 用于管理账号、模板和配置点击**“生成令牌”**立即复制令牌- 它只显示一次存储在安全位置密码管理器、环境变量、vault令牌安全注意 - 令牌绝不能提交到 Git 仓库 - 使用环境变量.env或密钥服务 - 定期轮换令牌 - 如果令牌泄露立即在 Business Settings 中撤销测试永久令牌curl-XGET\https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}\-HAuthorization: Bearer {TOKEN_PERMANENTE}常见错误错误解决方案菜单中没有系统用户你必须是 Business 账号的管理员。检查你的权限列表中不出现whatsapp_*权限WhatsApp 产品未添加到应用回到第 3 步使用令牌时权限不足确认资产应用 WABA已正确分配给 System User生成后令牌不工作等待 1-2 分钟传播。重试“用户没有权限”确认 System User 角色为管理员且在资产上有完全控制完成标志你应该拥有已创建带描述性名称的 System User已分配完全控制的资产应用 WABA已复制并安全存储的永久令牌通过 API 调用验证的令牌第 10 步 - 商家验证URLhttps://business.facebook.com/settings/security为什么要验证没有商家验证24 小时时段内商家发起的对话限额为250无法申请提高限额某些功能受限验证后限额可逐步提高至无限可访问高级功能在 Meta 面前更可信操作步骤访问https://business.facebook.com/settings在侧边菜单中点击**“安全中心”**Security Center找到**“商家验证部分点击开始验证”**填写公司信息公司法定名称与 CNPJ 一致地址公司官方地址公司电话商务号码网站公司网站 URLCNPJ国家登记号码上传证明文件至少一个CNPJ 卡片公司名下的公用事业账单电、水带公司名称和地址的银行对账单营业执照公司章程选择联系验证方式公司域名邮箱最快公司电话额外文件点击**“提交”**快速批准技巧使用公司域名邮箱例如adminsuaempresa.com.br而非 Gmail/Hotmail确保 Meta 登记的公司名称与文件上的名称完全一致公司网站必须活跃且可访问文件必须清晰可读PDF 或图片格式文件签发日期应在 90 天内账单和银行对账单时限场景预计时间文件正确 企业邮箱1-3 个工作日文件正确 电话验证3-5 个工作日文件不完整 / 拒绝 重新提交5-14 个工作日常见错误错误解决方案“文件被拒绝”确认文件上的名称与登记名称一致。提交更新的文件“无法验证”尝试其他类型的文件。添加多个文件验证卡住超过 7 天在business.facebook.com/help开支持工单“域名未验证”在域名的 DNS 中添加验证 TXT 记录验证邮件收不到检查垃圾邮件。尝试电话方式完成标志你应该拥有安全中心中验证状态为**“已验证”**绿色徽章可访问渐进式消息限额可升级到 1K、10K、100K 和无限消息限额级别验证后级别发起的会话24 小时如何达到未验证250初始默认第 1 级1.000完成商家验证第 2 级10.0007 天内发送 2 倍当前限额且质量良好第 3 级100.000保持质量和数量第 4 级无限保持稳定的质量设置后检查清单完成全部 10 步后你应该有以下值。填写并存储在.env文件中# # WhatsApp Cloud API - 环境变量# # 第 1 步 - Meta Business SuiteMETA_BUSINESS_ID# Business 账号 ID15 位# 第 2 步 - Meta for Developers 中的应用META_APP_ID# 应用 IDMETA_APP_SECRET# 应用密钥App Settings Basic 中# 第 4 步 - WhatsApp IDWHATSAPP_PHONE_NUMBER_ID# Phone Number ID真实号码的不是测试的WHATSAPP_WABA_ID# WhatsApp Business Account ID# 第 9 步 - 永久令牌WHATSAPP_API_TOKEN# System User 令牌永久# API 配置WHATSAPP_API_VERSIONv21.0WHATSAPP_API_URLhttps://graph.facebook.com# Webhook单独配置WEBHOOK_VERIFY_TOKEN# 你自定义的、用于验证 webhook 的令牌WEBHOOK_URL# 服务器公网 URL必须 HTTPS最终验证运行此命令确认一切正常# 将变量替换为你的真实值curl-XPOST\https://graph.facebook.com/v21.0/${WHATSAPP_PHONE_NUMBER_ID}/messages\-HAuthorization: Bearer${WHATSAPP_API_TOKEN}\-HContent-Type: application/json\-d{ messaging_product: whatsapp, to: NUMERO_DESTINATARIO, type: template, template: { name: hello_world, language: { code: en_US } } }如果你收到包含messages: [{id: wamid.XXXX}]的 JSON则设置已完成。实用链接资源URL官方文档https://developers.facebook.com/docs/whatsapp/cloud-apiAPI 参考https://developers.facebook.com/docs/whatsapp/cloud-api/reference平台状态https://metastatus.comBusiness 支持https://business.facebook.com/help开发者社区https://developers.facebook.com/communityAPI 更新日志https://developers.facebook.com/docs/whatsapp/cloud-api/changelog模板指南https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templatesWebhook 指南https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks下一步配置 webhook 以接收消息。请参阅项目文档中的 webhook 指南。