WhatsApp user_preferences webhook: when a customer stops or resumes marketing messages
The user_preferences webhook tells a business that a WhatsApp user stopped or resumed its marketing messages through the Offers and announcements setting. Each event carries category marketing_messages, a value of stop or resume, a detail sentence, the user's wa_id and BSUID, and a Unix timestamp. Interested and Not interested feedback in the same setting does not trigger it.
easyCoexistence connects your WhatsApp Business app number to Meta's Cloud API through Coexistence, so your AI and automations work on the number you keep in the app.
Values a preference can take: stop and resume, both in the marketing_messages category.
The failed-status code for a marketing template sent to a user who stopped your marketing messages.
Where Meta sends user_preferences: it is not a field a WhatsApp Business Account or number can override.
The permission an app needs for webhooks other than messages and calls, user_preferences included.
What triggers the user_preferences webhook?
A customer opening Offers and announcements in WhatsApp and choosing to stop, or later to resume, marketing messages from your business. Those two actions are the only triggers. The same setting also lets a customer mark Interested or Not interested, and that feedback sends no webhook, although Not interested can lower the per-user marketing limit between you and that customer and opens a second screen offering to stop marketing messages altogether. Only if they then tap stop does user_preferences fire.
What does the payload contain?
A user_preferences array next to a contacts array, under the field name user_preferences. The timestamp here is an integer, while status webhooks send theirs as a string. wa_id is left out when the customer uses a username and their phone number cannot be shared, user_id when business-scoped user IDs are not enabled for your business, and parent_user_id unless parent BSUIDs are on. Meta's example of a resume:
{
"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"
}
]
}
]
}What should your system do with a stop?
Record it against the customer and keep it out of every marketing send until a resume arrives. The detail field reads either "User requested to stop marketing messages" or "User requested to resume marketing messages", but value is what code should read.
- Store the preference by BSUID and by phone number, since either can be missing on a given event.
- Exclude the customer from marketing template sends; Meta would refuse them anyway with 131050.
- Apply it per customer only: Meta never applies a preference at the parent BSUID level.
- On resume, lift the exclusion, and keep your own opt-in record as Meta's opt-in policy requires.
What if user_preferences never reaches your server?
Meta enforces the stop anyway, so a missing webhook costs you a failed send, not a policy breach. When you send a marketing template to someone who stopped, the API accepts the request, does not send the message, and triggers a status webhook with status failed, code 131050 and the title "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business". Treat that failure exactly like a stop event: record it and suppress further marketing sends to that customer.
How does this work on a number connected through easyCoexistence?
user_preferences is not one of the fields Meta allows a destination override for, so Meta delivers it only to the default callback of the app that subscribed to the account. For a number connected through easyCoexistence, that app is easyCoexistence's, and it does not subscribe to user_preferences today, so the event does not reach a direct destination or a Forward URL. The 131050 failed status does, because it travels on the messages field.
If your AI sends marketing templates with send_template, keep the stop list in your own system and check it first: easyCoexistence does not keep one.
Common mistakes
- Treating Not interested as a stop. It sends no webhook and does not stop delivery, though it can lower the per-user marketing limit for that customer.
- Keying preferences on wa_id alone. It is omitted for customers with a username whose number cannot be shared; store the BSUID too.
- Applying a stop to everyone under a parent BSUID. Meta applies preferences per user, never at the parent level.
- Retrying after 131050 instead of recording it as a stop. Every retry fails the same way.
Marketing templates sent through it go out on your own WhatsApp Business Account, and the failed statuses that report a stopped customer reach your server directly or as signed forwards. US$ 9 down to US$ 0.75 per number per month, falling as you add numbers, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Does a stop also block replies to the customer's own messages?
Meta's documentation describes the stop as covering marketing messages, and the error it returns names marketing messages. Replies to a customer who wrote to you are service messages, a different category.
Does blocking the business trigger user_preferences?
No. The webhook triggers only on stop and resume in the Offers and announcements setting. Blocking is a separate action and is not reported on this field.
Does a resume count as opt-in?
It means the customer chose to receive your marketing messages again. Your own opt-in obligations under Meta's policy still apply, so keep the record of how and when that customer agreed to hear from you.
Which webhook field do I subscribe to?
user_preferences, in the App Dashboard under WhatsApp > Configuration, on the app subscribed to the WhatsApp Business Account. It is a separate field from messages and needs whatsapp_business_management.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialVerified on