怎么连接 WhatsApp 账号？Business App 与个人版扫码配对登录及连接异常排查

概览

支持 WhatsApp Business App 和 WhatsApp Messenger（个人版）账号，推荐使用 Business App 开展客户沟通。

WAthink 提供的第三方连接服务采用 WhatsApp 协议连接方式，属于非官方接入，不代表 WhatsApp 或 Meta 官方授权或背书。目前不提供 WhatsApp Business Platform（Meta 官方 API）接入。

工作区必须先连接号码，之后才能收发 WhatsApp 消息。平台使用 WhatsApp 协议连接：像 WhatsApp Web 一样扫描二维码（或输入 8 位配对码）即可连接一个 WhatsApp 应用账号，由随包自带的辅助服务（连接运行服务，位于 node/ 目录）代表你保持连接并收发消息。

整个产品——收件箱、广播、营销活动、流程、模板、自动回复、AI 助手——都会围绕这一通道运行。该通道接入方式、服务费用与额度按所选方案确认；并且不需要配置 Webhook，入站消息由辅助服务直接投递。

平台全局同一时间只有一个生效通道，由管理员在 Admin → Settings → System Message Setting（Active messaging engine）中选择；当前生效通道为 WhatsApp 协议连接。各工作区随后在 Devices 页面为号码完成配对；Devices 页面只显示 WhatsApp 协议连接接入面板。

设备（Devices）页面

所有与通道相关的操作都在顶部导航的 Devices 页面。它是工作区所有连接的统一入口，并且只显示 WhatsApp 协议连接接入面板：

• 左侧是状态筛选栏（All、Connected、Disconnected、Needs re-pair、Failed）与地区筛选，右侧是已配对手机卡片网格。
• 页面标题为 My devices；标题旁的小计数器显示当前已连接的号码数量。
• 点击 Add device 即可进入 WhatsApp 协议连接配对流程（左侧是二维码区域，右侧是简短表单）。

连接步骤

WhatsApp 协议连接可以像 WhatsApp Web 一样把已授权的 WhatsApp 应用账号（Business App / 个人版）作为设备接入。配对与收发由随包提供的辅助服务（连接运行服务，位于 node/ 目录）处理。该辅助服务必须持续运行，否则设备无法保持在线、消息也无法收发。该通道不需要配置任何 Webhook——消息由辅助服务直接投递。

准备（管理员）：启动辅助服务并让 WAthink 指向它

辅助服务地址是平台级设置，由管理员设置一次。

1. 启动服务。进入 node/ 目录，运行 npm install，再运行 node index.js。默认监听 node/.env 中 PORT 指定的端口（默认 8888）。该服务必须保持运行。
2. 在 node/.env 中，把 APP_DOMAIN_NAME 设为你的 WAthink 网址（例如 https://your-domain.com），并把 NODE_WEBHOOK_TOKEN 设为一个共享密钥。
3. 在 WAthink 中，把同一个共享密钥填入对应的管理后台设置。两处必须完全一致，否则 WAthink 会拒绝该服务的状态更新。
4. 进入 Admin → Settings → System Message Setting，选择 Unofficial API 卡片，把服务地址粘贴到 Server URL（例如 http://localhost:8888），保存。

无需配置 Webhook。辅助服务已经通过 APP_DOMAIN_NAME 知道你的 WAthink 网址，会自动回传配对与连接状态；消息也由辅助服务直接投递。

配对号码（工作区）

1. 在 Devices 页面选择 WhatsApp 协议连接，打开 Add device 流程。
2. 输入要绑定的 WhatsApp 号码（含国家区号）。可选填 Device label（例如 "Sales line"）；也可以为该设备单独覆盖辅助服务地址，但通常留空使用平台默认值。
3. 点击 Generate QR。WAthink 会创建一次配对会话并显示二维码。
4. 在对应的手机应用（WhatsApp Business App 或 WhatsApp Messenger）中打开 Settings → Linked Devices → Link a Device，扫描显示的二维码。如果你更愿意，也可以请求 8 位配对码，在手机上输入该码完成配对。
5. 页面每隔几秒检查一次，依次经过 QR generated → Syncing data → Ready。号码连接成功后，设备状态会自动变为 Connected（已连接）。

重新配对与断开行为

