WhatsApp user_preferences Webhook:客户停止或恢复营销消息时
user_preferences Webhook 告诉企业,WhatsApp 用户通过「优惠和公告」设置停止或恢复了其营销消息。每个事件包含类别 marketing_messages、取值 stop 或 resume、一句详情说明、用户的 wa_id 与 BSUID,以及 Unix 时间戳。同一设置中的「感兴趣」和「不感兴趣」反馈不会触发该事件。
easyCoexistence 通过 Coexistence 将您保留在 WhatsApp Business 应用中的号码连接至 Meta 的 Cloud API,因此您的 AI 与自动化可以在您于应用中保留的号码上运行。
可用的偏好取值为 stop 与 resume,均属于 marketing_messages 类别。
营销模板发送给已停止接收营销消息的用户时,失败状态所使用的代码。
Meta 发送 user_preferences 的位置:它是 WhatsApp Business Account 或号码都无法覆盖的字段。
应用订阅 messages 和 calls 以外的 Webhook 所需的权限,user_preferences 也包括在内。
什么会触发 user_preferences Webhook?
客户在 WhatsApp 中打开「优惠和公告」并选择停止,或之后选择恢复接收您企业的营销消息。这两个操作是唯一的触发条件。同一设置还允许客户标记「感兴趣」或「不感兴趣」,此类反馈不发送 Webhook。不过,「不感兴趣」可能会降低您与该客户之间的每位用户营销消息限额,并会弹出第二个界面,询问是否完全停止营销消息。只有客户随后点击停止,user_preferences 才会触发。
负载包含什么?
数据以 user_preferences 字段名发送,内含一个 user_preferences 数组,与 contacts 数组并列。这里的时间戳是整数,而状态 Webhook 的时间戳则以字符串形式发送。当客户使用用户名且其手机号码无法共享时,wa_id 会被省略;当企业未启用业务范围用户 ID 时,user_id 会被省略;除非启用了父级 BSUID,否则 parent_user_id 会被省略。以下是 Meta 给出的恢复示例:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824"
}
],
"user_preferences": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824",
"detail": "User requested to resume marketing messages",
"category": "marketing_messages",
"value": "resume",
"timestamp": 1731705721
}
]
},
"field": "user_preferences"
}
]
}
]
}收到停止后,您的系统应如何处理?
将其记录在该客户名下,并在收到恢复事件之前,将其排除在所有营销发送之外。detail 字段会显示「User requested to stop marketing messages」或「User requested to resume marketing messages」,但代码应读取的是 value。
- 按 BSUID 和手机号码分别存储偏好设置,因为某条事件中两者可能缺失其一。
- 将该客户排除在营销模板发送之外,否则 Meta 会以 131050 拒绝发送。
- 仅按单个客户生效:Meta 从不在父级 BSUID 层面应用偏好设置。
- 收到恢复事件后,解除排除,并按 Meta 的选择加入政策要求保留您自己的选择加入记录。
如果 user_preferences 从未到达您的服务器怎么办?
无论如何,Meta 都会执行停止,因此漏收 Webhook 只会导致一次发送失败,而不会构成政策违规。当您向已停止的客户发送营销模板时,API 会接受请求但不会发送消息,并触发一个状态 Webhook,其状态为 failed,代码为 131050,标题为「Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business」。请将此失败与停止事件完全同等处理:记录它,并停止向该客户发送任何后续营销消息。
通过 easyCoexistence 连接的号码,情况如何?
user_preferences 不在 Meta 允许覆盖目标地址的字段之列,因此 Meta 只会将其投递至订阅该账户的应用的默认回调。对于通过 easyCoexistence 连接的号码,该应用是 easyCoexistence 的应用,而目前它并未订阅 user_preferences,因此该事件不会到达直接目标地址或转发 URL。131050 失败状态会到达,因为它通过 messages 字段传输。
如果您的 AI 使用 send_template 发送营销模板,请在您自己的系统中保留停止名单并先行检查:easyCoexistence 不保存此名单。
常见错误
- 将「不感兴趣」视为停止。它不会发送 Webhook,也不会停止投递,但可能会降低该客户的每位用户营销消息限额。
- 仅以 wa_id 作为偏好设置的键。对于使用用户名且手机号码无法共享的客户,wa_id 会被省略,因此请同时存储 BSUID。
- 将停止应用于父级 BSUID 下的所有人。Meta 按用户应用偏好设置,从不在父级层面应用。
- 收到 131050 后重试,而不是将其记录为停止。每次重试都会以同样的方式失败。
通过它发送的营销模板将由您自己的 WhatsApp Business Account 发出,而报告客户已停止接收的失败状态会直接或以签名转发的方式送达您的服务器。每个已连接号码每月 US$ 9 起,号码越多单价越低,最低降至 US$ 0.75,并提供前 3 天免费试用。
常见问题
停止是否也会阻止回复客户自己发来的消息?
Meta 的文档将停止描述为涵盖营销消息,其返回的错误也明确指出营销消息。对曾写信给您的客户的回复属于服务消息,是另一类别。
屏蔽企业是否会触发 user_preferences?
不会。该 Webhook 仅在「优惠和公告」设置中的停止与恢复时触发。屏蔽是一项独立操作,不会在此字段中报告。
恢复是否算作选择加入?
这表示客户选择再次接收您的营销消息。Meta 政策规定的您自己的选择加入义务仍然适用,因此请保留该客户何时、以何种方式同意接收您联系的记录。
我应该订阅哪个 Webhook 字段?
user_preferences,位于应用控制台的 WhatsApp > Configuration 下,即订阅 WhatsApp Business Account 的应用。它与 messages 是独立字段,并需要 whatsapp_business_management 权限。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间