在当今数字化时代，多渠道客户服务 (Omnichannel) 是每个企业的生存要素。WhatsApp 拥有全球超过 20 亿用户，是您不能忽略的最重要沟通渠道之一。将 WhatsApp 的强大功能与 Chatwoot – 领先的开源 Omnichannel 客户互动平台 – 结合，您企业可以高效、集中且专业地管理数千条客户消息。.
本文将详细指导您逐步集成 WhatsApp Cloud API 到 Chatwoot 按照手动流程 (Manual Flow)。这是让您完全控制数据和配置而不依赖昂贵第三方 (BSP) 的方法。.
为什么使用 WhatsApp Cloud API 与 Chatwoot？
在深入技术细节之前，让我们先看看进行此集成的巨大优势：
- 节省成本： WhatsApp Cloud API 直接托管在 Meta 的基础设施上，消除了以前必须支付给 Twilio 或 MessageBird 等 BSP 的中间费用。.
- 高速度和高稳定性： 直接连接到 Meta 确保您的消息系统具有最低延迟和最高稳定性。.
- 集中管理： Chatwoot 允许您将来自 WhatsApp、Facebook、Email、实时聊天的消息汇总到一个界面，帮助支持人员无需在多个应用之间切换。.
- 自动化： 利用 Chatwoot 的功能，如 Chatbot、自动化规则和预设回复来快速响应客户。.
准备要求 (Prerequisites)
为了使安装过程顺利，您需要准备以下资源：
- Meta 开发者账户: 如果没有，请在 developers.facebook.com. 免费注册。这是您管理连接到 Facebook/Instagram/WhatsApp 生态系统的应用的地方。.
- 有效电话号码: 您需要一个能够接收 SMS 消息或语音通话以进行验证的电话号码。.
- 重要提示： 此电话号码 不得 正在链接到手机上的任何个人 WhatsApp 账户或 WhatsApp Business App。如果有，您必须先在手机上删除 WhatsApp 账户，然后才能用于 API。.
- Facebook Business 账户: 可以访问 business.facebook.com 来管理企业资产。.
步骤 1：设置企业资料 (Business Profile)
第一步是在 Meta 平台上为您的企业创建身份。这有助于 Meta 验证企业并授予访问 WhatsApp API 高级功能的权限。.
- 访问 business.facebook.com.
- 如果您是新手，请创建一个 Business Portfolio （以前称为 Business Manager Account）。.
- 填写企业的完整法律信息，如企业名称、企业电子邮件和地址。提供准确信息将有助于后续的企业验证（Business Verification）过程更快进行，尽管对于基本使用水平，您可能不需要立即验证。.
步骤 2：创建 Facebook 应用
类似于创建技术“连接门户”时，Facebook Developers 上的 App 是存放 API 配置的地方。.
- 访问页面 My Apps 并点击绿色按钮 Create App.
- 在“What do you want your app to do?”屏幕上，选择选项 Other （其他）。点击 下一个.
- 在“Select an app type”屏幕上，选择 Business. 。这是用于管理 Pages、Events 和 WhatsApp Business API 的应用类型。点击 下一个.
- 在“Details”部分：
- App Name: 设置易记的名称，例如“Chatwoot WhatsApp Connect”。.
- App Contact Email: 您的电子邮件。.
- Business Portfolio: 选择您在步骤 1 中创建的 Business 账户。这是使用生产环境 WhatsApp API 的必填步骤。.
- 点击 Create app 以完成。您可能需要输入 Facebook 密码进行确认。.
步骤 3：将 WhatsApp 产品添加到应用
创建 App 后，您将被带到控制面板（App Dashboard）。此时您的 App 还没有任何功能，您需要添加“产品”WhatsApp。.
- 向下滚动找到名为 WhatsApp 的产品列表中的项目。点击按钮 设置.
- Meta 将要求您选择或新建一个 Meta 商业账户. 。请选择您的商业账户。.
- 点击 继续. 。系统将花费几秒钟为您设置 WhatsApp Cloud API 环境。.
步骤 4：创建永久访问令牌 (Permanent Access Token)
这是 最重要的一步 并且最容易混淆。默认情况下，Meta 为您提供一个“临时访问令牌”（Temporary Access Token），有效期仅 24 小时。如果您将此令牌输入 Chatwoot，连接将在一天后断开。您必须创建一个“系统用户”（System User）来获取永久令牌。.
- 访问 商业设置.
- 在左侧菜单中，找到项目 Users > 系统用户.
- 点击按钮 添加. 。将弹出一个弹出窗口。请仔细阅读并接受条款。.
- 为系统用户命名，例如“Chatwoot 管理员”。在部分 系统用户角色, 选择 管理员. 。点击 创建系统用户.
- 创建完成后，您需要为此用户分配资产（App）。点击按钮 添加资产.
- 在弹出的窗口中，选择项目 应用, ,然后选择您在步骤 2 中创建的应用程序名称。.
- 启用选项 完全控制 （管理应用）以授予全部权限。点击 保存更改.
- 现在，返回系统用户列表页面，选择您刚创建的用户。点击按钮 生成新令牌.
- 从下拉列表中选择您的应用。.
- 权限（Permissions）： 您需要找到并精确勾选以下 3 个权限（非常重要）：
whatsapp_business_messaging: 允许发送和接收消息。.whatsapp_business_management: 允许管理 WhatsApp 企业信息。.whatsapp_business_manage_events: 允许接收 webhook 事件（收到的消息、发送状态等）。.
- 点击 Generate Token. 将显示一个长字符串代码。. 请立即复制并安全存储它, 因为 Facebook 不会再次显示此代码。这就是您将输入到 Chatwoot 的“API Key”。.
步骤 5：配置 WhatsApp 电话号码
您需要声明实际用于与客户聊天的电话号码。.
- 返回 developers.facebook.com 上的 App Dashboard 页面。.
- 在左侧菜单中，选择 WhatsApp > API Setup.
- 滚动到部分 步骤 5：添加电话号码, 点击按钮 添加电话号码.
- 填写 WhatsApp 资料信息：
- 显示名称： 客户看到的名字（例如：ABC 客户服务）。.
- 类别： 选择合适的业务领域。.
- 输入您的电话号码并选择验证方法（SMS 或语音通话）。.
- 输入 OTP 代码完成验证。.
- 成功后，您将看到您的电话号码出现在列表中。在此，复制两个重要参数： 电话号码 ID 和 WhatsApp 企业账户 ID.
步骤 6：连接到 Chatwoot
现在是时候在 Chatwoot 界面上将一切连接起来了。.
- 使用管理员权限登录您的 Chatwoot 系统。.
- 进入 设置 （设置 – 齿轮图标） > 收件箱 > 添加收件箱.
- 选择图标 WhatsApp.
- 在 API Provider 部分，选择 WhatsApp Cloud （注意不要选错 Twilio 或 360Dialog）。.
- 填写配置表单：
- Phone Number： 输入已验证的电话号码（仅输入数字，包括国家代码，没有加号或空格。例如：84912345678）。.
- Phone Number ID： 粘贴您在步骤 5 中获取的 ID。.
- Business Account ID： 粘贴您在步骤 5 中获取的 ID。.
- API Key： 粘贴代码 Permanent Access Token 您在步骤 4 中创建并保存的。.
- 点击 Create WhatsApp Channel.
- 下一步，选择将管理此收件箱的员工（Agents）。点击 Add agents.
- 最后的屏幕将为您提供 Webhook URL 和 Webhook Verify Token. 。请保持此屏幕打开或复制它们。.
步骤 7：配置 Webhook
在步骤 6 中输入 Token 仅帮助 Chatwoot 发送 消息。为了让 Chatwoot 接收 客户发送的消息，您需要在 Meta 声明 Webhook 地址。.
- 返回页面 Facebook App Dashboard.
- 在左侧菜单中，在部分 WhatsApp > 选择 Configuration.
- 找到标题为的部分 Webhook, 点击按钮 Edit.
- 一个弹出窗口将出现：
- 回调 URL： 粘贴 Chatwoot 提供的 Webhook URL（通常形式为
https://domain-cua-ban.com/webhooks/whatsapp/...). - 验证令牌： 粘贴来自 Chatwoot 的验证令牌。.
- 回调 URL： 粘贴 Chatwoot 提供的 Webhook URL（通常形式为
- 点击 验证并保存. 。如果信息正确，窗口将关闭并显示绿色对勾。如果报错，请检查 URL 是否可以公开访问（如果您在本地安装 Chatwoot，则需要使用 ngrok）。.
- 还没完！您需要注册想要接收的事件。在部分 Webhook 字段, 点击 管理.
- 在列中 订阅, 找到行 messages 并选中它。这是接收消息内容的必选事件。此外，您可以选择
message_deliveries,message_reads来跟踪已发送/已读状态。. - 点击 完成.
完成并测试
恭喜！您已完成将 WhatsApp Cloud API 集成到 Chatwoot 的过程。现在，系统已准备好运行。.
检查方法：
- 使用另一个个人手机号码，向您刚刚安装的企业手机号码发送“Hello”消息。.
- 打开 Chatwoot 仪表板，您将看到新消息出现在 WhatsApp 收件箱中。.
- 从 Chatwoot 尝试回复，个人手机将立即收到响应。.
运营时的一些注意事项 (Troubleshooting)
- 24 小时规则： WhatsApp 实施 24 小时会话政策。如果客户在过去 24 小时内未给您发消息，您无法自由发送消息给它们。您必须使用 模板消息 （预先获得 Meta 批准的样本消息）来开始对话。.
- 更新令牌： 如果您误用了临时令牌，连接将在 24 小时后丢失。请进入 Chatwoot > 设置 > 收件箱 > WhatsApp > 配置，并更新新的永久令牌。.
- 不接收消息错误： 请检查 Webhook 部分是否已订阅事件
messages。这是最常见的错误。.
希望这份指南能帮助您掌握Chatwoot上的WhatsApp通信渠道。祝您的企业借助新的客户服务系统强劲增长！