• 重新配对（Relink）：如果 WhatsApp 断开了链接（或你在手机的 Linked Devices 页面解绑），设备会显示为未连接。打开该设备重新配对即可。
• 断开（Disconnect）：断开连接会干净地结束会话，下一次连接会从零开始重新配对。
• 多号码：可以配对多个号码。WAthink 会在所有活跃设备之间分摊发送，因此某个设备被禁或某台手机没电不会拖住整个队列。

按 WhatsApp 当前的关联设备要求保持账号有效。连接中断时，先核对手机登录、关联设备授权与工作台连接状态，再决定是否重新配对。

请认真对待协议连接的账号风险。扫码绑定号码使用的是 WhatsApp Web 技术；借此进行高频营销可能导致号码被封。请使用专用号码、缓慢养号，并配合发送规则与每号代理使用。

优点：通过手机关联设备配对；支持 Business App 与个人版账号。缺点：需要你自行托管辅助服务、封号风险更高、没有原生模板审核；用于批量营销违反 WhatsApp 服务条款。

字段参考

连接状态说明

每个连接都会显示实时状态。平台把 WhatsApp 协议连接的信号简化为少量状态：

• 辅助服务会定期上报；约 90 秒未收到某设备的心跳即标记为未连接，确保页面状态与真实情况一致。
• 重新配对（Relink）会结束当前会话并重新生成二维码或配对码；断开（Disconnect）后下一次连接会从零开始重新配对。

故障排查

二维码无法扫描 / 配对始终不完成

• 确认辅助服务正在运行，且 Server URL 可访问。用浏览器打开该地址，应当能访问服务而不是连接错误。
• 二维码过期很快 — 让 WAthink 重新生成（页面每隔几秒刷新一次），不要扫描已经失效的图片。
• 确认手机有网络，且是在 Linked Devices → Link a Device 下扫码，而不是普通聊天界面。
• 如果状态显示 "Mismatch" 或 "Pair failed"，先断开连接（结束会话），再从零重新配对。

辅助服务未运行 / 消息发不出去

• 重启服务（在 node/ 下运行 node index.js），并查看控制台错误。辅助服务必须持续运行，停止后所有设备都会掉线、消息无法收发。
• 核对两侧共享密钥是否一致：node/.env 中的 NODE_WEBHOOK_TOKEN 必须等于 WAthink 中对应的管理后台设置。不一致会导致 WAthink 拒绝所有状态更新，连接状态永远不刷新。
• 确认 node/.env 中的 APP_DOMAIN_NAME 指向你的 WAthink 网址，以便服务能回调。
• 确认设备保持在线：设备列表显示 Connected（已连接）才可能发送；辅助服务停止或手机长期离线都会让设备掉线。
• 按 WhatsApp 当前的关联设备要求保持账号有效。连接中断时，先核对手机登录、关联设备授权与工作台连接状态，再决定是否重新配对。

设备被判掉线（约 90 秒无心跳）

• 辅助服务会定期为每台设备上报心跳；约 90 秒未收到心跳，WAthink 会把设备标记为未连接，避免页面显示与实际不符。
• 先确认辅助服务与配对手机都有网络，再等待下一次心跳；若状态一直不恢复，打开设备重新扫码或输入配对码。

代理不可达时发送失败（fail-closed）

• 如为该号码配置了代理：代理不可达时发送会直接失败（fail-closed），不会回退直连。
• 请先在代理隔离设置中确认代理可达，再重试发送；不要在未确认代理状态时反复重试。

会话并发冲突

• 同一号码不要在多个位置同时登录：如果该号码又在另一台设备、另一个 WAthink 实例或别的 WhatsApp Web 会话中扫码配对，原有会话会被顶掉，设备随即变为未连接。
• 同一工作区不要为同一号码重复添加多张设备卡片；确认重复卡片已删除后再重新配对。
• 出现冲突后，删除冲突设备，使用「重新配对」重新扫码或输入配对码即可恢复；必要时重启辅助服务并再次确认设备状态为 Connected（已连接）。

消息收不到

• 确认设备显示 Connected（已连接）且辅助服务正在运行；入站消息由辅助服务投递，无需手动配置 Webhook。
• 检查配对手机是否正常联网，并确认辅助服务日志中没有报错。

下一步

号码连接完成后，前往 仪表盘 确认消息在流动并查看 KPI。要了解限制与功能门控，请阅读 套餐与免费试用。继续复查配置与团队交接。