account_update Webhook 及所有断开原因
account_update 用于报告连接状态变化。其 event 字段说明发生了什么;如果是移除,disconnection_info.reason 会说明原因。这个原因决定号码能否恢复,还是已经永久失效。
应用从账户卸载时 Meta 发送的 event。
移除操作可能携带的明确断开原因。
主要设备的非活动时限,会以 PRIMARY_INACTIVITY 传递。
account_update 会携带哪些事件?
应用从 WhatsApp Business 账户卸载时,会发送 PARTNER_REMOVED。这是权威的断开信号,值得据此构建逻辑,而不是根据某一字段变为 false 来推断断开。
号码完全退出时,会发送 ACCOUNT_OFFBOARDED。先前被移除的连接恢复时,会发送 ACCOUNT_RECONNECTED。强制执行相关事件包括 ACCOUNT_RESTRICTION 和 ACCOUNT_VIOLATION,也包括名称含有 DISABLED 或 BAN 的事件。
验证和审批结果也会在这里传递,event 名称会含有 VERIFIED 或 APPROVED。处理程序应根据 event 名称进行分支处理;无法识别的事件应视为信息,而不是因此失败,因为 Meta 可能随时添加事件。
断开原因有哪些?
共有 6 种,含义差异很大。
PRIMARY_INACTIVITY 是大约 14 天的规则:主要设备上的 WhatsApp Business 应用未被打开。可以恢复,而且是最常见的情况。
COMPANION_INACTIVITY 表示配套设备处于同类非活动状态,时限更长,约为 30 天。
BUSINESS_DOWNGRADE 表示号码切回消费者使用的 WhatsApp 应用。由于 Coexistence 需要 WhatsApp Business 应用,这会结束 Coexistence。
CHANGE_NUMBER 表示电话号码本身发生变化。USER_RE_REGISTERED 表示号码在新设备上重新注册。ACCOUNT_DISCONNECTED 表示客户主动断开连接,或连接因强制执行而被断开。
断开时还会同时传递 disconnection_info.initiated_by,用于说明操作是由人员还是系统发起。
为什么原因比事件更重要?
因为单独看到 PARTNER_REMOVED,并不能告诉您应该采取什么行动。
如果号码因 PRIMARY_INACTIVITY 被移除,它还会回来:企业打开应用并重新连接后,一切都会恢复。若把这种情况当成客户离开,就会向仍然是客户的人发送取消邮件。
因 BUSINESS_DOWNGRADE 或 ACCOUNT_DISCONNECTED 被移除,是另一种情况。若把它当成暂时断开,连接就可能永远停留在待处理状态。
如果移除事件完全没有原因,initiated_by 就是备用信号:人员执行的移除表示有意操作,而无法解释的系统移除则不能这样判断。与其之后通过支持对话处理,不如在代码中区分这两种情况。
常见错误
- 把每一次 PARTNER_REMOVED 都当成同一种情况。原因可以区分 14 天的暂时沉寂与已经离开的客户。
- 根据字段变为 false 推断断开,而不是根据这一事件判断。这会产生误报。
- 遇到无法识别的 event 名称就失败。Meta 会添加事件,处理程序应跳过无法识别的事件。
EasyCoexistence 会按名称处理这些情况,把原因记录在连接时间线中,并区分可恢复的非活动移除与确实已经失效的号码。
常见问题
PARTNER_REMOVED 是永久的吗?
通常不是。大多数事件会带有 PRIMARY_INACTIVITY,表示应用一段时间未打开;重新连接后,一切都会恢复。
重新连接会恢复我的 Webhook 目标吗?
不会,这正是容易忽略的地方。目标是应用订阅上的 override,应用卸载时它也会被卸载,因此必须重新应用。
COMPANION_INACTIVITY 是什么?
表示配套设备处于非活动状态,而不是主要设备;时限更长,约为 30 天。
没有原因时,我还能收到这一事件吗?
可以。这种情况下,disconnection_info.initiated_by 是唯一能判断操作是否出于意图的信号。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间